asecli 0.6.2__py3-none-any.whl

asecli/__init__.py

@@ -0,0 +1,3 @@
+"""AseCLI — agent-native toolkit for Amplify Shader Editor assets."""
+
+__version__ = "0.6.2"

asecli/bridge/__init__.py

@@ -0,0 +1,40 @@
+"""Compile bridge (TASK-0011): MCP for Unity primary transport."""
+
+from .mcp_client import McpClient, McpError
+from .editor_create import create_shader_via_mcp
+from .editor_spec import EditorGraphSpec, SpecError, load_editor_graph_spec, route_create_backend
+from .graph_inspect import measure_node_bounds_via_mcp
+from .graph_geometry import EditorNodeGeometry, inspect_graph_geometry_via_mcp
+from .gui_support import (
+    ASECLI_GUI_EDITOR,
+    GUI_SUPPORT_ASSET_PATH,
+    MZGUI_EDITOR,
+    inspect_gui_support,
+    install_gui_support,
+)
+from .gui_handoff import handoff_gui_support
+from .gui_runtime_probe import probe_native_mzgui_via_mcp
+from .recompile import recompile_via_mcp
+from .wire_route import apply_wire_routes_via_mcp
+
+__all__ = [
+    "EditorGraphSpec",
+    "ASECLI_GUI_EDITOR",
+    "GUI_SUPPORT_ASSET_PATH",
+    "McpClient",
+    "McpError",
+    "MZGUI_EDITOR",
+    "SpecError",
+    "create_shader_via_mcp",
+    "load_editor_graph_spec",
+    "inspect_gui_support",
+    "handoff_gui_support",
+    "install_gui_support",
+    "probe_native_mzgui_via_mcp",
+    "measure_node_bounds_via_mcp",
+    "EditorNodeGeometry",
+    "inspect_graph_geometry_via_mcp",
+    "recompile_via_mcp",
+    "route_create_backend",
+    "apply_wire_routes_via_mcp",
+]

asecli/bridge/_editor_port_contract.py

