asecli 0.6.2__py3-none-any.whl

asecli/core/compiled_properties.py

@@ -0,0 +1,190 @@
+"""Conservative ShaderLab ``Properties`` parser for presentation reconciliation."""
+
+from __future__ import annotations
+
+import re
+
+
+_PROPERTIES_TOKEN = re.compile(r"(?m)^[ \t]*Properties\b")
+_ATTRIBUTE_TOKEN = re.compile(r"\[[^\]\r\n]*\]")
+_ATTRIBUTES_ONLY = re.compile(r"^(?:\[[^\]\r\n]*\][ \t]*)+$")
+_PROPERTY_DECLARATION = re.compile(
+    r"^(?P<attributes>(?:\[[^\]\r\n]*\][ \t]*)*)"
+    r"(?P<name>[A-Za-z_][A-Za-z0-9_]*)[ \t]*\([ \t]*"
+    r'"(?P<display_name>(?:\\.|[^"\\])*)"[ \t]*,'
+)
+_ATTRIBUTE_DETAIL = re.compile(
+    r"^\[(?P<type>[A-Za-z_][A-Za-z0-9_]*)(?:\((?P<args>.*)\))?\]$"
+)
+
+
+def parse_compiled_properties(source: str) -> list[dict]:
+    """Parse one ShaderLab Properties block or fail on an unknown active line.
+
+    ASECLI only promises layouts produced by its verified ASE profile. Failing
+    closed is intentional: an unparsed declaration must never become a vacuous
+    presentation pass.
+    """
+    body = _properties_body(source)
+    if body is None:
+        return []
+
+    properties: list[dict] = []
+    pending_attributes: list[str] = []
+    in_block_comment = False
+    for line_number, raw_line in enumerate(body.splitlines(), start=1):
+        line, in_block_comment = _without_comments(raw_line, in_block_comment)
+        stripped = line.strip()
+        if not stripped:
+            continue
+        if _ATTRIBUTES_ONLY.fullmatch(stripped):
+            pending_attributes.extend(_ATTRIBUTE_TOKEN.findall(stripped))
+            continue
+        match = _PROPERTY_DECLARATION.match(stripped)
+        if match is None:
+            raise ValueError(
+                f"unrecognized ShaderLab Properties declaration at block line {line_number}: {stripped!r}"
+            )
+        raw_attributes = [
+            *pending_attributes,
+            *_ATTRIBUTE_TOKEN.findall(match.group("attributes")),
+        ]
+        pending_attributes.clear()
+        attributes = [_parse_attribute(raw) for raw in raw_attributes]
+        properties.append(
+            {
+                "property_name": match.group("name"),
+                "display_name": match.group("display_name"),
+                "attributes": attributes,
+                "hidden": any(
+                    item["type"].lower() == "hideininspector" for item in attributes
+                ),
+                "block_line": line_number,
+            }
+        )
+    if in_block_comment:
+        raise ValueError("unterminated block comment in ShaderLab Properties block")
+    if pending_attributes:
+        raise ValueError("ShaderLab property attributes are not followed by a declaration")
+    return properties
+
+
+def inspect_compiled_properties(source: str) -> tuple[list[dict], str | None]:
+    try:
+        return parse_compiled_properties(source), None
+    except ValueError as exc:
+        return [], str(exc)
+
+
+def _properties_body(source: str) -> str | None:
+    matches = list(_PROPERTIES_TOKEN.finditer(source))
+    if not matches:
+        return None
+    if len(matches) != 1:
+        raise ValueError(f"expected at most one ShaderLab Properties block, found {len(matches)}")
+    token = matches[0]
+    opening = re.match(r"[ \t\r\n]*\{", source[token.end() :])
+    if opening is None:
+        raise ValueError("ShaderLab Properties keyword is not followed by an opening brace")
+    open_index = token.end() + opening.end() - 1
+    depth = 1
+    in_string = False
+    in_line_comment = False
+    in_block_comment = False
+    escaped = False
+    index = open_index + 1
+    while index < len(source):
+        char = source[index]
+        next_char = source[index + 1] if index + 1 < len(source) else ""
+        if in_line_comment:
+            if char in "\r\n":
+                in_line_comment = False
+            index += 1
+            continue
+        if in_block_comment:
+            if char == "*" and next_char == "/":
+                in_block_comment = False
+                index += 2
+            else:
+                index += 1
+            continue
+        if in_string:
+            if escaped:
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == '"':
+                in_string = False
+            index += 1
+            continue
+        if char == "/" and next_char == "/":
+            in_line_comment = True
+            index += 2
+            continue
+        if char == "/" and next_char == "*":
+            in_block_comment = True
+            index += 2
+            continue
+        if char == '"':
+            in_string = True
+        elif char == "{":
+            depth += 1
+        elif char == "}":
+            depth -= 1
+            if depth == 0:
+                return source[open_index + 1 : index]
+        index += 1
+    raise ValueError("unterminated ShaderLab Properties block")
+
+
+def _without_comments(line: str, in_block_comment: bool) -> tuple[str, bool]:
+    result: list[str] = []
+    in_string = False
+    escaped = False
+    index = 0
+    while index < len(line):
+        char = line[index]
+        next_char = line[index + 1] if index + 1 < len(line) else ""
+        if in_block_comment:
+            if char == "*" and next_char == "/":
+                in_block_comment = False
+                index += 2
+            else:
+                index += 1
+            continue
+        if in_string:
+            result.append(char)
+            if escaped:
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == '"':
+                in_string = False
+            index += 1
+            continue
+        if char == '"':
+            in_string = True
+            result.append(char)
+            index += 1
+            continue
+        if char == "/" and next_char == "/":
+            break
+        if char == "/" and next_char == "*":
+            in_block_comment = True
+            index += 2
+            continue
+        result.append(char)
+        index += 1
+    return "".join(result), in_block_comment
+
+
+def _parse_attribute(raw: str) -> dict:
+    match = _ATTRIBUTE_DETAIL.fullmatch(raw)
+    if match is None:
+        raise ValueError(f"invalid ShaderLab property attribute: {raw!r}")
+    result = {"type": match.group("type"), "raw": raw, "args": match.group("args")}
+    if result["type"] in {"ASECLITooltip", "ASECLIHelpBox", "TooltipMzgui", "HelpBoxMzgui"} and result["args"] is not None:
+        units = re.findall(r"#([0-9A-Fa-f]{4})", result["args"])
+        encoded = b"".join(int(unit, 16).to_bytes(2, "little") for unit in units)
+        result["text"] = encoded.decode("utf-16-le", errors="replace")
+    return result

