@stinkycomputing/sesame-editor-api 1.0.0-alpha.1

package/dist/helpers.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Serialization helper utilities for plugin authors.
+ *
+ * These work with minimal structural interfaces rather than importing from
+ * @xyflow/react, so this package remains free of a React dependency.
+ * ReactFlow's Node and Edge satisfy the MinimalNode / MinimalEdge contracts.
+ */
+import type { SesameNodeData } from './node-types';
+export interface MinimalNode {
+    id: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    data: unknown;
+}
+export interface MinimalEdge {
+    source: string;
+    sourceHandle?: string | null;
+    target: string;
+    targetHandle?: string | null;
+    data?: unknown;
+}
+export declare function getData<TNode extends MinimalNode>(node: TNode): SesameNodeData;
+export declare function nodeProps<TNode extends MinimalNode>(node: TNode): Record<string, unknown>;
+export declare function nodeMeta<TNode extends MinimalNode>(node: TNode): {
+    x: number;
+    y: number;
+    collapsed?: boolean;
+};
+export declare function getNodesByCategory<TNode extends MinimalNode>(nodes: TNode[], category: string): TNode[];
+/**
+ * Find the node connected to a specific input handle on targetNodeId.
+ * Returns the source node, its output handle index, and the built connectionId.
+ */
+export declare function findSourceConnection<TNode extends MinimalNode, TEdge extends MinimalEdge>(edges: TEdge[], nodes: TNode[], targetNodeId: string, targetHandleId: string): {
+    node: TNode;
+    handleIdx: number;
+    connectionId: string;
+} | undefined;
+/** Find all edges going into targetNodeId on ports of portType. */
+export declare function findInputConnectionsByType<TNode extends MinimalNode, TEdge extends MinimalEdge>(edges: TEdge[], nodes: TNode[], targetNodeId: string, portType: string): {
+    connectionId: string;
+    inputIdx: number;
+}[];

package/dist/helpers.js