@@ -0,0 +1,131 @@
+"""ASE 1.9.6.2 port contracts exposed by EditorGraphSpec v1..v3."""
+
+from __future__ import annotations
+
+from ._editor_primitives import DYNAMIC_NUMERIC, PRIMITIVE_OPS
+from .editor_spec import ConnectionSpec, NodeSpec, SpecError, TemplateSpec
+
+
+_NUMERIC_TYPES = frozenset({"INT", "FLOAT", "FLOAT2", "FLOAT3", "FLOAT4", "COLOR"})
+_MATRIX_TYPES = frozenset({"FLOAT3x3", "FLOAT4x4"})
+_DYNAMIC_NUMERIC = DYNAMIC_NUMERIC
+_URP_UNLIT_GUID = "2992e84f91cbeb14eab234972e07ea9d"
+_URP_UNLIT_MASTER_INPUTS = {
+    0: "FLOAT3",  # Baked Albedo
+    1: "FLOAT3",  # Baked Emission
+    2: "FLOAT3",  # Color
+    3: "FLOAT",   # Alpha
+    4: "FLOAT",   # Alpha Clip Threshold
+    5: "FLOAT3",  # Vertex Offset / Position
+    6: "FLOAT3",  # Vertex Normal
+    7: "FLOAT",   # Alpha Clip Threshold Shadow
+}
+_STATIC_INPUT_PORTS = {
+    "WorldPosInputsNode": {},
+    "TextureCoordinatesNode": {0: "FLOAT2", 1: "FLOAT2", 2: "SAMPLER2D"},
+    "BreakToComponentsNode": {0: _DYNAMIC_NUMERIC},
+    "SimpleAddOpNode": {0: _DYNAMIC_NUMERIC, 1: _DYNAMIC_NUMERIC},
+    "SimpleSubtractOpNode": {0: _DYNAMIC_NUMERIC, 1: _DYNAMIC_NUMERIC},
+    "SimpleMultiplyOpNode": {0: _DYNAMIC_NUMERIC, 1: _DYNAMIC_NUMERIC},
+    "SimpleDivideOpNode": {0: _DYNAMIC_NUMERIC, 1: _DYNAMIC_NUMERIC},
+    "SimpleMinOpNode": {0: _DYNAMIC_NUMERIC, 1: _DYNAMIC_NUMERIC},
+    "SimpleMaxOpNode": {0: _DYNAMIC_NUMERIC, 1: _DYNAMIC_NUMERIC},
+    "SaturateNode": {0: _DYNAMIC_NUMERIC},
+    "OneMinusNode": {0: _DYNAMIC_NUMERIC},
+    "LerpOp": {0: _DYNAMIC_NUMERIC, 1: _DYNAMIC_NUMERIC, 2: _DYNAMIC_NUMERIC},
+    "TexturePropertyNode": {},
+    "RangedFloatNode": {},
+    "Matrix4X4Node": {},
+    "Vector4Node": {},
+    "SamplerNode": {
+        0: "SAMPLER2D", 1: "FLOAT2", 2: "FLOAT", 3: "FLOAT2",
+        4: "FLOAT2", 5: "FLOAT", 6: "FLOAT", 7: "SAMPLERSTATE",
+    },
+}
+_STATIC_OUTPUT_PORTS = {
+    "WorldPosInputsNode": {0: "FLOAT3", 1: "FLOAT", 2: "FLOAT", 3: "FLOAT"},
+    "TextureCoordinatesNode": {0: "FLOAT2", 1: "FLOAT", 2: "FLOAT", 3: "FLOAT", 4: "FLOAT"},
+    "BreakToComponentsNode": {port: "FLOAT" for port in range(16)},
+    "SimpleAddOpNode": {0: _DYNAMIC_NUMERIC},
+    "SimpleSubtractOpNode": {0: _DYNAMIC_NUMERIC},
+    "SimpleMultiplyOpNode": {0: _DYNAMIC_NUMERIC},
+    "SimpleDivideOpNode": {0: _DYNAMIC_NUMERIC},
+    "SimpleMinOpNode": {0: _DYNAMIC_NUMERIC},
+    "SimpleMaxOpNode": {0: _DYNAMIC_NUMERIC},
+    "SaturateNode": {0: _DYNAMIC_NUMERIC},
+    "OneMinusNode": {0: _DYNAMIC_NUMERIC},
+    "LerpOp": {0: _DYNAMIC_NUMERIC},
+    "TexturePropertyNode": {0: "SAMPLER2D", 1: "SAMPLERSTATE"},
+    "RangedFloatNode": {0: "FLOAT"},
+    "Matrix4X4Node": {0: "FLOAT4x4"},
+    "Vector4Node": {0: "FLOAT4", 1: "FLOAT", 2: "FLOAT", 3: "FLOAT", 4: "FLOAT"},
+    "SamplerNode": {
+        0: "COLOR", 1: "FLOAT", 2: "FLOAT", 3: "FLOAT", 4: "FLOAT", 5: "FLOAT3",
+    },
+}
+
+
+def validate_connections(
+    template: TemplateSpec,
+    nodes: tuple[NodeSpec, ...],
+    connections: tuple[ConnectionSpec, ...],
+) -> None:
+    by_alias = {node.alias: node for node in nodes}
+    for index, connection in enumerate(connections):
+        source = by_alias[connection.source.node]
+        source_type = _output_ports(source).get(connection.source.port)
+        if source_type is None:
+            raise SpecError(
+                f"connections[{index}] source port {connection.source.port} does not exist on {source.alias}"
+            )
+
+        if connection.destination.node == "master":
+            if template.guid != _URP_UNLIT_GUID:
+                raise SpecError(
+                    f"connections[{index}] template guid has no verified master-port contract"
+                )
+            destination_ports = _URP_UNLIT_MASTER_INPUTS
+        else:
+            destination_ports = _input_ports(by_alias[connection.destination.node])
+        destination_type = destination_ports.get(connection.destination.port)
+        if destination_type is None:
+            raise SpecError(
+                f"connections[{index}] destination port {connection.destination.port} does not exist on "
+                f"{connection.destination.node}"
+            )
+        if not _compatible_port_types(source_type, destination_type):
+            raise SpecError(
+                f"connections[{index}] incompatible port types: {source_type} to {destination_type}"
+            )
+
+
+def _input_ports(node: NodeSpec) -> dict[int, str]:
+    if node.kind == "custom_expression":
+        return {index: item.type for index, item in enumerate(node.inputs)}
+    if node.kind == "primitive":
+        return PRIMITIVE_OPS[node.op][1]
+    if node.kind == "recipe":
+        return {index: item.type for index, item in enumerate(node.inputs)}
+    return _STATIC_INPUT_PORTS[node.ase_type]
+
+
+def _output_ports(node: NodeSpec) -> dict[int, str]:
+    if node.kind == "custom_expression":
+        assert node.output_type is not None
+        return {0: node.output_type}
+    if node.kind == "primitive":
+        return PRIMITIVE_OPS[node.op][2]
+    if node.kind == "recipe":
+        assert node.output_type is not None
+        return {0: node.output_type}
+    return _STATIC_OUTPUT_PORTS[node.ase_type]
+
+
+def _compatible_port_types(source: str, destination: str) -> bool:
+    if source == _DYNAMIC_NUMERIC:
+        return destination == _DYNAMIC_NUMERIC or destination in _NUMERIC_TYPES or destination in _MATRIX_TYPES
+    if destination == _DYNAMIC_NUMERIC:
+        return source in _NUMERIC_TYPES or source in _MATRIX_TYPES
+    if source in _NUMERIC_TYPES and destination in _NUMERIC_TYPES:
+        return True
+    return source == destination