asecli/core/custom_gui.py

@@ -0,0 +1,250 @@
+"""CustomEditor and ASECLI property-metadata support."""
+from __future__ import annotations
+from dataclasses import dataclass
+import re
+from .model import AseFile, AseGraph, NodeLine
+from .custom_gui_versions import CUSTOM_EDITOR_GRAPH_VERSIONS, PROPERTY_METADATA_TAIL_GRAPH_VERSIONS, TARGET_ASE_VERSION, TARGET_GRAPH_VERSION, require_custom_editor_version, require_property_metadata_tail_version
+from .material_gui_protocol import LEGACY_PROPERTY_METADATA_ATTRIBUTE_TYPES as _ALTERNATE_ASECLI_ATTRIBUTE_TYPES, MANAGED_PROPERTY_METADATA_ATTRIBUTE_TYPES, PROPERTY_METADATA_ATTRIBUTE_TYPES, canonical_property_metadata_type, equivalent_property_metadata_types
+from .material_gui_condition import parse_enable_if_arguments
+from .property_presentation import inspect_property_presentation
+
+ASECLI_GUI_EDITOR = "ASECLI.MaterialGUI.ASECLIMaterialGUI"
+MZGUI_EDITOR = "MZGUI.MZGUI"
+SUPPORTED_GUI_EDITORS = frozenset((MZGUI_EDITOR, ASECLI_GUI_EDITOR))
+CUSTOM_EDITOR_SUGGESTIONS = ("ASEMaterialInspector", MZGUI_EDITOR, ASECLI_GUI_EDITOR, "Rendering.HighDefinition.LightingShaderGraphGUI", "Rendering.HighDefinition.HDUnlitGUI", "UnityEditor.Rendering.HighDefinition.HDLitGUI", "UnityEditor.ShaderGraph.PBRMasterGUI", "UnityEditor.Rendering.HighDefinition.DecalGUI", "UnityEditor.Rendering.HighDefinition.FabricGUI", "UnityEditor.Experimental.Rendering.HDPipeline.HDLitGUI", "Rendering.HighDefinition.DecalGUI", "Rendering.HighDefinition.LitShaderGraphGUI", "Rendering.HighDefinition.DecalShaderGraphGUI", "UnityEditor.ShaderGraphUnlitGUI", "UnityEditor.ShaderGraphLitGUI", "UnityEditor.Rendering.Universal.DecalShaderGraphGUI")
+_MASTER_TYPES = {"AmplifyShaderEditor.TemplateMultiPassMasterNode", "AmplifyShaderEditor.TemplateMasterNode", "AmplifyShaderEditor.StandardSurfaceOutputNode", "AmplifyShaderEditor.LogNode"}
+_EDITOR_CLASS_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$")
+_ATTRIBUTE_RE = re.compile(r"^\[(?P<type>[A-Za-z_][A-Za-z0-9_]*)(?:\((?P<args>.*)\))?\]$")
+_CUSTOM_EDITOR_LINE_RE = re.compile(r'(?m)^(?P<indent>[ \t]*)CustomEditor[ \t]+"(?P<name>[^"\r\n]*)"[ \t]*(?:\r?\n|$)')
+_FALLBACK_LINE_RE = re.compile(r"(?im)^(?P<indent>[ \t]*)fallback\b")
+_GROUP_INVALID = frozenset("\r\n\\><'\";:[]{}=+`~/?!@#$%^&*")
+@dataclass(frozen=True)
+class PropertyMetadataTail:
+    count_index: int; attributes: tuple[str, ...]
+def validate_editor_class(name: str) -> str:
+    if len(name) > 255 or not _EDITOR_CLASS_RE.fullmatch(name):
+        raise ValueError(
+            "custom editor must be a namespace-qualified C# class name using only letters, digits, '_' and '.'"
+        )
+    return name
+def main_master_node(graph: AseGraph) -> NodeLine:
+    require_custom_editor_version(graph)
+    candidates = [node for node in graph.nodes if node.type_name in _MASTER_TYPES
+                  and len(node.raw_fields) > 9 and node.raw_fields[6].lower() == "true"]
+    if len(candidates) != 1:
+        raise ValueError(f"expected exactly one main MasterNode, found {len(candidates)}")
+    return candidates[0]
+def graph_custom_editor(graph: AseGraph) -> str | None:
+    value = main_master_node(graph).raw_fields[9]
+    return value or None
+def compiled_custom_editor(ase_file: AseFile) -> str | None:
+    matches = list(_CUSTOM_EDITOR_LINE_RE.finditer(ase_file.prefix))
+    if len(matches) > 1:
+        raise ValueError(f"expected at most one compiled CustomEditor directive, found {len(matches)}")
+    return matches[0].group("name") if matches else None
+def set_custom_editor(ase_file: AseFile, editor: str | None) -> dict:
+    if editor is not None:
+        validate_editor_class(editor)
+        editor = MZGUI_EDITOR if editor == ASECLI_GUI_EDITOR else editor
+    node = main_master_node(ase_file.graph)
+    before_graph = node.raw_fields[9] or None
+    before_compiled = compiled_custom_editor(ase_file)
+    node.raw_fields[9] = editor or ""
+    ase_file.graph.replace_node(node)
+    ase_file.prefix = _replace_compiled_editor(ase_file.prefix, editor)
+    return {"kind": "custom_editor", "main_node_id": node.node_id,
+            "before": {"graph": before_graph, "compiled": before_compiled}, "after": editor}
+def _replace_compiled_editor(prefix: str, editor: str | None) -> str:
+    matches = list(_CUSTOM_EDITOR_LINE_RE.finditer(prefix))
+    if len(matches) > 1:
+        raise ValueError(f"expected at most one compiled CustomEditor directive, found {len(matches)}")
+    if matches:
+        match = matches[0]
+        if editor is None:
+            return prefix[: match.start()] + prefix[match.end() :]
+        raw = match.group(0)
+        eol = "\r\n" if raw.endswith("\r\n") else ("\n" if raw.endswith("\n") else "")
+        line = f'{match.group("indent")}CustomEditor "{editor}"{eol}'
+        return prefix[: match.start()] + line + prefix[match.end() :]
+    if editor is None:
+        return prefix
+    eol = "\r\n" if "\r\n" in prefix else "\n"
+    fallback = _FALLBACK_LINE_RE.search(prefix)
+    if fallback:
+        line = f'{fallback.group("indent")}CustomEditor "{editor}"{eol}'
+        return prefix[: fallback.start()] + line + prefix[fallback.start() :]
+    closing_braces = list(re.finditer(r"(?m)^[ \t]*}[ \t]*(?:\r?\n|$)", prefix))
+    if not closing_braces:
+        raise ValueError("cannot insert compiled CustomEditor: ShaderLab closing brace not found")
+    insert_at = closing_braces[-1].start()
+    return prefix[:insert_at] + f'\tCustomEditor "{editor}"{eol}' + prefix[insert_at:]
+def encode_custom_unicode(text: str) -> str:
+    raw = text.encode("utf-16-le", errors="surrogatepass")
+    return "".join(f"#{int.from_bytes(raw[i:i + 2], 'little'):04X}" for i in range(0, len(raw), 2))
+def decode_custom_unicode(value: str) -> str:
+    units = re.findall(r"#([0-9A-Fa-f]{4})", value)
+    raw = b"".join(int(unit, 16).to_bytes(2, "little") for unit in units)
+    return raw.decode("utf-16-le", errors="replace")
+def encode_foldout_title(text: str) -> str:
+    invalid = sorted({char for char in text if char in _GROUP_INVALID})
+    if invalid:
+        rendered = " ".join(repr(char) for char in invalid)
+        raise ValueError(f"group title contains characters rejected by ASE: {rendered}")
+    raw = text.encode("utf-16-le", errors="surrogatepass")
+    values = [int.from_bytes(raw[i:i + 2], "little") for i in range(0, len(raw), 2)]
+    return "".join(chr(value) if value <= 127 else f"#{value:04x}" for value in values)
+def decode_foldout_title(value: str) -> str:
+    def replace(match: re.Match[str]) -> str:
+        return chr(int(match.group(1), 16))
+    decoded = re.sub(r"#([0-9A-Fa-f]{4})", replace, value)
+    return decoded.encode("utf-16-le", errors="surrogatepass").decode("utf-16-le", errors="replace")
+def is_material_property_node(node: NodeLine) -> bool:
+    return len(node.raw_fields) > 7 and node.raw_fields[6] == "Property"
+def parse_property_metadata_attribute(raw: str) -> dict:
+    match = _ATTRIBUTE_RE.fullmatch(raw)
+    if not match:
+        raise ValueError(f"invalid property metadata serialization: {raw!r}")
+    type_name = match.group("type")
+    args = match.group("args")
+    result = {"type": type_name, "raw": raw, "args": args}
+    if args is not None and type_name in {"ASECLITooltip", "ASECLIHelpBox", "TooltipMzgui", "HelpBoxMzgui"}:
+        result["text"] = decode_custom_unicode(args)
+    elif args is not None and type_name in {"ASECLIEnableIf", "EnableIfMzgui"}:
+        result["condition"] = parse_enable_if_arguments(args)
+    elif args is not None and type_name in {"ASECLIFoldout", "FoldoutMzgui"}:
+        result["text"] = decode_foldout_title(args)
+    return result
+def read_property_metadata_tail(graph: AseGraph, node: NodeLine) -> PropertyMetadataTail:
+    require_property_metadata_tail_version(graph)
+    if not is_material_property_node(node):
+        raise ValueError(f"node {node.node_id} is not an exported PropertyNode")
+    fields = node.raw_fields
+    for index in range(len(fields) - 1, 5, -1):
+        value = fields[index]
+        if not value.isdigit():
+            continue
+        count = int(value)
+        if count != len(fields) - index - 1:
+            continue
+        attributes = fields[index + 1 :]
+        try:
+            for attribute in attributes:
+                parse_property_metadata_attribute(attribute)
+        except ValueError:
+            continue
+        return PropertyMetadataTail(index, tuple(attributes))
+    raise ValueError(f"node {node.node_id} has no valid property metadata serialization tail")
+def _validated_raw_attribute(raw: str) -> tuple[str, str]:
+    if any(char in raw for char in (";", "\r", "\n", "\"", "'", "\\")):
+        raise ValueError("raw property metadata attribute contains a forbidden serialization character")
+    parsed = parse_property_metadata_attribute(raw)
+    type_name = str(parsed["type"])
+    canonical_type = canonical_property_metadata_type(type_name)
+    if canonical_type is None:
+        raise ValueError(
+            "unsupported MZGUI-compatible property metadata attribute type: " + type_name
+        )
+    return canonical_type, raw
+def set_property_metadata_attribute(graph: AseGraph, node_id: str, raw: str) -> dict:
+    type_name, raw = _validated_raw_attribute(raw)
+    node = graph.node_by_id(node_id)
+    if node is None:
+        raise KeyError(f"node {node_id} not found")
+    tail = read_property_metadata_tail(graph, node)
+    attributes = list(tail.attributes)
+    matching = [
+        index
+        for index, item in enumerate(attributes)
+        if parse_property_metadata_attribute(item)["type"]
+        in equivalent_property_metadata_types(type_name)
+    ]
+    before = [attributes[i] for i in matching]
+    if matching:
+        first = matching[0]
+        attributes[first] = raw
+        for index in reversed(matching[1:]):
+            del attributes[index]
+    else:
+        attributes.append(raw)
+    _write_property_metadata_tail(graph, node, tail.count_index, attributes)
+    return {"kind": "property_metadata", "node_id": node_id, "type": type_name, "before": before, "after": raw}
+def remove_property_metadata_attribute(graph: AseGraph, node_id: str, type_name: str) -> dict:
+    canonical_type = canonical_property_metadata_type(type_name)
+    if canonical_type is None:
+        raise ValueError(f"unsupported MZGUI-compatible property metadata attribute type: {type_name}")
+    node = graph.node_by_id(node_id)
+    if node is None:
+        raise KeyError(f"node {node_id} not found")
+    tail = read_property_metadata_tail(graph, node)
+    types = equivalent_property_metadata_types(canonical_type)
+    removed = [item for item in tail.attributes if parse_property_metadata_attribute(item)["type"] in types]
+    kept = [item for item in tail.attributes if parse_property_metadata_attribute(item)["type"] not in types]
+    _write_property_metadata_tail(graph, node, tail.count_index, kept)
+    return {"kind": "property_metadata", "node_id": node_id, "type": canonical_type, "removed": removed}
+def _write_property_metadata_tail(graph: AseGraph, node: NodeLine, count_index: int, attributes: list[str]) -> None:
+    node.raw_fields = node.raw_fields[:count_index] + [str(len(attributes)), *attributes]
+    graph.replace_node(node)
+def semantic_attribute(type_name: str, text: str) -> str:
+    if len(text) > 4096:
+        raise ValueError("custom GUI text must not exceed 4096 characters")
+    canonical_type = canonical_property_metadata_type(type_name)
+    if canonical_type is None:
+        raise ValueError(f"no text semantic encoder for {type_name}")
+    if canonical_type == "FoldoutMzgui":
+        encoded = encode_foldout_title(text)
+    elif canonical_type in {"TooltipMzgui", "HelpBoxMzgui"}:
+        encoded = encode_custom_unicode(text)
+    else:
+        raise ValueError(f"no text semantic encoder for {type_name}")
+    return f"[{type_name}({encoded})]"
+def inspect_custom_gui(ase_file: AseFile) -> dict:
+    main = main_master_node(ase_file.graph)
+    graph_editor = main.raw_fields[9] or None
+    compiled_editor = compiled_custom_editor(ase_file)
+    properties = []
+    property_metadata_tail_supported = ase_file.graph.version in PROPERTY_METADATA_TAIL_GRAPH_VERSIONS
+    if property_metadata_tail_supported:
+        for node in ase_file.graph.nodes:
+            if not is_material_property_node(node):
+                continue
+            tail = read_property_metadata_tail(ase_file.graph, node)
+            properties.append(
+                {
+                    "node_id": node.node_id,
+                    "node_type": node.type_name,
+                    "property_name": node.raw_fields[7] if len(node.raw_fields) > 7 else None, "order_index": int(node.raw_fields[9]),
+                    "display_name": node.raw_fields[8] if len(node.raw_fields) > 8 else None,
+                    "attributes": [parse_property_metadata_attribute(raw) for raw in tail.attributes],
+                }
+            )
+    editor = {"main_node_id": main.node_id, "graph": graph_editor,
+              "compiled": compiled_editor, "consistent": graph_editor == compiled_editor}
+    return {
+        "ase_profile": TARGET_ASE_VERSION,
+        "version_capabilities": {
+            "custom_editor": ase_file.graph.version in CUSTOM_EDITOR_GRAPH_VERSIONS,
+            "property_metadata_tail": property_metadata_tail_supported,
+        },
+        "profile_graph_version": TARGET_GRAPH_VERSION,
+        "graph_version": ase_file.graph.version,
+        "editor": editor,
+        "properties": properties,
+        "property_presentation": inspect_property_presentation(
+            editor, properties, ase_file.prefix, supported_editors=SUPPORTED_GUI_EDITORS
+        ),
+        "capabilities": {
+            "supported_editors": sorted(SUPPORTED_GUI_EDITORS),
+            "built_in_editor": MZGUI_EDITOR,
+            "legacy_fallback_editor": ASECLI_GUI_EDITOR,
+            "editor_suggestions": list(CUSTOM_EDITOR_SUGGESTIONS),
+            "property_attribute_types": list(PROPERTY_METADATA_ATTRIBUTE_TYPES),
+            "legacy_read_attribute_types": list(_ALTERNATE_ASECLI_ATTRIBUTE_TYPES),
+            "semantic_operations": {
+                "group": "FoldoutMzgui",
+                "tooltip": "TooltipMzgui",
+                "help_box": "HelpBoxMzgui",
+                "enabled_if": "EnableIfMzgui",
+            },
+            "shader_drawer_only": ["ShowIf"],
+        },
+    }