@@ -0,0 +1,65 @@
+/**
+ * Serialization helper utilities for plugin authors.
+ *
+ * These work with minimal structural interfaces rather than importing from
+ * @xyflow/react, so this package remains free of a React dependency.
+ * ReactFlow's Node and Edge satisfy the MinimalNode / MinimalEdge contracts.
+ */
+// ---------------------------------------------------------------------------
+// Node data accessors
+// ---------------------------------------------------------------------------
+export function getData(node) {
+    return node.data;
+}
+export function nodeProps(node) {
+    return getData(node).properties;
+}
+export function nodeMeta(node) {
+    return {
+        x: node.position.x,
+        y: node.position.y,
+        collapsed: getData(node).collapsed || false,
+    };
+}
+export function getNodesByCategory(nodes, category) {
+    return nodes.filter(n => getData(n).def.category === category);
+}
+// ---------------------------------------------------------------------------
+// Edge traversal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Find the node connected to a specific input handle on targetNodeId.
+ * Returns the source node, its output handle index, and the built connectionId.
+ */
+export function findSourceConnection(edges, nodes, targetNodeId, targetHandleId) {
+    const edge = edges.find(e => e.target === targetNodeId && e.targetHandle === targetHandleId);
+    if (!edge)
+        return undefined;
+    const srcNode = nodes.find(n => n.id === edge.source);
+    if (!srcNode)
+        return undefined;
+    const handleIdx = parseInt((edge.sourceHandle || '').replace('out-', ''), 10);
+    const data = getData(srcNode);
+    const outputs = (data.dynamicOutputs ?? data.def.outputs);
+    const port = outputs[handleIdx];
+    const portName = port?.name || '';
+    const connectionId = `${data.properties.id}${portName}`;
+    return { node: srcNode, handleIdx, connectionId };
+}
+/** Find all edges going into targetNodeId on ports of portType. */
+export function findInputConnectionsByType(edges, nodes, targetNodeId, portType) {
+    const targetNode = nodes.find(n => n.id === targetNodeId);
+    if (!targetNode)
+        return [];
+    const data = getData(targetNode);
+    const inputs = (data.dynamicInputs ?? data.def.inputs);
+    const results = [];
+    inputs.forEach((port, i) => {
+        if (port.type !== portType)
+            return;
+        const conn = findSourceConnection(edges, nodes, targetNodeId, `in-${i}`);
+        if (conn)
+            results.push({ connectionId: conn.connectionId, inputIdx: i });
+    });
+    return results;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './node-types';
+export * from './plugin';
+export * from './helpers';

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './node-types';
+export * from './plugin';
+export * from './helpers';

package/dist/node-types.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Core node type definitions shared between the config editor and all plugins.
+ * Plugins import these types to describe their own node types.
+ */
+export type MetadataFormat = 'json' | 'protobuf/transport-status' | 'protobuf/audio-state' | 'protobuf/transport-control' | 'protobuf/audio-control';
+export interface PortDef {
+    /** Display label shown next to the handle. */
+    label: string;
+    /**
+     * Connection-type string used for validation.
+     * Only ports with the same type can be connected.
+     * Examples: "source/device", "audio/raw", "video/composition", …
+     */
+    type: string;
+    /** Optional port name used during serialization to build "connectionId" strings. */
+    name?: string;
+    /** Optional max outgoing connections allowed from this output port. */
+    maxConnections?: number;
+}
+export type MetadataDirection = 'emit' | 'receive';
+export interface MetadataDef {
+    /** Unique identifier for this metadata channel, e.g. 'transport-status', 'audio-state'. */
+    id: string;
+    /** Human-readable label shown in the node UI. */
+    label: string;
+    /** Whether this node emits or receives this metadata. */
+    direction: MetadataDirection;
+    /**
+     * Port type string used for connection matching.
+     * Convention: 'metadata/<id>', e.g. 'metadata/transport-status'.
+     */
+    portType: string;
+    /** Wire format for the payload. Maps to DataType in sesame/v1/wire/wire.proto. */
+    format: MetadataFormat;
+}
+export type WidgetType = 'text' | 'number' | 'slider' | 'toggle' | 'combo' | 'chromacolor';
+export interface WidgetDef {
+    type: WidgetType;
+    label: string;
+    /** Key into the node's `properties` record. */
+    property: string;
+    options?: {
+        min?: number;
+        max?: number;
+        step?: number;
+        precision?: number;
+        values?: string[] | Record<string, string>;
+        getDisplayText?: (value: number) => string;
+        getEditValue?: (value: number) => number;
+        parseEditValue?: (edited: number) => number;
+        cbProperty?: string;
+        crProperty?: string;
+    };
+}
+export interface NodeTypeDef {
+    /** Unique type key, e.g. "source/decklink". */
+    type: string;
+    /** Human-readable title shown in the node header. */
+    title: string;
+    /**
+     * Category used during serialization grouping.
+     * Open string to allow plugin-defined categories alongside built-in ones.
+     */
+    category: string;
+    /** Header background color (CSS). */
+    color: string;
+    /** Label shown in the context menu group heading. */
+    menuGroup: string;
+    /** Sort order for the context menu group (lower = higher). */
+    menuOrder: number;
+    /** Sort order within the menu group (lower = higher). Defaults to 0 when omitted. */
+    menuItemOrder?: number;
+    /** Input port definitions (left-hand handles). */
+    inputs: PortDef[];
+    /** Output port definitions (right-hand handles). */
+    outputs: PortDef[];
+    /** Inline widget controls rendered inside the node body. */
+    widgets: WidgetDef[];
+    /** Default property values for a newly created node. */
+    defaultProperties: Record<string, unknown>;
+    /**
+     * Metadata channels this node exposes — status streams it emits or
+     * control streams it receives. Each entry generates a port with the
+     * given portType so it can be wired to an output's metadata tracks.
+     */
+    metadata?: MetadataDef[];
+    /** Whether this node supports dynamic ports – ports added/removed based on connections. */
+    dynamicPorts?: boolean;
+    /**
+     * Optional key that selects a specialised property-panel editor instead of
+     * the default widget list.
+     */
+    customEditor?: string;
+    /**
+     * Optional callback invoked when the count of connected dynamic input ports changes.
+     * Return partial properties to merge, or undefined for no change.
+     *
+     * @param properties     Current node properties.
+     * @param dynamicInputCount  Total dynamic input count including the trailing empty slot.
+     * @param inputConnectionIds Resolved connection-ID string for each dynamic input slot
+     *                           (undefined when the slot is unconnected).
+     */
+    onDynamicPortsChanged?: (properties: Record<string, unknown>, dynamicInputCount: number, inputConnectionIds: (string | undefined)[]) => Partial<Record<string, unknown>> | undefined;
+}
+/** Stored in each React Flow node's `data` field. */
+export interface SesameNodeData {
+    /** Index signature for React Flow compatibility. */
+    [key: string]: unknown;
+    /** Reference to the declarative node definition. */
+    def: NodeTypeDef;
+    /** Mutable property bag (widget values, id, etc.). */
+    properties: Record<string, unknown>;
+    /** Whether the node body is collapsed. */
+    collapsed?: boolean;
+    /** Dynamic input ports (used for nodes with `dynamicPorts`). */
+    dynamicInputs?: PortDef[];
+    /** Dynamic output ports (used for nodes with `dynamicPorts`). */
+    dynamicOutputs?: PortDef[];
+}

package/dist/node-types.js

@@ -0,0 +1,5 @@
+/**
+ * Core node type definitions shared between the config editor and all plugins.
+ * Plugins import these types to describe their own node types.
+ */
+export {};

package/dist/plugin.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Plugin interface types for the Sesame config editor.
+ *
+ * TNode / TEdge are generic so this package does not depend on @xyflow/react.
+ * In practice the config-editor and all plugins instantiate them as
+ * Node and Edge from @xyflow/react.
+ */
+import type { SesameConfig } from '@stinkycomputing/sesame-interop';
+import type { NodeTypeDef, PortDef } from './node-types';
+type ISesameConfig = SesameConfig.ISesameConfig;
+export interface NodeFactory<TNode = unknown, TEdge = unknown> {
+    /**
+     * Create a React Flow node. Registers the node ID for collision detection
+     * and generates an empty-ID warning if `id` is falsy.
+     */
+    makeNode(id: string, type: string, position: {
+        x: number;
+        y: number;
+    }, properties: Record<string, unknown>, collapsed?: boolean, extraInputs?: PortDef[], extraOutputs?: PortDef[]): TNode;
+    /** Create a React Flow edge. */
+    edge(sourceId: string, sourceHandle: string, targetId: string, targetHandle: string): TEdge;
+    /** Find the handle ID for an output port matching portType (and optional portName). */
+    findOutputSlot(nodes: TNode[], nodeId: string, portType: string, outputName?: string): string | null;
+    /** Find the handle ID for the nth input port matching portType. */
+    findInputSlot(nodes: TNode[], nodeId: string, portType: string, nthOfType?: number): string | null;
+    /** Read _meta position from a config object, or fall back to a grid position. */
+    pos(obj: unknown, fallbackX: number, fallbackIdx: number): {
+        x: number;
+        y: number;
+    };
+    /** Read _meta collapsed flag from a config object. */
+    collapsed(obj: unknown): boolean;
+    /** Horizontal spacing between node columns. */
+    readonly X_OFFSET: number;
+}
+export interface CoreNodeMaps<TNode = unknown> {
+    /** All source nodes keyed by config ID. */
+    sourceNodes: ReadonlyMap<string, TNode>;
+    /** All output nodes keyed by config ID. */
+    outputNodes: ReadonlyMap<string, TNode>;
+}
+export interface PluginBuildResult<TNode = unknown, TEdge = unknown> {
+    /** Nodes created by this plugin. */
+    nodes: TNode[];
+    /**
+     * Edges created by this plugin, including edges to/from core nodes.
+     * Also includes edges that cross the plugin boundary (e.g. source → plugin node).
+     */
+    edges: TEdge[];
+    /**
+     * Nodes this plugin exposes for cross-plugin edge resolution.
+     * The graph-builder inspects their output port types and routes them into
+     * the relevant core lookup maps automatically:
+     *   - ports of type audio/stereo  → merged into the audio-mix lookup
+     *   - ports of type video/composition → merged into the compositor lookup
+     * This allows outputs, RTT sources, and encoders to connect to plugin nodes
+     * without any hardcoded knowledge of the plugin.
+     */
+    supplementalNodes: Map<string, TNode>;
+}
+export interface ISesameEditorPlugin<TNode = unknown, TEdge = unknown> {
+    /** Unique reverse-domain ID, e.g. "com.snigel". */
+    id: string;
+    /** Node type definitions to register in the graph editor's node registry. */
+    nodeTypes: NodeTypeDef[];
+    /**
+     * Build React Flow nodes and edges from this plugin's portion of the config.
+     * Called after all core nodes have been created, before cross-plugin edges
+     * are wired.
+     */
+    buildNodes(extensions: Record<string, unknown>, config: ISesameConfig, factory: NodeFactory<TNode, TEdge>, coreNodes: CoreNodeMaps<TNode>): PluginBuildResult<TNode, TEdge>;
+    /**
+     * Serialize plugin-specific graph nodes back to a flat record that is stored
+     * under `config.extensions` keyed by this plugin's namespace.
+     */
+    serializeNodes(allNodes: TNode[], allEdges: TEdge[]): Record<string, unknown>;
+}
+export {};

package/dist/plugin.js

@@ -0,0 +1,8 @@
+/**
+ * Plugin interface types for the Sesame config editor.
+ *
+ * TNode / TEdge are generic so this package does not depend on @xyflow/react.
+ * In practice the config-editor and all plugins instantiate them as
+ * Node and Edge from @xyflow/react.
+ */
+export {};

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@stinkycomputing/sesame-editor-api",
+  "version": "1.0.0-alpha.1",
+  "description": "Plugin API types for Sesame config editor",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@stinkycomputing/sesame-interop": "^1.5.0-alpha.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.4"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}