asecli/bridge/_editor_primitives.py

@@ -0,0 +1,205 @@
+"""Algorithm-primitive closure (op -> ASE class + port contract) for EditorGraphSpec v3.
+
+This module is the single source of truth shared by the model (manifest
+synthesis), the port-contract validator, the spec validator, and (mirrored in)
+the fixed C# executor. It must import nothing from the rest of the package so
+both ``editor_spec`` and ``_editor_port_contract`` may depend on it without a
+cycle.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import re
+from typing import Any
+
+DYNAMIC_NUMERIC = "DYNAMIC_NUMERIC"
+
+
+@dataclass(frozen=True)
+class PrimitiveSpec:
+    id: str
+    op: str
+    args: tuple[str, ...] = ()
+    value: str | None = None
+
+    def to_dict(self) -> dict:
+        result: dict[str, Any] = {"id": self.id, "op": self.op}
+        if self.op == "const":
+            result["value"] = self.value
+        else:
+            result["args"] = list(self.args)
+        return result
+
+
+@dataclass(frozen=True)
+class ExpansionSpec:
+    primitives: tuple[PrimitiveSpec, ...]
+    output: str
+
+    def to_dict(self) -> dict:
+        return {
+            "primitives": [item.to_dict() for item in self.primitives],
+            "output": self.output,
+        }
+
+
+_DYN = DYNAMIC_NUMERIC
+_FLOAT = "FLOAT"
+_FLOAT2 = "FLOAT2"
+_FLOAT3 = "FLOAT3"
+_FLOAT4 = "FLOAT4"
+_COLOR = "COLOR"
+_INT = "INT"
+_SAMPLER2D = "SAMPLER2D"
+
+# op -> (ASE class name, input ports, output ports).
+# Dynamic ports use DYNAMIC_NUMERIC; fixed dimensions are spelled out.
+# Arity here is the authoritative ASE 1.9.6.2 runtime shape, verified against
+# the local schema dump and AmplifyShaderEditor source.
+PRIMITIVE_OPS: dict[str, tuple[str, dict[int, str], dict[int, str]]] = {
+    # 3.1 Math / trigonometry (almost all dynamic).
+    "add": ("SimpleAddOpNode", {0: _DYN, 1: _DYN}, {0: _DYN}),
+    "sub": ("SimpleSubtractOpNode", {0: _DYN, 1: _DYN}, {0: _DYN}),
+    "mul": ("SimpleMultiplyOpNode", {0: _DYN, 1: _DYN}, {0: _DYN}),
+    "div": ("SimpleDivideOpNode", {0: _DYN, 1: _DYN}, {0: _DYN}),
+    "min": ("SimpleMinOpNode", {0: _DYN, 1: _DYN}, {0: _DYN}),
+    "max": ("SimpleMaxOpNode", {0: _DYN, 1: _DYN}, {0: _DYN}),
+    "remainder": ("SimpleRemainderNode", {0: _DYN, 1: _DYN}, {0: _DYN}),
+    "saturate": ("SaturateNode", {0: _DYN}, {0: _DYN}),
+    "one_minus": ("OneMinusNode", {0: _DYN}, {0: _DYN}),
+    "negate": ("NegateNode", {0: _DYN}, {0: _DYN}),
+    "abs": ("AbsOpNode", {0: _DYN}, {0: _DYN}),
+    "floor": ("FloorOpNode", {0: _DYN}, {0: _DYN}),
+    "ceil": ("CeilOpNode", {0: _DYN}, {0: _DYN}),
+    "fract": ("FractNode", {0: _DYN}, {0: _DYN}),
+    "round": ("RoundOpNode", {0: _DYN}, {0: _DYN}),
+    "trunc": ("TruncOpNode", {0: _DYN}, {0: _DYN}),
+    "sign": ("SignOpNode", {0: _DYN}, {0: _DYN}),
+    "sqrt": ("SqrtOpNode", {0: _DYN}, {0: _DYN}),
+    "rsqrt": ("RSqrtOpNode", {0: _DYN}, {0: _DYN}),
+    "rcp": ("ReciprocalOpNode", {0: _DYN}, {0: _DYN}),
+    "normalize": ("NormalizeNode", {0: _DYN}, {0: _DYN}),
+    "length": ("LengthOpNode", {0: _DYN}, {0: _FLOAT}),
+    "clamp": ("ClampOpNode", {0: _DYN, 1: _DYN, 2: _DYN}, {0: _DYN}),
+    "step": ("StepOpNode", {0: _DYN, 1: _DYN}, {0: _DYN}),
+    "smoothstep": ("SmoothstepOpNode", {0: _DYN, 1: _DYN, 2: _DYN}, {0: _DYN}),
+    "lerp": ("LerpOp", {0: _DYN, 1: _DYN, 2: _DYN}, {0: _DYN}),
+    "pow": ("PowerNode", {0: _DYN, 1: _DYN}, {0: _DYN}),
+    "exp": ("ExpOpNode", {0: _DYN}, {0: _DYN}),
+    "exp2": ("Exp2OpNode", {0: _DYN}, {0: _DYN}),
+    "log": ("LogOpNode", {0: _DYN}, {0: _DYN}),
+    "log2": ("Log2OpNode", {0: _DYN}, {0: _DYN}),
+    "log10": ("Log10OpNode", {0: _DYN}, {0: _DYN}),
+    "sin": ("SinOpNode", {0: _DYN}, {0: _DYN}),
+    "cos": ("CosOpNode", {0: _DYN}, {0: _DYN}),
+    "tan": ("TanOpNode", {0: _DYN}, {0: _DYN}),
+    "asin": ("ASinOpNode", {0: _DYN}, {0: _DYN}),
+    "acos": ("ACosOpNode", {0: _DYN}, {0: _DYN}),
+    "atan": ("ATanOpNode", {0: _DYN}, {0: _DYN}),
+    "atan2": ("ATan2OpNode", {0: _DYN, 1: _DYN}, {0: _DYN}),
+    "sinh": ("SinhOpNode", {0: _DYN}, {0: _DYN}),
+    "cosh": ("CoshOpNode", {0: _DYN}, {0: _DYN}),
+    "tanh": ("TanhOpNode", {0: _DYN}, {0: _DYN}),
+    "radians": ("RadiansOpNode", {0: _DYN}, {0: _DYN}),
+    "degrees": ("DegreesOpNode", {0: _DYN}, {0: _DYN}),
+    "fmod": ("FmodOpNode", {0: _DYN, 1: _DYN}, {0: _DYN}),
+    "remap": ("TFHCRemapNode", {0: _DYN, 1: _DYN, 2: _DYN, 3: _DYN, 4: _DYN}, {0: _DYN}),
+    "dot": ("DotProductOpNode", {0: _DYN, 1: _DYN}, {0: _FLOAT}),
+    "cross": ("CrossProductOpNode", {0: _FLOAT3, 1: _FLOAT3}, {0: _FLOAT3}),
+    "distance": ("DistanceOpNode", {0: _DYN, 1: _DYN}, {0: _FLOAT}),
+    "reflect": ("ReflectOpNode", {0: _DYN, 1: _DYN}, {0: _DYN}),
+    "refract": ("RefractOpVec", {0: _DYN, 1: _DYN, 2: _DYN}, {0: _DYN}),
+    # ASE RotateAboutAxisNode takes 4 inputs (axis, angle, pivot, position).
+    "rotate_axis": ("RotateAboutAxisNode",
+                     {0: _FLOAT3, 1: _FLOAT, 2: _FLOAT3, 3: _FLOAT3}, {0: _FLOAT3}),
+
+    # 3.2 Vector / channel / constant.
+    "append": ("DynamicAppendNode", {0: _FLOAT, 1: _FLOAT, 2: _FLOAT, 3: _FLOAT}, {0: _FLOAT4}),
+    "swizzle": ("SwizzleNode", {0: _DYN}, {0: _DYN}),
+    "component_mask": ("ComponentMaskNode", {0: _DYN}, {0: _DYN}),
+    "split": ("BreakToComponentsNode", {0: _DYN}, {port: _FLOAT for port in range(16)}),
+    # "const" is shape-dispatched at runtime; not a fixed ASE class.
+
+    # 3.3 Image / color / logic.
+    "luminance": ("LuminanceNode", {0: _DYN}, {0: _DYN}),
+    "desaturate": ("DesaturateOpNode", {0: _DYN, 1: _DYN}, {0: _DYN}),
+    "contrast": ("SimpleContrastOpNode", {0: _DYN, 1: _DYN}, {0: _DYN}),
+    "posterize": ("PosterizeNode", {0: _COLOR, 1: _INT}, {0: _COLOR}),
+    "rgb_to_hsv": ("RGBToHSVNode", {0: _FLOAT3}, {0: _FLOAT3, 1: _FLOAT, 2: _FLOAT, 3: _FLOAT}),
+    "hsv_to_rgb": ("HSVToRGBNode", {0: _FLOAT, 1: _FLOAT, 2: _FLOAT},
+                   {0: _FLOAT3, 1: _FLOAT, 2: _FLOAT, 3: _FLOAT}),
+    "gamma_to_linear": ("GammaToLinearNode", {0: _DYN}, {0: _DYN}),
+    "linear_to_gamma": ("LinearToGammaNode", {0: _DYN}, {0: _DYN}),
+    "not": ("NotNode", {0: _DYN}, {0: _DYN}),
+    "nand": ("NandNode", {0: _DYN, 1: _DYN}, {0: _DYN}),
+    # ASE AllOpNode / AnyOpNode are unary "all/any components non-zero".
+    "and": ("AllOpNode", {0: _DYN}, {0: _DYN}),
+    "or": ("AnyOpNode", {0: _DYN}, {0: _DYN}),
+    # ASE StaticSwitch is a 9-input keyword toggle; ConditionalIfNode is a 5-input compare.
+    "select": ("StaticSwitch", {port: _FLOAT for port in range(9)}, {0: _DYN}),
+
+    # 3.4 Input / context primitives.
+    "texcoord": ("TextureCoordinatesNode",
+                 {0: _FLOAT2, 1: _FLOAT2, 2: _SAMPLER2D},
+                 {0: _FLOAT2, 1: _FLOAT, 2: _FLOAT, 3: _FLOAT, 4: _FLOAT}),
+    "world_position": ("WorldPosInputsNode", {}, {0: _FLOAT3, 1: _FLOAT, 2: _FLOAT, 3: _FLOAT}),
+    "time": ("SimpleTimeNode", {0: _FLOAT}, {0: _FLOAT}),
+    "vertex_color": ("VertexColorNode", {}, {0: _COLOR, 1: _FLOAT, 2: _FLOAT, 3: _FLOAT, 4: _FLOAT}),
+    "vertex_id": ("VertexIdVariableNode", {}, {0: _INT}),
+    "instance_id": ("InstanceIdNode", {}, {0: _INT}),
+    "world_normal": ("WorldNormalVector", {0: _FLOAT3}, {0: _FLOAT3, 1: _FLOAT, 2: _FLOAT, 3: _FLOAT}),
+}
+
+
+_VEC_CONST = re.compile(r"^\s*float([234])\s*\(\s*(.+?)\s*\)\s*$")
+_NUMBER = re.compile(r"^[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?$")
+
+
+def const_class(value: str) -> str:
+    """ASE class for a const literal, dispatched by HLSL shape."""
+    if _NUMBER.fullmatch(value.strip()):
+        return "RangedFloatNode"
+    match = _VEC_CONST.match(value)
+    if match:
+        return {"2": "Vector2Node", "3": "Vector3Node", "4": "Vector4Node"}[match.group(1)]
+    raise ValueError(f"unsupported const literal shape: {value!r}")
+
+
+def const_output_type(value: str) -> str:
+    if _NUMBER.fullmatch(value.strip()):
+        return "FLOAT"
+    match = _VEC_CONST.match(value)
+    if match:
+        return "FLOAT" + match.group(1)
+    raise ValueError(f"unsupported const literal shape: {value!r}")
+
+
+def primitive_class(op: str) -> str | None:
+    """ASE class for an op, or None when the op is not in the closure."""
+    entry = PRIMITIVE_OPS.get(op)
+    return entry[0] if entry else None
+
+
+def is_known_op(op: str) -> bool:
+    return op in PRIMITIVE_OPS
+
+
+def expansion_classes(primitives: object) -> list[str] | None:
+    """Resolve each recipe expansion primitive to its ASE class.
+
+    Returns ``None`` when any primitive cannot be resolved (which signals the
+    executor to fall back to ``CustomExpressionNode``), otherwise a list of ASE
+    class names aligned with the primitive order.
+    """
+    classes: list[str] = []
+    for primitive in primitives:  # type: ignore[union-attr]
+        op = primitive.op
+        if op == "const":
+            classes.append(const_class(primitive.value))
+            continue
+        cls = primitive_class(op)
+        if cls is None:
+            return None
+        classes.append(cls)
+    return classes

asecli/bridge/_editor_spec_grammar.py

@@ -0,0 +1,245 @@
+"""Shared grammar constants, helpers and v3 parsing for EditorGraphSpec validation."""
+
+from __future__ import annotations
+
+import math
+import re
+from typing import Any
+
+from ._editor_primitives import ExpansionSpec, PrimitiveSpec, const_output_type, is_known_op
+from .editor_spec import InputSpec, NodeSpec, SpecError
+
+
+GENERIC_NODE_TYPES = frozenset({"WorldPosInputsNode", "TextureCoordinatesNode", "BreakToComponentsNode", "SimpleAddOpNode", "SimpleSubtractOpNode", "SimpleMultiplyOpNode", "SimpleDivideOpNode", "SimpleMinOpNode", "SimpleMaxOpNode", "SaturateNode", "OneMinusNode", "LerpOp"})
+PROPERTY_NODE_TYPES = frozenset({"TexturePropertyNode", "RangedFloatNode", "Matrix4X4Node", "Vector4Node"})
+PROPERTY_TYPES = frozenset({"Constant", "Property", "InstancedProperty", "Global"})
+SUPPORTED_PRIMITIVES_VERSIONS = frozenset({1})
+PRECISION_TYPES = frozenset({"Float", "Half", "Inherit"})
+INPUT_TYPES = frozenset(
+    {
+        "INT", "FLOAT", "FLOAT2", "FLOAT3", "FLOAT4", "FLOAT3x3", "FLOAT4x4",
+        "SAMPLER1D", "SAMPLER2D", "SAMPLER3D", "SAMPLERCUBE", "SAMPLER2DARRAY", "SAMPLERSTATE",
+    }
+)
+OUTPUT_TYPES = frozenset({"INT", "FLOAT", "FLOAT2", "FLOAT3", "FLOAT4", "FLOAT3x3", "FLOAT4x4"})
+_ROOT_KEYS = frozenset({"version", "template", "nodes", "connections", "primitives_version"})
+_TEMPLATE_KEYS = frozenset({"guid", "shader_name"})
+_COMMON_NODE_KEYS = frozenset({"alias", "kind", "position"})
+_NODE_KEYS_V1 = {
+    "node": _COMMON_NODE_KEYS | {"type"},
+    "property": _COMMON_NODE_KEYS | {"type", "property_name", "inspector_name", "parameter_type"},
+    "sampler": _COMMON_NODE_KEYS | {"property_name", "inspector_name", "parameter_type"},
+    "custom_expression": _COMMON_NODE_KEYS | {"name", "code", "output_type", "inputs"},
+}
+_NODE_KEYS_V2 = {
+    **_NODE_KEYS_V1,
+    "node": _NODE_KEYS_V1["node"] | {"precision"},
+    "property": _NODE_KEYS_V1["property"] | {"help", "tooltip", "enabled_if", "precision", "default", "min", "max"},
+    "sampler": _NODE_KEYS_V1["sampler"] | {"help", "tooltip", "enabled_if", "precision"},
+}
+_NODE_KEYS_V3 = {
+    **_NODE_KEYS_V2,
+    "primitive": _COMMON_NODE_KEYS | {"op"},
+    "recipe": _COMMON_NODE_KEYS | {"recipe", "code", "output_type", "inputs", "expansion"},
+}
+_ALIAS = re.compile(r"^[A-Za-z][A-Za-z0-9_-]{0,63}$")
+_IDENTIFIER = re.compile(r"^[A-Za-z_][A-Za-z0-9_]{0,63}$")
+_PROPERTY_NAME = re.compile(r"^_[A-Za-z][A-Za-z0-9_]{0,126}$")
+_GUID = re.compile(r"^[0-9a-fA-F]{32}$")
+_CSHARP_MARKERS = re.compile(
+    r"(?:\busing\s+(?:System|Unity)|\bUnityEditor\b|\bUnityEngine\b|"
+    r"\bSystem\.(?:IO|Reflection|Diagnostics|Runtime|Net)\b|\bDllImport\b|^\s*#r\b)", re.MULTILINE,
+)
+
+
+def parse_precision(obj: dict, label: str) -> str | None:
+    if "precision" not in obj:
+        return None
+    precision = obj.get("precision")
+    if not isinstance(precision, str) or precision not in PRECISION_TYPES:
+        raise SpecError(f"{label} precision must be one of {sorted(PRECISION_TYPES)}")
+    return precision
+
+
+def parse_primitive(obj: dict, label: str, alias: str, position: tuple[float, float]) -> NodeSpec:
+    op = _string(obj.get("op"), f"{label} op", 64)
+    if not is_known_op(op):
+        raise SpecError(f"{label} op {op!r} is not in the algorithm-primitive closure")
+    return NodeSpec(alias, "primitive", position, op=op)
+
+
+def parse_recipe(obj: dict, label: str, alias: str, position: tuple[float, float]) -> NodeSpec:
+    recipe = _string(obj.get("recipe"), f"{label} recipe", 64)
+    code = _safe_text(obj.get("code"), f"{label} code", 65535, True)
+    if any(char in code for char in ("@", "$")) or _CSHARP_MARKERS.search(code):
+        raise SpecError(f"{label} code contains an ASE delimiter or forbidden C# runtime marker")
+    output_type = obj.get("output_type")
+    if output_type not in OUTPUT_TYPES:
+        raise SpecError(f"{label} output_type must be one of {sorted(OUTPUT_TYPES)}")
+    raw_inputs = obj.get("inputs")
+    if not isinstance(raw_inputs, list) or not raw_inputs or len(raw_inputs) > 32:
+        raise SpecError(f"{label} inputs must contain 1 through 32 entries")
+    inputs = tuple(parse_input(item, label, i) for i, item in enumerate(raw_inputs))
+    input_names = {item.name for item in inputs}
+    if len(input_names) != len(inputs):
+        raise SpecError(f"{label} input name must be unique")
+    expansion = _parse_expansion(obj.get("expansion"), label, inputs)
+    return NodeSpec(alias, "recipe", position, recipe=recipe, code=code,
+                    output_type=output_type, inputs=inputs, expansion=expansion)
+
+
+def _parse_expansion(value: Any, label: str, inputs: tuple[InputSpec, ...]) -> ExpansionSpec:
+    obj = _object(value, f"{label} expansion")
+    _unknown(obj, frozenset({"primitives", "output"}), f"{label} expansion")
+    raw = obj.get("primitives")
+    if not isinstance(raw, list) or not raw:
+        raise SpecError(f"{label} expansion.primitives must be a non-empty array")
+    primitives = tuple(_parse_primitive_entry(item, label, i) for i, item in enumerate(raw))
+    ids = [item.id for item in primitives]
+    if len(set(ids)) != len(ids):
+        raise SpecError(f"{label} expansion primitive id must be unique")
+    input_names = {item.name for item in inputs}
+    declared: set[str] = set(input_names)
+    for primitive in primitives:
+        if primitive.op == "const":
+            if primitive.args:
+                raise SpecError(f"{label} expansion const primitive must not declare args")
+            if primitive.value is None:
+                raise SpecError(f"{label} expansion const primitive must declare value")
+            try:
+                const_output_type(primitive.value)
+            except ValueError as exc:
+                raise SpecError(f"{label} expansion const value {exc}") from exc
+        else:
+            if primitive.value is not None:
+                raise SpecError(f"{label} expansion non-const primitive must not declare value")
+            for arg in primitive.args:
+                if arg not in declared:
+                    raise SpecError(f"{label} expansion arg {arg!r} references an undeclared id or input")
+        declared.add(primitive.id)
+    output = obj.get("output")
+    if not isinstance(output, str) or not output or output not in declared:
+        raise SpecError(f"{label} expansion.output must reference a declared id or input name")
+    return ExpansionSpec(primitives=primitives, output=output)
+
+
+def _parse_primitive_entry(value: Any, node_label: str, index: int) -> PrimitiveSpec:
+    label = f"{node_label} expansion.primitives[{index}]"
+    obj = _object(value, label)
+    _unknown(obj, frozenset({"id", "op", "args", "value"}), label)
+    pid = _string(obj.get("id"), f"{label} id", 64)
+    if not _IDENTIFIER.fullmatch(pid):
+        raise SpecError(f"{label} id must be an HLSL identifier")
+    op = _string(obj.get("op"), f"{label} op", 64)
+    args = obj.get("args")
+    if args is None:
+        arg_tuple: tuple[str, ...] = ()
+    elif isinstance(args, list):
+        arg_tuple = tuple(_string(item, f"{label} args", 64) for item in args)
+    else:
+        raise SpecError(f"{label} args must be an array")
+    value = obj.get("value")
+    if value is not None and not isinstance(value, str):
+        raise SpecError(f"{label} value must be a string")
+    return PrimitiveSpec(id=pid, op=op, args=arg_tuple, value=value)
+
+
+def parse_property_semantics(
+    obj: dict, label: str, kind: str, node_type: str,
+) -> tuple[Any, float | None, float | None]:
+    default = obj.get("default")
+    minimum = obj.get("min")
+    maximum = obj.get("max")
+    if kind == "sampler":
+        if default is not None or minimum is not None or maximum is not None:
+            raise SpecError(f"{label} sampler does not accept default/min/max")
+        return None, None, None
+    if node_type == "RangedFloatNode":
+        if default is not None:
+            if isinstance(default, bool) or not isinstance(default, (int, float)) or not math.isfinite(float(default)):
+                raise SpecError(f"{label} default must be a finite number")
+            default = float(default)
+        if (minimum is None) != (maximum is None):
+            raise SpecError(f"{label} min and max must appear together")
+        if minimum is not None:
+            if isinstance(minimum, bool) or not isinstance(minimum, (int, float)):
+                raise SpecError(f"{label} min must be a number")
+            if isinstance(maximum, bool) or not isinstance(maximum, (int, float)):
+                raise SpecError(f"{label} max must be a number")
+            minimum = float(minimum)
+            maximum = float(maximum)
+            if minimum > maximum:
+                raise SpecError(f"{label} min must not exceed max")
+        return default, minimum, maximum
+    if node_type == "Vector4Node":
+        if default is not None:
+            if not isinstance(default, list) or len(default) != 4 or any(
+                isinstance(item, bool) or not isinstance(item, (int, float)) for item in default
+            ):
+                raise SpecError(f"{label} default must be a 4-number array")
+            default = [float(item) for item in default]
+        if minimum is not None or maximum is not None:
+            raise SpecError(f"{label} min/max only apply to RangedFloatNode")
+        return default, None, None
+    if default is not None or minimum is not None or maximum is not None:
+        raise SpecError(f"{label} default/min/max only apply to RangedFloatNode or Vector4Node")
+    return None, None, None
+
+
+def parse_input(value: Any, node_label: str, index: int) -> InputSpec:
+    label = f"{node_label}.inputs[{index}]"
+    obj = _object(value, label)
+    _unknown(obj, frozenset({"name", "type"}), label)
+    name = _string(obj.get("name"), f"{label} name", 64)
+    if not _IDENTIFIER.fullmatch(name):
+        raise SpecError(f"{label} name must be an HLSL identifier")
+    data_type = obj.get("type")
+    if data_type not in INPUT_TYPES:
+        raise SpecError(f"{label} type must be one of {sorted(INPUT_TYPES)}")
+    return InputSpec(name=name, type=data_type)
+
+
+def object_dict(value: Any, label: str) -> dict:
+    if not isinstance(value, dict):
+        raise SpecError(f"{label} must be a JSON object")
+    return value
+
+
+def reject_unknown(value: dict, allowed: frozenset[str] | set[str], label: str) -> None:
+    unknown = set(value) - set(allowed)
+    if unknown:
+        raise SpecError(f"{label} has unknown keys: {sorted(unknown)}")
+
+
+def require_string(value: Any, label: str, limit: int) -> str:
+    if not isinstance(value, str) or not value or len(value) > limit:
+        raise SpecError(f"{label} must be a non-empty string of at most {limit} characters")
+    return value
+
+
+def safe_text(value: Any, label: str, limit: int, allow_newline: bool) -> str:
+    text = require_string(value, label, limit)
+    if "\x00" in text or (not allow_newline and any(char in text for char in ("\r", "\n", ";"))):
+        raise SpecError(f"{label} contains a forbidden control character or separator")
+    return text
+
+
+def position(value: Any, label: str) -> tuple[float, float]:
+    if not isinstance(value, list) or len(value) != 2:
+        raise SpecError(f"{label} must be [x, y]")
+    result = []
+    for item in value:
+        if isinstance(item, bool) or not isinstance(item, (int, float)):
+            raise SpecError(f"{label} coordinates must be numbers")
+        number = float(item)
+        if not math.isfinite(number) or abs(number) > 1_000_000:
+            raise SpecError(f"{label} coordinates must be finite and within +/-1000000")
+        result.append(number)
+    return result[0], result[1]
+
+
+_object = object_dict
+_unknown = reject_unknown
+_string = require_string
+_safe_text = safe_text
+_position = position

asecli/bridge/_editor_spec_io.py

@@ -0,0 +1,26 @@
+"""IO and routing helpers for EditorGraphSpec, split out to bound LOC."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .editor_spec import EditorGraphSpec, SpecError
+
+
+def load_editor_graph_spec(path: str | Path) -> EditorGraphSpec:
+    try:
+        value = json.loads(Path(path).read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        raise
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise SpecError(f"cannot read EditorGraphSpec JSON: {exc}") from exc
+    return EditorGraphSpec.from_dict(value)
+
+
+def route_create_backend(requested: str, spec: EditorGraphSpec | None) -> str:
+    if requested not in {"text", "editor", "auto"}:
+        raise SpecError(f"unknown create backend: {requested}")
+    if requested == "auto":
+        return "editor" if spec is not None else "text"
+    return requested