asecli/core/custom_gui_versions.py

@@ -0,0 +1,35 @@
+"""Verified ASE graph-version capabilities for custom material GUI metadata."""
+
+from __future__ import annotations
+
+from .model import AseGraph
+
+
+TARGET_ASE_VERSION = "1.9.6.2"
+TARGET_GRAPH_VERSION = "19602"
+CUSTOM_EDITOR_GRAPH_VERSIONS = frozenset(("19109", "19602"))
+PROPERTY_METADATA_TAIL_GRAPH_VERSIONS = frozenset(("19602",))
+
+
+def _require_graph_version(graph: AseGraph, supported: frozenset[str], capability: str) -> None:
+    try:
+        int(graph.version)
+    except ValueError as exc:
+        raise ValueError(f"unsupported non-numeric ASE graph version: {graph.version!r}") from exc
+    if graph.version not in supported:
+        versions = ", ".join(sorted(supported))
+        raise ValueError(
+            f"unsupported ASE graph version {graph.version!r} for {capability}; verified versions: {versions}"
+        )
+
+
+def require_custom_editor_version(graph: AseGraph) -> None:
+    _require_graph_version(graph, CUSTOM_EDITOR_GRAPH_VERSIONS, "serialized CustomEditor")
+
+
+def require_property_metadata_tail_version(graph: AseGraph) -> None:
+    _require_graph_version(
+        graph,
+        PROPERTY_METADATA_TAIL_GRAPH_VERSIONS,
+        "ASECLI property metadata",
+    )

