designer-session

Designer Session

Read the active Designer session and graph before mutating it. The public tools create built-in sbs:: nodes or explicit open-package resource instances, address native node and property identifiers, and accept an allowlisted set of scalar and vector value types. They do not expose an eval, script, shell, or generic action surface.

Use export_graph_state after each authoring sequence to verify node count, type URLs, positions, parameters, topology, and output usages. A typical graph sequence is create_graph → create_node → connect_nodes → set_parameter → add_output/set_output_usage → save_package_as → export_graph_state.

Package tools use Designer's package manager. Bitmap and SVG imports validate the declared resource kind and use linked resources unless embed=true is explicitly requested. export_sbsar uses Designer's official SBSAR exporter and requires a fresh, nonempty artifact. export_maps compiles the current package to SBSAR in a new run directory, then invokes only the official sbsrender executable discovered by the host environment and always requires explicit format, bit depth, and color-space settings; it fails closed when that executable is unavailable.

expose_parameter binds a writable constant input through the public graph-input and function-graph APIs. The SDK must advertise the required variable reader and a unique string input; unsupported types return EXPOSE_API_UNAVAILABLE or EXPOSE_TYPE_UNSUPPORTED. Use set_graph_parameter to edit the exposed value. Host API calls remain on the Designer main thread through the adapter's Core execution bridge.

Use get_gradient_keys and set_gradient_keys for the native gradientrgba input of sbs::compositing::gradient nodes. Both require the observed graph UID. The setter replaces 2..64 strictly ordered keys, with position, RGBA channels, and midpoint in 0..1 (midpoint defaults to 0.5). It rejects other node/input types, connected or function-driven inputs, and nonfinite values before mutation. Results contain the actual native float values, which may have float32 rounding. Reads preserve native pin order, including stacked pins with equal positions. Writes require strictly increasing positions after native float32 conversion. Readback failure restores the prior gradient. These tools do not change color mode, interpolation mode, other node parameters, or graph connections.

Start with list_nodes and list_node_types, then describe_node or describe_node_type to inspect supported parameter and port types. Reuse returned native IDs; create_node.node_id sets a display label, not the SDK handle. Pass the observed graph_uid as expected_graph_uid on supported mutations. Use validate_connection before connecting and disconnect_nodes for exact-edge removal. Open package resources can be inspected, selected or instanced through list_resources, select_graph and instance_resource; create_subgraph creates a same-package composition graph. Recursive instances are rejected.

inspect_graph_session reports package ownership/dirty state, graph inputs, node connections/function bindings and the last application interop error. This is not a per-node compiler log.

evaluate_graph checks node and static resolution budgets and output texture metadata. Compute remains synchronous with no hard cancellation deadline. Exported file headers verify dimensions and actual bit depth; hashes prove fresh bytes, not visual material accuracy. export_native_maps preserves native texture precision without requiring SAT. Select the named graph output node and its returned port when Designer releases an intermediate texture after computation. Missing texture errors identify the requested name, node and port. Native export checks all selected textures and stages verified files before publishing the destination; a failed export leaves that destination available for retry. Each file receipt includes its native pixel format and source node/port. SAT export owns the renderer process tree for timeout cleanup. Save before closing a modified package; opening an already-open package preserves its in-memory edits. Use a new path to export SBSAR or save another package.