asecli/core/fishbone_placement.py

@@ -0,0 +1,159 @@
+"""Geometric placement pass for a prepared recursive fishbone topology."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass
+from typing import Mapping, Protocol
+
+from .layout_graph import id_key, node_position, node_rect, overlaps_with_gap, round_coord, sibling_gap
+from .wire_router import WIRE_NODE_TYPE
+
+HORIZONTAL_GAP = 96.0
+SIBLING_GAP = 32.0
+MODULE_GAP = 96.0
+
+
+class Geometry(Protocol):
+    width: float
+    height: float
+    input_ports: dict[str, tuple[float, float]]
+    output_ports: dict[str, tuple[float, float]]
+
+
+@dataclass
+class _Template:
+    positions: dict[str, float]
+    bounds: tuple[float, float, float, float]
+
+
+def place_fishbone(graph, geometry: Mapping[str, Geometry], topology):
+    roots = topology.roots
+    main = roots[0]
+    anchor_x, anchor_y = node_position(graph.node_by_id(main))
+    x_by_node = {root: anchor_x for root in roots}
+    stage_output_x = {}
+    ordered_parents = sorted(
+        topology.ids - topology.satellites,
+        key=lambda node_id: (topology.depths[node_id], id_key(node_id)),
+    )
+    for parent in ordered_parents:
+        if parent not in x_by_node:
+            continue
+        # Every node owns a local fishbone stage. Its direct sources share one
+        # output anchor line 96px before the consumer, while independent
+        # branches are not stretched to an unrelated global depth column.
+        launch_x = round_coord(x_by_node[parent] - HORIZONTAL_GAP)
+        for child in topology.children[parent]:
+            wire = topology.primary_wire[(child, parent)]
+            output_dx = geometry[child].output_ports[wire.out_port][0]
+            x_by_node[child] = launch_x - output_dx
+            stage_output_x[child] = launch_x
+
+    templates: dict[str, _Template] = {}
+
+    def build(node_id: str) -> _Template:
+        if node_id in templates:
+            return templates[node_id]
+        positions_y = {node_id: 0.0}
+        own = (
+            x_by_node[node_id], 0.0,
+            x_by_node[node_id] + geometry[node_id].width, geometry[node_id].height,
+        )
+        branch = topology.children[node_id]
+        if not branch:
+            templates[node_id] = _Template(positions_y, own)
+            return templates[node_id]
+        local = {child: build(child) for child in branch}
+        spine = topology.spine_child[node_id]
+        wire = topology.primary_wire[(spine, node_id)]
+        shifts = {
+            spine: geometry[node_id].input_ports[wire.in_port][1]
+            - geometry[spine].output_ports[wire.out_port][1]
+        }
+        spine_bounds = _shift(local[spine].bounds, shifts[spine])
+        spine_index = branch.index(spine)
+        upper_cursor = min(own[1], spine_bounds[1])
+        for index in range(spine_index - 1, -1, -1):
+            child, next_child = branch[index], branch[index + 1]
+            gap = sibling_gap(child, next_child, topology.group_of, SIBLING_GAP, MODULE_GAP)
+            shifts[child] = upper_cursor - gap - local[child].bounds[3]
+            upper_cursor = local[child].bounds[1] + shifts[child]
+        lower_cursor = max(own[3], spine_bounds[3])
+        for index in range(spine_index + 1, len(branch)):
+            child, previous = branch[index], branch[index - 1]
+            gap = sibling_gap(previous, child, topology.group_of, SIBLING_GAP, MODULE_GAP)
+            shifts[child] = lower_cursor + gap - local[child].bounds[1]
+            lower_cursor = local[child].bounds[3] + shifts[child]
+        bounds = [own]
+        for child in branch:
+            shift = shifts[child]
+            for member, y in local[child].positions.items():
+                positions_y[member] = y + shift
+            bounds.append(_shift(local[child].bounds, shift))
+        templates[node_id] = _Template(positions_y, _union(bounds))
+        return templates[node_id]
+
+    positions, ordered_roots = {}, [main]
+    main_template = build(main)
+    for node_id, relative_y in main_template.positions.items():
+        positions[node_id] = (round_coord(x_by_node[node_id]), round_coord(anchor_y + relative_y))
+    cursor = main_template.bounds[3] + anchor_y + MODULE_GAP
+    bundles: dict[tuple[str, str], list[str]] = defaultdict(list)
+    for root in roots[1:]:
+        owner = topology.group_of.get(root)
+        bundles[("comment", owner) if owner else ("node", root)].append(root)
+    ordered_bundles = sorted(
+        bundles.values(),
+        key=lambda bundle: (
+            min(topology.current_y[item] for item in bundle), min(id_key(item) for item in bundle),
+        ),
+    )
+    for bundle in ordered_bundles:
+        bundle.sort(key=lambda item: (topology.current_y[item], id_key(item)))
+        for index, root in enumerate(bundle):
+            template = build(root)
+            shift = cursor - template.bounds[1]
+            for node_id, relative_y in template.positions.items():
+                positions[node_id] = (round_coord(x_by_node[node_id]), round_coord(relative_y + shift))
+            ordered_roots.append(root)
+            cursor = template.bounds[3] + shift + (SIBLING_GAP if index + 1 < len(bundle) else MODULE_GAP)
+
+    _place_registers(topology, geometry, positions)
+    for node in graph.nodes:
+        if node.type_name == WIRE_NODE_TYPE:
+            positions[node.node_id] = node_position(node)
+    return positions, ordered_roots, stage_output_x
+
+
+def _place_registers(topology, geometry, positions):
+    for register_id in sorted(topology.satellites, key=id_key):
+        incoming = sorted(
+            (wire for wire in topology.collapsed_wires if wire.in_node == register_id),
+            key=lambda wire: (id_key(wire.out_node), wire.in_port),
+        )
+        wire = incoming[0]
+        source = wire.out_node
+        source_rect = node_rect(source, positions, geometry)
+        x = source_rect[2] + HORIZONTAL_GAP
+        source_y = positions[source][1] + geometry[source].output_ports[wire.out_port][1]
+        y = source_y - geometry[register_id].input_ports[wire.in_port][1]
+        candidate = (x, y, x + geometry[register_id].width, y + geometry[register_id].height)
+        occupied = [node_rect(item, positions, geometry) for item in positions]
+        while any(overlaps_with_gap(candidate, rect, SIBLING_GAP) for rect in occupied):
+            y += geometry[register_id].height + SIBLING_GAP
+            candidate = (x, y, x + geometry[register_id].width, y + geometry[register_id].height)
+        positions[register_id] = round_coord(x), round_coord(y)
+        topology.depths[register_id] = max(0, topology.depths[source] - 1)
+
+
+def _shift(bounds, dy):
+    return bounds[0], bounds[1] + dy, bounds[2], bounds[3] + dy
+
+
+def _union(rects):
+    values = list(rects)
+    return (
+        min(rect[0] for rect in values), min(rect[1] for rect in values),
+        max(rect[2] for rect in values), max(rect[3] for rect in values),
+    )