nexus_map_codebase.py

import ast
import json
import os
import sys
import argparse
import tempfile
import random
import string
from datetime import datetime
from typing import List, Dict, Any, Optional, Tuple

import re
import unicodedata
from markdown_it import MarkdownIt
import mdformat

try:
    from tree_sitter import Parser
    from tree_sitter_language_pack import get_language, get_parser
    _HAVE_TREE_SITTER = True
except Exception:
    Parser = None  # type: ignore[assignment]
    get_language = None  # type: ignore[assignment]
    get_parser = None  # type: ignore[assignment]
    _HAVE_TREE_SITTER = False

# Force UTF-8 output for Windows console
if sys.platform == 'win32':
    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
    sys.stderr.reconfigure(encoding='utf-8', errors='replace')


# CARTOGRAPHER CORE PLAN:
# This file is the heart of Cartographer: portable file-note generation,
# multi-language outline parsing, beacon parsing/application, and on-disk beacon
# update helpers. Preserve it in Core v1 alongside the snippet engine.
# @beacon[
#   id=nmcv1@file-core,
#   role=core keeper: cartographer mapping, beacon parsing, and beacon-update engine,
#   slice_labels=nexus-portability,nexus-core-v1,
#   kind=span,
#   show_span=false,
# ]
# CORE V1 KEEPER:
# Preserve the portable note/header model, MD_PATH identity machinery, semantic
# whitening, and Cartographer-aware reconcile semantics. These are central to
# transferable installs and stable F12 refresh behavior.
# @beacon[
#   id=nmcv1@portable-note-and-identity-core,
#   role=core keeper: portable note format plus markdown and identity reconciliation semantics,
#   slice_labels=nexus-portability,nexus-core-v1,
#   kind=span,
#   show_span=false,
# ]
# @beacon[
#   id=auto-beacon@_warn_name-ts8n,
#   role=_warn_name,
#   slice_labels=f9-f12-handlers,ra-reconcile,carto-js-ts,
#   kind=ast,
# ]
def _warn_name(base: str) -> str:
    """Append generation timestamp so stale warning nodes are visibly old."""
    ts = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
    return f"{base} [{ts}]"

# --- Configuration (Synced) ---

# @beacon[
#   id=auto-beacon@EMOJI_FOLDER-1o5m,
#   role=EMOJI_FOLDER — 📂 folder,
#   slice_labels=ra-notes,ra-notes-salvage,
#   kind=span,
# ]
EMOJI_FOLDER = "📂"
# @beacon-close[
#   id=auto-beacon@EMOJI_FOLDER-1o5m,
# ]

# @beacon[
#   id=auto-beacon@EMOJI_FILE-0c0j,
#   role=EMOJI_FILE — 📄 file,
#   slice_labels=ra-notes,ra-notes-salvage,
#   kind=span,
# ]
EMOJI_FILE = "📄"
# @beacon-close[
#   id=auto-beacon@EMOJI_FILE-0c0j,
# ]

# @beacon[
#   id=auto-beacon@EMOJI_PYTHON-pp3q,
#   role=EMOJI_PYTHON — 🐍 .py,
#   slice_labels=ra-notes,ra-notes-salvage,
#   kind=span,
# ]
EMOJI_PYTHON = "🐍"
# @beacon-close[
#   id=auto-beacon@EMOJI_PYTHON-pp3q,
# ]

# @beacon[
#   id=auto-beacon@EMOJI_MARKDOWN-nq2i,
#   role=EMOJI_MARKDOWN — 📘 .md,
#   slice_labels=ra-notes,ra-notes-salvage,
#   kind=span,
# ]
EMOJI_MARKDOWN = "📘"
# @beacon-close[
#   id=auto-beacon@EMOJI_MARKDOWN-nq2i,
# ]

# @beacon[
#   id=auto-beacon@EMOJI_SQL-1x3e,
#   role=EMOJI_SQL — 🗄️ .sql,
#   slice_labels=ra-notes,ra-notes-salvage,
#   kind=span,
# ]
EMOJI_SQL = "🗄️"
# @beacon-close[
#   id=auto-beacon@EMOJI_SQL-1x3e,
# ]

# @beacon[
#   id=auto-beacon@EMOJI_SHELL-n7l1,
#   role=EMOJI_SHELL — 🐚 shell,
#   slice_labels=ra-notes,ra-notes-salvage,
#   kind=span,
# ]
EMOJI_SHELL = "🐚"
# @beacon-close[
#   id=auto-beacon@EMOJI_SHELL-n7l1,
# ]

# @beacon[
#   id=auto-beacon@EMOJI_CLASS-td8j,
#   role=EMOJI_CLASS — 📦 class,
#   slice_labels=ra-notes,ra-notes-salvage,
#   kind=span,
# ]
EMOJI_CLASS = "📦"
# @beacon-close[
#   id=auto-beacon@EMOJI_CLASS-td8j,
# ]

# @beacon[
#   id=auto-beacon@EMOJI_FUNC-l9m0,
#   role=EMOJI_FUNC — ƒ function,
#   slice_labels=ra-notes,ra-notes-salvage,
#   kind=span,
# ]
EMOJI_FUNC = "ƒ"
# @beacon-close[
#   id=auto-beacon@EMOJI_FUNC-l9m0,
# ]

# @beacon[
#   id=auto-beacon@EMOJI_ASYNC-zx2s,
#   role=EMOJI_ASYNC — ⚡ async,
#   slice_labels=ra-notes,ra-notes-salvage,
#   kind=span,
# ]
EMOJI_ASYNC = "⚡"
# @beacon-close[
#   id=auto-beacon@EMOJI_ASYNC-zx2s,
# ]

# @beacon[
#   id=auto-beacon@EMOJI_CONST-4qzz,
#   role=EMOJI_CONST — 💎 const,
#   slice_labels=ra-notes,ra-notes-salvage,
#   kind=span,
# ]
EMOJI_CONST = "💎"
# @beacon-close[
#   id=auto-beacon@EMOJI_CONST-4qzz,
# ]

# @beacon[
#   id=auto-beacon@EMOJI_JS-y6yc,
#   role=EMOJI_JS — 🟨 .js,
#   slice_labels=ra-notes,ra-notes-salvage,
#   kind=span,
# ]
EMOJI_JS = "🟨"
# @beacon-close[
#   id=auto-beacon@EMOJI_JS-y6yc,
# ]

# @beacon[
#   id=auto-beacon@EMOJI_TS-98pq,
#   role=EMOJI_TS — 🟦 .ts,
#   slice_labels=ra-notes,ra-notes-salvage,
#   kind=span,
# ]
EMOJI_TS = "🟦"
# @beacon-close[
#   id=auto-beacon@EMOJI_TS-98pq,
# ]

# @beacon[
#   id=auto-beacon@EMOJI_VUE-m8x1,
#   role=EMOJI_VUE — 🟩 .vue,
#   slice_labels=ra-notes,ra-notes-salvage,
#   kind=span,
# ]
EMOJI_VUE = "🟩"
# @beacon-close[
#   id=auto-beacon@EMOJI_VUE-m8x1,
# ]

# Debug flags (controlled via environment variables)
DEBUG_MD_BEACONS = bool(os.environ.get("CARTOGRAPHER_MD_BEACONS"))


def _get_line_count(path: str) -> Optional[int]:
    """Return number of lines in a text file, or None on error.

    Used to annotate FILE nodes with LINE COUNT in their Workflowy notes.
    """
    try:
        with open(path, "r", encoding="utf-8") as f:
            return sum(1 for _ in f)
    except Exception:
        return None


def _portable_relpath(abs_path: str, repo_root: str) -> str | None:
    """Return a portable (forward-slash) relpath, or None if not safe/possible."""
    try:
        # Normalize separators but keep semantics.
        abs_norm = os.path.normpath(abs_path)
        root_norm = os.path.normpath(repo_root)

        # os.path.commonpath throws on Windows when drives differ.
        common = os.path.commonpath([abs_norm, root_norm])
        if os.path.normcase(common) != os.path.normcase(root_norm):
            return None

        rel = os.path.relpath(abs_norm, root_norm)
        rel = rel.replace("\\", "/")
        if not rel or rel.startswith(".."):
            return None
        return rel
    except Exception:
        return None


def format_file_note(
    path: str,
    line_count: int | None = None,
    sha1: str | None = None,
    *,
    repo_root: str | None = None,
) -> str:
    """Format the standard FILE-node note header.

    Shared between Cartographer (map_codebase) and per-file beacon refresh
    (refresh_file_node_beacons) so that FILE nodes always expose a consistent
    header block.

    Portability policy (PR2 - segments mode):
    - When repo_root is provided and `path` is under repo_root, store ONLY the
      final path segment in the note (folder name or filename). This makes
      Cartographer Workflowy trees portable and robust under folder moves.
    - Otherwise (no Root context), store the raw absolute path.

        Path: ...
        LINE COUNT: N
        Source-SHA1: ...

    LINE COUNT and Source-SHA1 are optional and omitted when not provided.
    """
    used_path = path

    # Segments mode: when we are in a Root-mapped tree (repo_root provided)
    # and this path is under repo_root, store ONLY the final segment.
    if repo_root and isinstance(path, str) and isinstance(repo_root, str):
        try:
            if os.path.isabs(path) and os.path.isabs(repo_root):
                root_norm = os.path.normcase(os.path.normpath(repo_root))
                path_norm = os.path.normcase(os.path.normpath(path))
                if os.path.commonpath([path_norm, root_norm]) == root_norm:
                    # Strip trailing separators so basename works for directories.
                    seg = os.path.basename(path.rstrip("\\/"))
                    if seg:
                        used_path = seg
        except Exception:
            # Fail closed: if any path math goes sideways, keep raw path.
            used_path = path

    lines: list[str] = [f"Path: {used_path}"]
    if line_count is not None:
        lines.append(f"LINE COUNT: {line_count}")
    if sha1 is not None:
        lines.append(f"Source-SHA1: {sha1}")
    return "\n".join(lines)


# --- Parsers ---

# @beacon[
#   id=auto-beacon@tokens_to_nexus_tree-fcan,
#   role=tokens_to_nexus_tree,
#   slice_labels=nexus-md-header-path,ra-snippet-range-ast-md,
#   kind=ast,
# ]
def tokens_to_nexus_tree(
    tokens,
    source_lines: Optional[List[str]] = None,
) -> List[Dict[str, Any]]:
    """Convert markdown-it-py token stream to NEXUS hierarchical tree.

    Assigns priority values based on document order (100, 200, 300, ...).
    Lower priority = appears first in document.

    v2.2: For each Markdown heading node, writes an explicit MD_PATH block into
    the note:

        MD_PATH:
        # Top
        ## Section
        ### Subsection
        ---
        <existing heading content>

    v2.3: When ``source_lines`` are provided, each heading node's note body is
    taken from the exact raw Markdown lines that belong *directly* to that
    heading (after the heading line and before the next heading of any level).
    This preserves nested ordered/bullet lists, indentation, fenced code
    blocks, and numbering verbatim instead of reconstructing them token by
    token.

    This mirrors Python's AST_QUALNAME header and is consumed by
    get_snippet_for_md_path in beacon_obtain_code_snippet.py.
    """
    root_children: List[Dict[str, Any]] = []
    # Stack of (heading_level, nexus_node)
    stack: List[tuple[int, Dict[str, Any]]] = []
    priority_counter = 100
    heading_entries: List[Dict[str, Any]] = []
    excluded_body_lines: set[int] = set()

    i = 0
    while i < len(tokens):
        token = tokens[i]

        if token.type == "html_block" and (
            "@beacon[" in (token.content or "") or "@beacon-close[" in (token.content or "")
        ):
            token_map = getattr(token, "map", None)
            if token_map:
                start0, end0 = token_map
                for line_no in range(start0 + 1, end0 + 1):
                    excluded_body_lines.add(line_no)
            i += 1
            continue

        if token.type != "heading_open":
            i += 1
            continue

        # Start of a heading
        heading_level = int(token.tag[1])  # h1 -> 1, h2 -> 2, etc.

        # Get the heading text from next token (should be inline)
        heading_text = ""
        if i + 1 < len(tokens) and tokens[i + 1].type == "inline":
            heading_text = tokens[i + 1].content

        # Pop stack until we find the correct parent level for this heading
        while stack and stack[-1][0] >= heading_level:
            stack.pop()

        # Build MD_PATH lines from current ancestor stack + this heading
        md_path_lines: List[str] = []
        for lvl, ancestor_node in stack:
            ancestor_name = (ancestor_node.get("name") or "").strip() or "..."
            md_path_lines.append(f"{('#' * lvl)} {ancestor_name}".rstrip())
        this_heading_name = heading_text or "..."
        md_path_lines.append(f"{('#' * heading_level)} {this_heading_name}".rstrip())

        note_lines: List[str] = ["MD_PATH:"]
        note_lines.extend(md_path_lines)
        note_lines.append("---")
        note_text = "\n".join(note_lines)

        # Create NEXUS node
        nexus_node: Dict[str, Any] = {
            "name": this_heading_name,
            "priority": priority_counter,
            "note": note_text,
            "children": [],
        }
        priority_counter += 100

        # Add to parent (or root if stack empty)
        if stack:
            stack[-1][1]["children"].append(nexus_node)
        else:
            root_children.append(nexus_node)

        # Determine source line span for the heading itself so we can attach the
        # raw body that follows it verbatim.
        token_map = getattr(token, "map", None)
        if token_map:
            heading_start0, heading_end0 = token_map
        elif i + 1 < len(tokens) and getattr(tokens[i + 1], "map", None):
            heading_start0, heading_end0 = tokens[i + 1].map
        else:
            heading_start0 = 0
            heading_end0 = 0

        heading_entries.append(
            {
                "node": nexus_node,
                "heading_start_line": heading_start0 + 1,
                "body_start_line": heading_end0 + 1,
            }
        )

        # Push this heading onto stack
        stack.append((heading_level, nexus_node))

        # Skip the inline and heading_close tokens
        i += 3  # heading_open, inline, heading_close

    if source_lines is not None and heading_entries:
        total_lines = len(source_lines)
        for idx, entry in enumerate(heading_entries):
            body_start_line = int(entry["body_start_line"])
            next_heading_start = (
                int(heading_entries[idx + 1]["heading_start_line"])
                if idx + 1 < len(heading_entries)
                else total_lines + 1
            )
            body_end_line = next_heading_start - 1

            body_lines: List[str] = []
            if body_end_line >= body_start_line:
                for line_no in range(body_start_line, body_end_line + 1):
                    if line_no in excluded_body_lines:
                        continue
                    body_lines.append(source_lines[line_no - 1])

                while body_lines and not body_lines[0].strip():
                    body_lines.pop(0)
                while body_lines and not body_lines[-1].strip():
                    body_lines.pop()

            if body_lines:
                entry["node"]["note"] = (
                    f"{entry['node']['note']}\n\n" + "\n".join(body_lines)
                )

    return root_children


# @beacon[
#   id=carto-js-ts@parse_markdown_beacon_blocks,
#   role=carto-js-ts,
#   slice_labels=carto-js-ts,carto-js-ts-beacons,f9-f12-handlers,ra-reconcile,nexus-md-header-path,
#   kind=span,
# ]
# Phase 2 JS/TS: Markdown beacon parser template.
# Reference for JS/TS block-comment beacons (/* @beacon[...] */),
# which use the same metadata fields and parsing pattern.
def parse_markdown_beacon_blocks(lines: list[str]) -> list[dict[str, Any]]:
    """Parse @beacon[...] HTML comment blocks from Markdown source.

    Expected form (we control this schema):

        <!--
        @beacon[
          id=docs:intro@1234,
          role=doc:intro,
          slice_labels=DOC,
          kind=span,
          start_snippet="# Heading text",
          comment=One-line human note,
        ]
        -->

    Returns a list of dicts with keys:
        id, role, slice_labels, kind, start_snippet, end_snippet,
        comment, comment_line, span_lineno_start, span_lineno_end,
        kind_explicit.
    """
    beacons: list[dict[str, Any]] = []
    n = len(lines)
    i = 0

    while i < n:
        line = lines[i]
        if "@beacon[" in line:
            comment_line = i + 1  # 1-based
            block_lines = [line]
            i += 1
            # Collect until a line containing ']' (inclusive)
            while i < n:
                block_lines.append(lines[i])
                if "]" in lines[i]:
                    i += 1
                    break
                i += 1

            # Parse block_lines into key/value pairs (skip first/last structural lines)
            fields: dict[str, str] = {}
            inner_lines = block_lines[1:-1] if len(block_lines) >= 2 else []
            for raw in inner_lines:
                text = raw.strip()
                if not text or text.startswith("@beacon"):
                    continue
                if text.startswith("<!--") or text.startswith("-->"):
                    continue
                # Drop trailing ',' or '],' or ']'
                while text and text[-1] in ",]":
                    text = text[:-1].rstrip()
                if not text or "=" not in text:
                    continue
                key, val = text.split("=", 1)
                key = key.strip()
                val = val.strip()
                # Strip surrounding quotes if present
                if (val.startswith("\"") and val.endswith("\"")) or (
                    val.startswith("'") and val.endswith("'")
                ):
                    val = val[1:-1]
                fields[key] = val

            kind_raw = fields.get("kind")
            kind = (kind_raw or "span").strip().lower() or "span"
            if kind not in {"ast", "span"}:
                continue

            show_span, show_span_explicit = _parse_show_span_fields(fields)

            start_snippet = fields.get("start_snippet")
            end_snippet = fields.get("end_snippet")

            span_start: Optional[int] = None
            span_end: Optional[int] = None

            if kind == "span" and start_snippet:
                norm_snip = normalize_for_match(start_snippet)
                if norm_snip:
                    # Find candidate start lines (global search), but IGNORE
                    # lines that are clearly part of the beacon metadata
                    # itself (the @beacon block and its key/value lines).
                    start_candidates: list[int] = []
                    for idx, src_line in enumerate(lines, start=1):
                        # Skip any line that looks like part of a @beacon
                        # comment block so we never anchor spans to their
                        # own metadata.
                        if "@beacon[" in src_line or "start_snippet=" in src_line or "end_snippet=" in src_line:
                            continue
                        if norm_snip in normalize_for_match(src_line):
                            start_candidates.append(idx)

                    if start_candidates:
                        if len(start_candidates) == 1:
                            span_start = start_candidates[0]
                        else:
                            after = [ln for ln in start_candidates if ln > comment_line]
                            if len(after) == 1:
                                span_start = after[0]
                            else:
                                # Ambiguous; require refinement
                                span_start = None

                    if span_start is not None:
                        if end_snippet:
                            norm_end = normalize_for_match(end_snippet)
                            for idx in range(span_start, len(lines) + 1):
                                if norm_end in normalize_for_match(lines[idx - 1]):
                                    span_end = idx
                                    break
                            if span_end is None:
                                # Explicit end_snippet but no match – leave span unset
                                span_start = None
                        else:
                            # Default: until just before next header (any level)
                            span_end = len(lines)
                            for idx in range(span_start + 1, len(lines) + 1):
                                if re.match(r"^#{1,6}\s", lines[idx - 1]):
                                    span_end = idx - 1
                                    break

            beacon = {
                "id": fields.get("id"),
                "role": fields.get("role"),
                "slice_labels": fields.get("slice_labels"),
                "kind": kind,
                "start_snippet": start_snippet,
                "end_snippet": end_snippet,
                "comment": (fields.get("comment") if fields.get("comment") not in (None, "") else fields.get("comments")),
                "comment_line": comment_line,
                "span_lineno_start": span_start,
                "span_lineno_end": span_end,
                "kind_explicit": bool(kind_raw),
                "show_span": show_span,
                "show_span_explicit": show_span_explicit,
            }
            beacons.append(beacon)
        else:
            i += 1

    # Second pass: compute span ranges for Markdown span beacons using @beacon-close[...]
    for beacon in beacons:
        if beacon.get("kind") != "span":
            continue

        # Only override when no span was set by start_snippet/end_snippet
        if beacon.get("span_lineno_start") is not None and beacon.get("span_lineno_end") is not None:
            continue

        b_id = (beacon.get("id") or "").strip()
        if not b_id:
            continue

        comment_line = beacon.get("comment_line")
        if not isinstance(comment_line, int) or not (1 <= comment_line <= n):
            continue

        # Find end of opener's metadata block (first line containing ']')
        j = comment_line
        open_end = comment_line
        while j <= n:
            raw = lines[j - 1]
            if "]" in raw:
                open_end = j
                break
            j += 1

        # Scan forward for matching @beacon-close[...] with same id
        close_comment_line = None
        k = open_end + 1
        while k <= n:
            raw = lines[k - 1]
            if "@beacon-close[" in raw:
                close_lines = [raw]
                k += 1
                while k <= n:
                    next_raw = lines[k - 1]
                    close_lines.append(next_raw)
                    if next_raw.strip().lstrip("#").lstrip().startswith("]"):
                        k += 1
                        break
                    k += 1

                close_id = None
                for cl in close_lines:
                    text = cl.strip()
                    # Strip HTML comment wrappers
                    if text.startswith("<!--"):
                        text = text[4:].lstrip()
                    if text.endswith("-->"):
                        text = text[:-3].rstrip()
                    # Drop trailing ',' and ']'
                    while text and text[-1] in ",]":
                        text = text[:-1].rstrip()
                    if "id=" in text:
                        _, val = text.split("=", 1)
                        close_id = val.strip()
                        break

                if close_id == b_id:
                    close_comment_line = k - len(close_lines)
                    break

            k += 1

        if close_comment_line is not None:
            inner_start = open_end + 1
            inner_end = close_comment_line - 1
            if inner_start <= inner_end:
                beacon["span_lineno_start"] = inner_start
                beacon["span_lineno_end"] = inner_end

    return beacons


def _extract_markdown_beacon_context(lines: list[str], comment_line: int) -> List[str]:
    """Extract nearby HTML comment lines (non-beacon) around a Markdown beacon.

    We look above and below the beacon's comment_line for HTML comments
    (<!-- ... -->) that do not contain @beacon[. Blank lines are skipped.
    """
    context: List[str] = []

    # Above
    j = comment_line - 1
    while j >= 1:
        stripped = lines[j - 1].strip()
        if not stripped:
            j -= 1
            continue
        if stripped.startswith("<!--") and "@beacon[" not in stripped:
            # Skip pure sentinel lines like "<!--" and "-->", but keep
            # single-line comments that actually contain text.
            if stripped != "<!--" and stripped != "-->":
                context.insert(0, stripped)
            j -= 1
            continue
        break

    # Below
    j = comment_line + 1
    while j <= len(lines):
        stripped = lines[j - 1].strip()
        if not stripped:
            j += 1
            continue
        if stripped.startswith("<!--") and "@beacon[" not in stripped:
            if stripped != "<!--" and stripped != "-->":
                context.append(stripped)
            j += 1
            continue
        break

    return _strip_beacon_meta_blocks_from_context(context)


# @beacon[
#   id=carto-js-ts@apply_markdown_beacons,
#   role=carto-js-ts,
#   slice_labels=carto-js-ts,carto-js-ts-beacons,ra-snippet-range-ast-beacon-md,nexus-md-header-path,
#   kind=span,
# ]
# Phase 2 JS/TS: Markdown beacon application template.
# Reference for apply_js_beacons(...) when attaching JS/TS span
# and AST beacons under headings / AST nodes with context comments.
def apply_markdown_beacons(
    lines: list[str],
    root_children: List[Dict[str, Any]],
    beacons: list[dict[str, Any]],
) -> None:
    """Attach Markdown beacons under headings or decorate headings directly.

    V2:
      - Supports both kind=span and kind=ast beacons.
      - kind=ast beacons decorate the nearest heading node's name and note.
      - kind=span beacons remain child nodes under the nearest enclosing
        heading (or at the top level if no heading is found).

    Auto-promotion:
      - For beacons where ``kind`` is *not* explicitly set and the first
        non-blank, non-HTML-comment line after the beacon block is a heading
        (e.g. a line starting with one or more ``#`` followed by a space),
        we auto-upgrade ``kind`` from ``span`` to ``ast``.
    """
    if not beacons or not root_children:
        return
    _prepend_duplicate_beacon_id_warning_nodes(root_children, beacons, language="MD")

    # Normalize kind and optionally auto-promote some span beacons to AST
    # based on their position relative to the next heading.
    for beacon in beacons:
        kind = (beacon.get("kind") or "span").strip().lower() or "span"
        beacon["kind"] = kind
        if kind != "span":
            continue
        # Only auto-promote when the user did not explicitly specify kind.
        if beacon.get("kind_explicit"):
            continue
        # Never auto-promote an explicit span region (paired opener/closer).
        if isinstance(beacon.get("span_lineno_end"), int):
            continue
        comment_line = beacon.get("comment_line") or 0
        if not isinstance(comment_line, int) or comment_line <= 0:
            continue
        # Find end of the @beacon[...] block (first line containing ']')
        block_end = comment_line
        k = comment_line
        while k <= len(lines):
            if "]" in lines[k - 1]:
                block_end = k
                # If the very next line closes the same HTML comment block,
                # treat that "-->" line as part of the beacon block so that
                # auto-promotion starts scanning AFTER the entire comment.
                if block_end < len(lines) and "-->" in lines[block_end]:
                    block_end += 1
                break
            k += 1
        j = block_end + 1
        in_html_comment = False
        while j <= len(lines):
            raw = lines[j - 1]
            stripped = raw.strip()
            if not stripped:
                j += 1
                continue
            # Track and skip non-beacon HTML comment blocks (multi-line), so
            # we only consider real content lines when deciding whether to
            # auto-promote this beacon to an AST beacon.
            if not in_html_comment and "<!--" in raw and "@beacon[" not in raw:
                in_html_comment = True
            if in_html_comment:
                if "-->" in raw:
                    in_html_comment = False
                j += 1
                continue
            # First significant line after the beacon block: if it's a
            # heading of any level (we accept up to 32 '#' chars for
            # extended Markdown), upgrade this beacon to AST.
            if re.match(r"^#{1,32}\s", stripped):
                beacon["kind"] = "ast"
            break

    def iter_nodes(nodes: List[Dict[str, Any]]):
        for node in nodes:
            yield node
            for ch in node.get("children") or []:
                if isinstance(ch, dict):
                    yield from iter_nodes([ch])

    all_nodes = list(iter_nodes(root_children))

    # Precompute heading positions (line numbers) in the Markdown source so
    # we can attach beacons relative to concrete headings.
    heading_positions: list[tuple[Dict[str, Any], int]] = []

    def _find_heading_lineno(heading_text: str) -> Optional[int]:
        """Find the line number of a Markdown heading whose text matches heading_text.

        We treat any line starting with 1–6 '#' characters followed by optional
        whitespace and then exactly heading_text as a match. This avoids regex
        edge-cases with f-strings and keeps the logic transparent.
        """
        if not heading_text:
            return None
        for idx, line in enumerate(lines, start=1):
            stripped = line.strip()
            if not stripped.startswith("#"):
                if DEBUG_MD_BEACONS:
                    print(
                        f"[MD-HEAD-CHECK] heading={heading_text!r} line={idx} text={stripped!r} (no # prefix)"
                    )
                continue
            # Count leading '#' characters
            hash_count = 0
            for ch in stripped:
                if ch == "#":
                    hash_count += 1
                else:
                    break
            if not (1 <= hash_count <= 6):
                if DEBUG_MD_BEACONS:
                    print(
                        f"[MD-HEAD-CHECK] heading={heading_text!r} line={idx} text={stripped!r} (hash_count={hash_count} out of range)"
                    )
                continue
            rest = stripped[hash_count:].lstrip()
            if DEBUG_MD_BEACONS:
                print(f"[MD-HEAD-CHECK] heading={heading_text!r} line={idx} rest={rest!r}")
            if rest == heading_text:
                if DEBUG_MD_BEACONS:
                    print(f"[MD-HEAD] name={heading_text!r} lineno={idx}")
                return idx
        return None

    for node in all_nodes:
        name = (node.get("name") or "").strip()
        if not name:
            continue
        ln = _find_heading_lineno(name)
        if ln is not None:
            heading_positions.append((node, ln))

    if DEBUG_MD_BEACONS and heading_positions:
        print("[MD-HEAD-LIST] headings:")
        for h_node, h_ln in heading_positions:
            print(f"  - name={h_node.get('name')!r} lineno={h_ln}")

    # PASS 1: AST beacons – decorate heading nodes.
    for beacon in beacons:
        if beacon.get("kind") != "ast":
            continue

        b_id = (beacon.get("id") or "").strip()
        role = (beacon.get("role") or "").strip()
        raw_slice_labels = (beacon.get("slice_labels") or "").strip()
        # Defaults: derive role from id prefix (before '@')
        if not role and b_id and "@" in b_id:
            role = b_id.split("@", 1)[0]
        slice_labels = _canonicalize_slice_labels(raw_slice_labels, role)

        display_role = role or b_id or "md-ast-beacon"
        display_slice = slice_labels or "-"
        tag_suffix = _slice_label_tags(slice_labels or display_slice)

        comment_line = beacon.get("comment_line") or 0
        owner: Optional[Dict[str, Any]] = None

        # Preferred: nearest heading *after* the beacon block.
        if isinstance(comment_line, int) and comment_line > 0 and heading_positions:
            best_node: Optional[Dict[str, Any]] = None
            best_lineno: Optional[int] = None
            for node, h_lineno in heading_positions:
                if h_lineno > comment_line and (best_lineno is None or h_lineno < best_lineno):
                    best_lineno = h_lineno
                    best_node = node
            if best_node is not None:
                owner = best_node

        # Fallback: use start_snippet text if it looks like a header line.
        if owner is None:
            start_snippet = beacon.get("start_snippet") or ""
            header_text = None
            m = (
                re.match(r"^#{1,32}\\s*(.*)", start_snippet.strip())
                if start_snippet
                else None
            )
            if m:
                header_text = m.group(1).strip()

            if header_text:
                norm_target = normalize_for_match(header_text)
                for node in all_nodes:
                    node_name = (node.get("name") or "")
                    node_norm = normalize_for_match(node_name)
                    if node_norm == norm_target or (
                        norm_target and norm_target in node_norm
                    ):
                        owner = node
                        break

        if owner is None:
            # If we couldn't find a heading to decorate, fall back to SPAN
            # semantics by resetting kind; the SPAN pass will handle it.
            beacon["kind"] = "span"
            continue

        name = owner.get("name") or "Untitled"
        if "🔱" not in name:
            name = f"{name} 🔱"
        if tag_suffix:
            name = f"{name} {tag_suffix}"
        owner["name"] = name

        context_lines = _extract_markdown_beacon_context(
            lines, beacon.get("comment_line") or 0
        )
        comment = beacon.get("comment")

        meta_lines = [
            "BEACON (MD AST)",
            f"id: {b_id}",
            f"role: {role}",
            f"slice_labels: {slice_labels}",
            "kind: ast",
        ]
        if comment:
            meta_lines.append(f"comment: {comment}")
        if context_lines:
            meta_lines.append("")
            meta_lines.append("CONTEXT COMMENTS (MD):")
            meta_lines.extend(context_lines)
        # Visual separator between beacon metadata and body text
        meta_lines.append("---")

        note = owner.get("note") or ""
        meta_block = "\n".join(meta_lines)
        if not note:
            owner["note"] = meta_block
        else:
            # Insert beacon metadata block just after the MD_PATH header
            # (the first line that is exactly '---' following 'MD_PATH:').
            lines_note = note.splitlines()
            insert_idx = len(lines_note)
            saw_md_path = False
            for idx, line in enumerate(lines_note):
                if line.strip() == "MD_PATH:":
                    saw_md_path = True
                elif saw_md_path and line.strip() == "---":
                    insert_idx = idx + 1
                    break
            new_lines: list[str] = []
            new_lines.extend(lines_note[:insert_idx])
            # Ensure a blank line before the beacon block when joining
            if insert_idx < len(lines_note) and lines_note[insert_idx].strip():
                new_lines.append("")
            new_lines.append(meta_block)
            # Blank line between beacon block and any existing body text
            if insert_idx < len(lines_note):
                if lines_note[insert_idx].strip():
                    new_lines.append("")
                new_lines.extend(lines_note[insert_idx:])
            owner["note"] = "\n".join(new_lines)

    # PASS 2: SPAN beacons – unchanged behavior, with optional comment support.
    for beacon in beacons:
        if beacon.get("kind") != "span":
            continue

        start_snippet = beacon.get("start_snippet") or ""
        span_start = beacon.get("span_lineno_start")
        span_end = beacon.get("span_lineno_end")
        # Fallback for snippet-less beacons: anchor to the line after the beacon block
        if span_start is None:
            comment_line = beacon.get("comment_line") or 0
            if isinstance(comment_line, int) and comment_line > 0:
                span_start = comment_line + 1

        # Derive heading text from start_snippet if it looks like a Markdown header
        header_text = None
        m = re.match(r"^#{1,6}\\s*(.*)", start_snippet.strip()) if start_snippet else None
        if m:
            header_text = m.group(1).strip()

        # Prefer the nearest preceding heading in the actual Markdown source,
        # using span_lineno_start as the anchor. This makes placement robust even
        # if start_snippet is not a header line.
        owner_header_text = None
        if isinstance(span_start, int):
            for idx in range(span_start, 0, -1):
                line = lines[idx - 1].strip()
                m2 = re.match(r"^#{1,6}\\s*(.*)", line)
                if m2:
                    owner_header_text = m2.group(1).strip()
                    break

        target_header = owner_header_text or header_text

        owner: Optional[Dict[str, Any]] = None

        # Preferred: line-number based nearest-previous-heading resolution.
        if isinstance(span_start, int) and heading_positions:
            best_node = None
            best_lineno = -1
            for node, h_lineno in heading_positions:
                if h_lineno <= span_start and h_lineno > best_lineno:
                    best_lineno = h_lineno
                    best_node = node
            if best_node is not None:
                owner = best_node

        # Fallback: header-text based resolution when line-based match fails.
        if owner is None and target_header:
            norm_target = normalize_for_match(target_header)
            for node in all_nodes:
                node_name = (node.get("name") or "")
                node_norm = normalize_for_match(node_name)
                if node_norm == norm_target or (
                    norm_target and norm_target in node_norm
                ):
                    owner = node
                    break

        b_id = (beacon.get("id") or "").strip()
        role = (beacon.get("role") or "").strip()
        raw_slice_labels = (beacon.get("slice_labels") or "").strip()
        # Defaults: derive role from id prefix (before '@')
        if not role and b_id and "@" in b_id:
            role = b_id.split("@", 1)[0]
        slice_labels = _canonicalize_slice_labels(raw_slice_labels, role)

        if DEBUG_MD_BEACONS:
            print(
                "[MD-BEACON] id=%r span_start=%r target_header=%r owner=%r" % (
                    b_id,
                    span_start,
                    target_header,
                    (owner.get("name") if owner else None),
                )
            )

        show_span, show_span_explicit = _beacon_show_span(beacon)

        display_role = role or b_id or "md-span-beacon"
        display_slice = slice_labels or "-"

        tag_suffix = _slice_label_tags(slice_labels or display_slice)
        name = f"🔱 {display_role}"
        if tag_suffix:
            name = f"{name} {tag_suffix}"

        context_lines = _extract_markdown_beacon_context(
            lines, beacon.get("comment_line") or 0
        )
        comment = beacon.get("comment")

        note_lines = [
            "BEACON (MD SPAN)",
            f"id: {b_id}",
            f"role: {role}",
            f"slice_labels: {slice_labels}",
            "kind: span",
        ]
        if show_span_explicit:
            note_lines.append(f"show_span: {'true' if show_span else 'false'}")
        if comment:
            note_lines.append(f"comment: {comment}")
        if context_lines:
            note_lines.append("")
            note_lines.append("CONTEXT COMMENTS (MD):")
            note_lines.extend(context_lines)

        # Raw Markdown span text between @beacon[...] and @beacon-close[...]
        span_text_lines: list[str] = []
        if isinstance(span_start, int) and isinstance(span_end, int):
            if 1 <= span_start <= span_end <= len(lines):
                span_text_lines = lines[span_start - 1 : span_end]
                # Trim leading/trailing blank lines inside the span
                while span_text_lines and not span_text_lines[0].strip():
                    span_text_lines.pop(0)
                while span_text_lines and not span_text_lines[-1].strip():
                    span_text_lines.pop()
        if show_span and span_text_lines:
            note_lines.append("")
            note_lines.append("SPAN TEXT:")
            note_lines.extend(span_text_lines)

        span_node = {
            "name": name,
            "note": "\n".join(note_lines),
            "children": [],
        }

        if owner is not None:
            children = owner.get("children") or []
            children.append(span_node)
            owner["children"] = children
        else:
            root_children.append(span_node)


# @beacon[
#   id=auto-beacon@_split_frontmatter_if_any-3p1h,
#   role=_split_frontmatter_if_any,
#   slice_labels=nexus-md-header-path,ra-snippet-range-ast-md,ra-reconcile,
#   kind=ast,
# ]
def _split_frontmatter_if_any(text: str | None) -> tuple[str | None, str]:
    """If text starts with valid YAML frontmatter, return (frontmatter, body).

    Frontmatter is defined as:
    - First line exactly '---' (no leading/trailing spaces)
    - A matching closing '---' on a later line

    If not present, returns (None, original_text).
    """
    if not isinstance(text, str):
        return None, ""

    lines = text.splitlines()
    if not lines or lines[0].strip() != "---":
        return None, text

    frontmatter_lines: list[str] = []
    body_lines: list[str] = []
    found_closing = False

    for idx, line in enumerate(lines[1:], start=1):
        if line.strip() == "---":
            found_closing = True
            body_lines = lines[idx + 1 :]
            break
        frontmatter_lines.append(line)

    if not found_closing:
        # Not a well-formed frontmatter block; treat as normal text.
        return None, text

    frontmatter = "\n".join(frontmatter_lines).strip("\n")
    body = "\n".join(body_lines)
    return frontmatter or None, body


# @beacon[
#   id=auto-beacon@_frontmatter_has_ignore_mdformat-y9k2,
#   role=_frontmatter_has_ignore_mdformat,
#   slice_labels=nexus-md-header-path,ra-snippet-range-ast-md,ra-reconcile,
#   kind=ast,
# ]
def _frontmatter_has_ignore_mdformat(frontmatter: str | None) -> bool:
    """Return True if frontmatter contains IGNORE_MDFORMAT set to a truthy value.

    - Field name is matched case-insensitively: IGNORE_MDFORMAT
    - Values treated as true (case-insensitive): true, yes, on, 1
    - Stops on first occurrence of the key.
    """
    if not isinstance(frontmatter, str):
        return False

    for raw in frontmatter.splitlines():
        line = raw.strip()
        if not line or line.startswith("#"):
            continue
        if ":" not in line:
            continue
        key, val = line.split(":", 1)
        if key.strip().lower() != "ignore_mdformat":
            continue
        v = val.strip().lower()
        if v in {"true", "yes", "on", "1"}:
            return True
        return False

    return False


# @beacon[
#   id=auto-beacon@parse_markdown_structure-z918,
#   role=parse_markdown_structure,
#   slice_labels=nexus-md-header-path,ra-snippet-range-ast-md,
#   kind=ast,
# ]
def parse_markdown_structure(file_path: str) -> List[Dict[str, Any]]:
    """Parses Markdown into NEXUS node tree using markdown-it-py.
    
    CRITICAL CHANGES (v2.0):
    1. Runs mdformat FIRST to normalize Markdown (fixes nested code blocks, etc.)
       unless a YAML frontmatter flag IGNORE_MDFORMAT is set to true.
    2. Uses markdown-it-py parser (battle-tested, CommonMark compliant)
    3. Assigns priority values based on document order (preserves ordering)
    4. Converts token stream to hierarchical NEXUS tree
    
    NO JUNK ALLOWED - mdformat enforces opinionated style before parsing,
    except for files that explicitly opt out via IGNORE_MDFORMAT.
    """
    try:
        # STEP 1: Load the Markdown source.
        with open(file_path, 'r', encoding='utf-8') as f:
            original_content = f.read()

        # STEP 1.1: Detect YAML frontmatter and per-file IGNORE_MDFORMAT flag.
        frontmatter, _body = _split_frontmatter_if_any(original_content)
        ignore_mdformat = _frontmatter_has_ignore_mdformat(frontmatter)

        if ignore_mdformat:
            # Skip mdformat entirely for this file; parse the raw content.
            body_for_parse = _body
            full_content_for_parse = original_content
            if DEBUG_MD_BEACONS:
                print(
                    f"[MD-FILE] path={file_path!r} (IGNORE_MDFORMAT=true; "
                    "skipping mdformat normalization)",
                )
        else:
            # STEP 1.2: Format the Markdown with mdformat FIRST (normalize before parsing).
            # This auto-repairs nested code blocks, whitespace, etc.
            body_for_parse = mdformat.text(_body)
            full_content_for_parse = (f"---\n{frontmatter}\n---\n" if frontmatter else "") + body_for_parse

            # Optional debug: show formatted Markdown with line numbers
            if DEBUG_MD_BEACONS:
                print(f"[MD-FILE] path={file_path!r}")
                print("[MD-FORMATTED-BEGIN]")
                for idx, line in enumerate(full_content_for_parse.splitlines(), start=1):
                    print(f"{idx:4d}: {line!r}")
                print("[MD-FORMATTED-END]")

            # STEP 1.3: Write formatted content BACK to source file (opinionated cleanup)
            with open(file_path, 'w', encoding='utf-8') as f:
                f.write(full_content_for_parse)

        lines = full_content_for_parse.splitlines()
        md_beacons = parse_markdown_beacon_blocks(lines)

        # STEP 2: Parse ONLY the body with markdown-it-py to avoid misinterpreting frontmatter
        md = MarkdownIt("commonmark")
        tokens = md.parse(body_for_parse)

        if DEBUG_MD_BEACONS:
            print("[MD-TOKENS-BEGIN]")
            for t in tokens:
                # t.map is (start_line, end_line) 0-based; add 1 for human-readable
                line_span = t.map if hasattr(t, 'map') and t.map is not None else None
                if line_span:
                    span_str = f"[{line_span[0]+1},{line_span[1]+1}]"
                else:
                    span_str = "[]"
                print(f"  type={t.type!r} tag={t.tag!r} map={span_str} content={t.content!r}")
            print("[MD-TOKENS-END]")
        
        # STEP 3: Convert token stream to NEXUS hierarchical tree with priorities.
        # Use the exact body lines from the parsed Markdown so list/code-block
        # structure is preserved verbatim inside heading notes.
        root_children = tokens_to_nexus_tree(tokens, source_lines=body_for_parse.splitlines())
        
        if frontmatter is not None:
            # Preserve frontmatter at the top of the tree so it survives round-trips
            root_children.insert(0, {
                "name": "⚙️ YAML Frontmatter",
                "priority": 0,
                "note": frontmatter,
                "children": []
            })
            
        if md_beacons:
            apply_markdown_beacons(lines, root_children, md_beacons)
        return root_children
        
    except Exception as e:
        return [{"name": _warn_name("⚠️ MD Parse Error"), "note": str(e), "children": []}]

def normalize_for_match(s: str) -> str:
    """Normalize a snippet or line for matching.

    V1: remove all whitespace characters so that `x=3` matches `x = 3`.
    This intentionally trades a tiny false-positive risk for robustness
    against formatting-only changes.
    """
    if not isinstance(s, str):
        return ""
    return "".join(ch for ch in s if not ch.isspace())


_TAG_LIKE_PATTERN = re.compile(r"<[A-Za-z_/][-A-Za-z0-9_/]*>")


# @beacon[
#   id=auto-beacon@whiten_text_for_header_compare-56c5,
#   role=whiten_text_for_header_compare,
#   slice_labels=nexus-md-header-path,ra-snippet-range-ast-md,
#   kind=ast,
# ]
def whiten_text_for_header_compare(text: str | None) -> str:
    """Whiten heading-like text for structural comparison.

    Used by Cartographer/F12/MD_PATH flows to decide whether two headings are
    "semantically the same" while preserving trailing #tags.

    Rules:
    - Strip simple HTML tags like <code>, </code>, <span>, </span> by pattern:
      <[A-Za-z_/][-A-Za-z0-9_/]*>
      (no whitespace or digits at the start, so "a < 5" is untouched).
    - Drop all backticks.
    - Drop emoji / Symbol, Other (So) codepoints.
    - Drop all whitespace.
    - Do NOT strip '#' or words, so tag changes still show up as differences.
    """
    if not isinstance(text, str):
        return ""
    s = text

    # Remove simple tag-like markup such as <code>, </code>, <span>, </span>.
    s = _TAG_LIKE_PATTERN.sub("", s)

    # Drop backticks used for inline code in Markdown.
    s = s.replace("`", "")

    # Normalize a small set of common HTML entities so textual comparisons
    # are robust to &lt;/&gt;/&amp;/&quot; vs their literal forms.
    html_entity_map = {
        "&quot;": '"',
        "&lt;": "<",
        "&gt;": ">",
        "&amp;": "&",
    }
    for ent, ch in html_entity_map.items():
        if ent in s:
            s = s.replace(ent, ch)

    # Drop double quotes entirely (including those produced from &quot;).
    s = s.replace('"', "")

    # Remove emoji / other symbolic decoration.
    #
    # NOTE: We *preserve* the trident (🔱) because it is a semantic UI marker
    # for Cartographer beacon-decorated nodes. If we strip it here, the
    # Cartographer no-op suppression in reconcile_trees_cartographer(...) will
    # treat names with/without 🔱 as equal and may "restore" the old Ether name,
    # causing the trident to vanish after a file refresh.
    _PRESERVE_SO = {"🔱"}
    s = "".join(ch for ch in s if unicodedata.category(ch) != "So" or ch in _PRESERVE_SO)

    # Collapse and remove whitespace entirely.
    s = re.sub(r"\s+", "", s)
    return s


# @beacon[
#   id=auto-beacon@_extract_beacon_id_from_note-ovd8,
#   role=_extract_beacon_id_from_note,
#   slice_labels=ra-reconcile,f9-f12-handlers,
#   kind=ast,
# ]
def _extract_beacon_id_from_note(note: str | None) -> str | None:
    """Extract beacon `id:` field from a node's note, if present.

    We deliberately do not try to distinguish AST vs SPAN kinds here; the
    id is expected to be unique within a single file's Cartographer subtree.
    """
    if not isinstance(note, str) or "BEACON (" not in note:
        return None
    for line in note.splitlines():
        stripped = line.strip()
        if stripped.startswith("id:"):
            val = stripped.split(":", 1)[1].strip()
            return val or None
    return None


# @beacon[
#   id=auto-beacon@_extract_ast_qualname_from_note-gzzl,
#   role=_extract_ast_qualname_from_note,
#   slice_labels=f9-f12-handlers,ra-reconcile,
#   kind=ast,
# ]
def _extract_ast_qualname_from_note(note: str | None) -> str | None:
    """Extract AST_QUALNAME from a node's note, if present."""
    if not isinstance(note, str):
        return None
    for line in note.splitlines():
        stripped = line.strip()
        if stripped.startswith("AST_QUALNAME:"):
            val = stripped.split(":", 1)[1].strip()
            return val or None
    return None


# @beacon[
#   id=carto-js-ts@_is_meaningful_js_local_name-p7m2,
#   role=_is_meaningful_js_local_name,
#   slice_labels=carto-js-ts,f9-f12-handlers,ra-reconcile,
#   kind=ast,
#   comment=Heuristic filter for noisy JS/TS local variables so F12 maps meaningful locals without single-letter spam.
# ]
def _is_meaningful_js_local_name(var_name: str | None) -> bool:
    """Return True when a JS/TS local variable name is worth mapping.

    Current heuristic is intentionally simple and conservative:
    - Drop names with fewer than 3 substantive chars after removing
      underscores/$.
      Examples: i, j, _, _i, $x, me, el

    We keep longer names for now because some locals are genuinely meaningful.
    """
    raw = (var_name or "").strip()
    if not raw:
        return False

    compact = re.sub(r"[_$]", "", raw)
    if len(compact) < 3:
        return False
    return True


# @beacon[
#   id=carto-js-ts@_new_js_scope_state-w1f9,
#   role=_new_js_scope_state,
#   slice_labels=carto-js-ts,f9-f12-handlers,ra-reconcile,
#   kind=ast,
#   comment=Create per-scope JS/TS parser state so anonymous lambda identities and local occurrence counters stay stable across formatting-only edits.
# ]
def _new_js_scope_state(*, is_lambda: bool) -> dict[str, Any]:
    """Return mutable parser state for one JS/TS scope."""
    return {
        "is_lambda": bool(is_lambda),
        "anon_counter": 0,
        "local_name_counts": {},
    }


# @beacon[
#   id=carto-js-ts@_js_next_anonymous_scope_name-x6c2,
#   role=_js_next_anonymous_scope_name,
#   slice_labels=carto-js-ts,f9-f12-handlers,ra-reconcile,
#   kind=ast,
#   comment=Assign stable parent-local ordinal identities to anonymous JS/TS lambda scopes instead of using file line numbers.
# ]
def _js_next_anonymous_scope_name(scope_state: dict[str, Any] | None) -> str:
    """Return the next anonymous-scope name for the current parent scope."""
    if not isinstance(scope_state, dict):
        return "__lambdao_1"

    next_n = int(scope_state.get("anon_counter") or 0) + 1
    scope_state["anon_counter"] = next_n
    return f"__lambdao_{next_n}"


# @beacon[
#   id=carto-js-ts@_js_next_lambda_local_suffix-r3d7,
#   role=_js_next_lambda_local_suffix,
#   slice_labels=carto-js-ts,f9-f12-handlers,ra-reconcile,
#   kind=ast,
#   comment=Assign stable occurrence-index suffixes to meaningful lambda-local declarations so comments and whitespace do not churn AST_QUALNAMEs.
# ]
def _js_next_lambda_local_suffix(scope_state: dict[str, Any] | None, var_name: str) -> str:
    """Return the next occurrence index for a lambda-local variable name."""
    if not isinstance(scope_state, dict):
        return "1"

    counts = scope_state.get("local_name_counts")
    if not isinstance(counts, dict):
        counts = {}
        scope_state["local_name_counts"] = counts

    next_n = int(counts.get(var_name) or 0) + 1
    counts[var_name] = next_n
    return str(next_n)


# @beacon[
#   id=auto-beacon@_extract_md_path_from_note-eihl,
#   role=_extract_md_path_from_note,
#   slice_labels=ra-snippet-range-ast-md,ra-reconcile,
#   kind=ast,
# ]
def _extract_md_path_from_note(note: str | None) -> list[str] | None:
    """Extract MD_PATH heading lines from a Markdown node's note, if any.

    Returns the raw heading lines (including leading '#' characters) between
    the 'MD_PATH:' sentinel and the terminating '---' line.
    """
    if not isinstance(note, str):
        return None
    lines = note.splitlines()
    in_block = False
    path_lines: list[str] = []
    for raw in lines:
        stripped = raw.strip()
        if not in_block:
            if stripped == "MD_PATH:":
                in_block = True
            continue
        if stripped == "---":
            break
        if stripped:
            # Preserve the heading text as written; callers may whiten it.
            path_lines.append(stripped)
    return path_lines or None


# @beacon[
#   id=auto-beacon@_find_markdown_heading_insert_idx-6t3r,
#   role=_find_markdown_heading_insert_idx,
#   slice_labels=nexus-md-header-path,ra-snippet-range-ast-md,f9-f12-handlers,ra-reconcile,
#   kind=ast,
# ]
def _find_markdown_heading_insert_idx(lines: list[str], md_path_lines: list[str]) -> Optional[int]:
    """Return the 0-based insertion index immediately above the heading for MD_PATH.

    This is the reverse/export twin of Markdown heading identity resolution:
    given raw file lines and an MD_PATH sequence, locate the unique heading line
    whose ancestor chain matches exactly. Returns None on zero/multiple matches.
    """
    if not lines or not md_path_lines:
        return None

    desired: list[tuple[int, str]] = []
    for raw in md_path_lines:
        s = (raw or "").strip()
        if not s:
            continue
        m = re.match(r"^(#{1,32})\s*(.*)$", s)
        if not m:
            return None
        level = len(m.group(1))
        text = whiten_text_for_header_compare((m.group(2) or "").strip()).casefold()
        desired.append((level, text))

    if not desired:
        return None

    md_text = "\n".join(lines)
    md = MarkdownIt("commonmark")
    tokens = md.parse(md_text)

    stack: list[tuple[int, str]] = []
    matches: list[int] = []
    for idx, token in enumerate(tokens):
        if token.type != "heading_open":
            continue

        try:
            level = int(token.tag[1]) if token.tag and len(token.tag) > 1 else 1
        except Exception:
            level = 1

        text = ""
        if idx + 1 < len(tokens) and tokens[idx + 1].type == "inline":
            text = tokens[idx + 1].content or ""
        norm = whiten_text_for_header_compare(text).casefold()

        while stack and stack[-1][0] >= level:
            stack.pop()
        stack.append((level, norm))

        start0 = None
        if getattr(token, "map", None):
            start0 = token.map[0]
        elif idx + 1 < len(tokens) and getattr(tokens[idx + 1], "map", None):
            start0 = tokens[idx + 1].map[0]
        if start0 is None:
            start0 = 0

        if len(stack) != len(desired):
            continue
        if all(stack[j][0] == desired[j][0] and stack[j][1] == desired[j][1] for j in range(len(desired))):
            matches.append(start0)

    if len(matches) != 1:
        return None
    return matches[0]


def _extract_vue_section_key_from_note(note: str | None) -> str | None:
    """Extract a stable identity key for Vue section nodes.

    Section nodes are virtual wrappers (template/script/style). They do not
    naturally have Beacon IDs or AST_QUALNAMEs, so name-only matching can
    cause churn when we adjust display formatting (e.g. '<script>' → '[script]').

    We therefore match section nodes by a key derived from their note fields.
    """
    if not isinstance(note, str):
        return None

    section: str | None = None
    content_row0: str | None = None
    script_index: str | None = None
    style_index: str | None = None

    for raw in note.splitlines():
        s = raw.strip()
        if s.startswith("VUE_SECTION:"):
            section = s.split(":", 1)[1].strip() or None
        elif s.startswith("VUE_CONTENT_ROW0:"):
            content_row0 = s.split(":", 1)[1].strip() or None
        elif s.startswith("VUE_SCRIPT_INDEX:"):
            script_index = s.split(":", 1)[1].strip() or None
        elif s.startswith("VUE_STYLE_INDEX:"):
            style_index = s.split(":", 1)[1].strip() or None

    if not section:
        return None

    # Prefer explicit indices when present.
    if script_index is not None:
        return f"{section}:script:{script_index}"
    if style_index is not None:
        return f"{section}:style:{style_index}"
    if content_row0 is not None:
        return f"{section}:row0:{content_row0}"

    return section


# @beacon[
#   id=auto-beacon@reconcile_trees_cartographer-2hsq,
#   role=reconcile_trees_cartographer,
#   slice_labels=ra-snippet-range-ast-md,ra-reconcile,f9-f12-handlers,nexus-md-header-path,
#   kind=ast,
# ]
def reconcile_trees_cartographer(source_node: Dict[str, Any], ether_node: Dict[str, Any]) -> None:
    """Reconcile a Cartographer-derived subtree against an existing ETHER tree.

    This variant is used for F12 / per-file Cartographer refresh. It prefers
    identity anchors over raw name matching:

      1. Beacon id (`id:` under BEACON (AST|SPAN)).
      2. AST_QUALNAME (Python AST nodes).
      3. MD_PATH header sequence for Markdown headings (each line whitened via
         ``whiten_text_for_header_compare``).
      4. Fallback: raw name equality.

    For nodes that are matched (i.e., share identity and thus an id), we then
    compare name and note using ``whiten_text_for_header_compare`` and, when
    they are semantically equal, we *restore* the ETHER value into the source
    tree. This lets the downstream WEAVE engine skip spurious updates caused
    purely by Workflowy whitening or formatting differences, while still
    propagating real changes (e.g. new tags or beacon metadata).
    """
    # Seed id on the root when present.
    if isinstance(ether_node, dict) and "id" in ether_node:
        source_node["id"] = ether_node["id"]

    source_children = [c for c in (source_node.get("children") or []) if isinstance(c, dict)]
    ether_children = [c for c in (ether_node.get("children") or []) if isinstance(c, dict)]

    if not source_children or not ether_children:
        return

    # Build Ether maps by identity anchor.
    ether_by_beacon: dict[str, dict[str, Any]] = {}
    ether_by_ast: dict[str, list[dict[str, Any]]] = {}
    ether_by_mdpath: dict[tuple[str, ...], list[dict[str, Any]]] = {}
    ether_by_vuekey: dict[str, dict[str, Any]] = {}
    ether_by_name: dict[str, list[dict[str, Any]]] = {}
    matched_ether_obj_ids: set[int] = set()

    def _candidate_if_unmatched(candidate: dict[str, Any] | None) -> dict[str, Any] | None:
        if not isinstance(candidate, dict):
            return None
        if id(candidate) in matched_ether_obj_ids:
            return None
        return candidate

    def _first_unmatched(candidates: list[dict[str, Any]] | None) -> dict[str, Any] | None:
        for candidate in candidates or []:
            if id(candidate) in matched_ether_obj_ids:
                continue
            return candidate
        return None

    # CARTO-DEBUG targeting is disabled by default; set this to a real
    # function name when focused instrumentation is needed.
    TARGET_FUNC = "__CARTO_DEBUG_TARGET_UNUSED__"
    import sys as _carto_debug_sys

    for e in ether_children:
        note_e = e.get("note") or ""
        name_e = e.get("name") or ""
        # 1) Beacon id
        b_id = _extract_beacon_id_from_note(note_e)
        if b_id and b_id not in ether_by_beacon:
            ether_by_beacon[b_id] = e
        # 2) AST_QUALNAME
        qual = _extract_ast_qualname_from_note(note_e)
        if qual:
            ether_by_ast.setdefault(qual, []).append(e)
        # 3) MD_PATH
        md_path = _extract_md_path_from_note(note_e)
        if md_path:
            key = tuple(whiten_text_for_header_compare(line) for line in md_path if line.strip())
            if key:
                ether_by_mdpath.setdefault(key, []).append(e)
        # 3.5) Vue section key
        vue_key = _extract_vue_section_key_from_note(note_e)
        if vue_key and vue_key not in ether_by_vuekey:
            ether_by_vuekey[vue_key] = e
        # 4) Raw name fallback
        if isinstance(name_e, str):
            ether_by_name.setdefault(name_e, []).append(e)

        # Debug: log any ETHER child that looks like our target function
        if (
            isinstance(name_e, str)
            and TARGET_FUNC in name_e
        ) or (
            isinstance(qual, str)
            and qual == TARGET_FUNC
        ):
            print(
                "[CARTO-DEBUG] ether child candidate for TARGET_FUNC:",
                {"name": name_e, "id": e.get("id"), "qual": qual},
                file=_carto_debug_sys.stderr,
                flush=True,
            )

    for s in source_children:
        note_s = s.get("note") or ""
        name_s = s.get("name") or ""
        match: dict[str, Any] | None = None

        b_id_s = _extract_beacon_id_from_note(note_s)
        qual_s = _extract_ast_qualname_from_note(note_s)
        debug_hit = (
            (isinstance(name_s, str) and TARGET_FUNC in name_s)
            or (isinstance(qual_s, str) and qual_s == TARGET_FUNC)
        )

        if debug_hit:
            print("[CARTO-DEBUG] SOURCE child before matching:", file=_carto_debug_sys.stderr, flush=True)
            print(
                "[CARTO-DEBUG]   name_s=", repr(name_s),
                "qual_s=", repr(qual_s),
                "b_id_s=", repr(b_id_s),
                file=_carto_debug_sys.stderr,
                flush=True,
            )
            print(
                "[CARTO-DEBUG]   ether_by_ast keys=",
                list(ether_by_ast.keys()),
                file=_carto_debug_sys.stderr,
                flush=True,
            )
            print(
                "[CARTO-DEBUG]   ether_by_beacon keys=",
                list(ether_by_beacon.keys()),
                file=_carto_debug_sys.stderr,
                flush=True,
            )

        # 1) Beacon id
        if b_id_s and b_id_s in ether_by_beacon:
            match = _candidate_if_unmatched(ether_by_beacon[b_id_s])
            if debug_hit and match is not None:
                print(
                    "[CARTO-DEBUG]   MATCH via BEACON id:",
                    {"b_id_s": b_id_s, "match_id": match.get("id")},
                    file=_carto_debug_sys.stderr,
                    flush=True,
                )
        else:
            # 2) AST_QUALNAME
            if qual_s and qual_s in ether_by_ast:
                match = _first_unmatched(ether_by_ast.get(qual_s))
                if debug_hit and match is not None:
                    print(
                        "[CARTO-DEBUG]   MATCH via AST_QUALNAME:",
                        {"qual_s": qual_s, "match_id": match.get("id")},
                        file=_carto_debug_sys.stderr,
                        flush=True,
                    )
            else:
                # 3) MD_PATH (whitened per-line comparison)
                md_path_s = _extract_md_path_from_note(note_s)
                if md_path_s:
                    key_s = tuple(
                        whiten_text_for_header_compare(line) for line in md_path_s if line.strip()
                    )
                    if key_s:
                        match = _first_unmatched(ether_by_mdpath.get(key_s))
                        if debug_hit and match is not None:
                            print(
                                "[CARTO-DEBUG]   MATCH via MD_PATH:",
                                {"key_s": key_s, "match_id": match.get("id")},
                                file=_carto_debug_sys.stderr,
                                flush=True,
                            )
                # 3.5) Vue section key
                if match is None:
                    vue_key_s = _extract_vue_section_key_from_note(note_s)
                    if vue_key_s and vue_key_s in ether_by_vuekey:
                        match = _candidate_if_unmatched(ether_by_vuekey[vue_key_s])
                        if debug_hit and match is not None:
                            print(
                                "[CARTO-DEBUG]   MATCH via VUE_SECTION key:",
                                {"vue_key_s": vue_key_s, "match_id": match.get("id")},
                                file=_carto_debug_sys.stderr,
                                flush=True,
                            )

                # 4) Raw name fallback
                if match is None and isinstance(name_s, str) and name_s in ether_by_name:
                    match = _first_unmatched(ether_by_name.get(name_s))
                    if debug_hit and match is not None:
                        print(
                            "[CARTO-DEBUG]   MATCH via raw name:",
                            {"name_s": name_s, "match_id": match.get("id")},
                            file=_carto_debug_sys.stderr,
                            flush=True,
                        )

        if match is None:
            if debug_hit:
                print("[CARTO-DEBUG]   NO MATCH for source child", file=_carto_debug_sys.stderr, flush=True)
            # No identity match at this level; we do not attempt to force ids.
            continue

        matched_ether_obj_ids.add(id(match))

        # Seed id from the matched Ether node.
        if "id" in match:
            s["id"] = match["id"]
            if debug_hit:
                print(
                    "[CARTO-DEBUG]   Seeded id from match:",
                    {"seed_id": s["id"]},
                    file=_carto_debug_sys.stderr,
                    flush=True,
                )

        # Whiten-based no-op suppression: if name/note are semantically equal
        # after whitening, preserve the ETHER values so WEAVE sees no change.
        name_e = match.get("name")
        if isinstance(name_s, str) and isinstance(name_e, str):
            if whiten_text_for_header_compare(name_s) == whiten_text_for_header_compare(name_e):
                s["name"] = name_e
        note_e = match.get("note")
        if isinstance(note_s, str) and isinstance(note_e, str):
            if whiten_text_for_header_compare(note_s) == whiten_text_for_header_compare(note_e):
                s["note"] = note_e

        if debug_hit:
            print(
                "[CARTO-DEBUG]   FINAL source child after matching:",
                {"name": s.get("name"), "id": s.get("id"), "note": s.get("note")},
                file=_carto_debug_sys.stderr,
                flush=True,
            )

        # Recurse into children with the same Cartographer-aware logic.
        reconcile_trees_cartographer(s, match)


# @beacon[
#   id=auto-beacon@_slice_label_tags-vxd4,
#   role=_slice_label_tags,
#   slice_labels=f9-f12-handlers,ra-reconcile,
#   kind=ast,
# ]
def _slice_label_tags(slice_labels: str) -> str:
    """Convert a slice_labels string into a space-delimited #tag list.

    Examples:
        "DOC"        -> "#DOC"
        "FP,DA"      -> "#FP #DA"
        "doc-intro"  -> "#doc-intro"

    We split on commas and whitespace to support "FP, DA" or "FP DA" forms.
    """
    if not isinstance(slice_labels, str):
        return ""
    labels = []
    for part in re.split(r"[\s,]+", slice_labels):
        part = part.strip()
        if not part:
            continue
        labels.append(f"#{part}")
    return " ".join(labels)


# @beacon[
#   id=auto-beacon@_canonicalize_slice_labels-zpcy,
#   role=_canonicalize_slice_labels,
#   slice_labels=f9-f12-handlers,ra-reconcile,
#   kind=ast,
# ]
def _canonicalize_slice_labels(slice_labels: str | None, role: str | None) -> str:
    """Canonicalize slice_labels for tags and display.

    - If slice_labels is empty and role is provided, derive labels from role.
    - Replaces ':', '.', and other non-tag-safe characters with '-' to ensure
      Workflowy tags render correctly (e.g. model:mert:production → model-mert-production,
      Class.method → Class-method).
    - Accepts comma/whitespace separated labels and normalizes each token.
    """
    raw = (slice_labels or "").strip()
    base_role = (role or "").strip()
    tokens: list[str] = []

    if raw:
        for part in re.split(r"[\s,]+", raw):
            part = part.strip()
            if not part:
                continue
            # Replace dots, colons, and other non-tag-safe chars with hyphens.
            sanitized = part.replace(":", "-").replace(".", "-")
            # Also replace slashes, spaces, and other problematic characters.
            sanitized = re.sub(r"[^A-Za-z0-9_-]+", "-", sanitized)
            sanitized = sanitized.strip("-")
            if sanitized:
                tokens.append(sanitized)
    elif base_role:
        # Apply same sanitization to role-derived labels.
        sanitized = base_role.replace(":", "-").replace(".", "-")
        sanitized = re.sub(r"[^A-Za-z0-9_-]+", "-", sanitized)
        sanitized = sanitized.strip("-")
        if sanitized:
            tokens.append(sanitized)

    return ",".join(tokens)


# @beacon[
#   id=carto-js-ts@_coerce_boolish-jb5p,
#   role=carto-js-ts,
#   slice_labels=carto-js-ts,carto-js-ts-beacons,f9-f12-handlers,ra-reconcile,nexus-md-header-path,
#   kind=ast,
# ]
def _coerce_boolish(val: Any | None) -> Optional[bool]:
    """Coerce common Workflowy/beacon boolean spellings to a bool.

    Returns:
      - True/False when val looks like a boolean
      - None when val is missing/empty/unknown

    Accepted false values (case-insensitive): false, 0, no, off
    Accepted true values  (case-insensitive): true, 1, yes, on
    """
    if val is None:
        return None
    if isinstance(val, bool):
        return val
    s = str(val).strip().lower()
    if not s:
        return None
    if s in {"false", "0", "no", "off"}:
        return False
    if s in {"true", "1", "yes", "on"}:
        return True
    return None


# @beacon[
#   id=carto-js-ts@_parse_show_span_fields-5i6q,
#   role=carto-js-ts,
#   slice_labels=carto-js-ts,carto-js-ts-beacons,f9-f12-handlers,ra-reconcile,nexus-md-header-path,
#   kind=ast,
# ]
def _parse_show_span_fields(fields: dict[str, str]) -> tuple[bool, bool]:
    """Return (show_span, show_span_explicit) from parsed beacon fields."""
    raw = fields.get("show_span")
    if raw is None:
        return True, False
    b = _coerce_boolish(raw)
    if b is None:
        # Fail-open: if malformed, behave like legacy (show span) but keep
        # explicitness so it round-trips and is visible to humans.
        return True, True
    return b, True


# @beacon[
#   id=carto-js-ts@_beacon_show_span-8v9u,
#   role=carto-js-ts,
#   slice_labels=carto-js-ts,carto-js-ts-beacons,f9-f12-handlers,ra-reconcile,
#   kind=ast,
# ]
def _beacon_show_span(beacon: dict[str, Any]) -> tuple[bool, bool]:
    """Return (show_span, explicit) for a parsed beacon dict."""
    explicit = bool(beacon.get("show_span_explicit"))
    raw = beacon.get("show_span")
    if isinstance(raw, bool):
        return raw, explicit
    b = _coerce_boolish(raw)
    if b is None:
        return True, explicit
    return b, True


# @beacon[
#   id=carto-js-ts@_extract_show_span_from_note-1q2w,
#   role=carto-js-ts,
#   slice_labels=carto-js-ts,carto-js-ts-beacons,f9-f12-handlers,ra-reconcile,
#   kind=ast,
# ]
def _extract_show_span_from_note(note: str | None) -> Optional[bool]:
    """Extract show_span from a Workflowy note (BEACON node note).

    Expected line form (case-insensitive key):
        show_span: false
        show_span: true
    """
    if not isinstance(note, str) or not note:
        return None
    for line in note.splitlines():
        stripped = line.strip()
        if stripped.lower().startswith("show_span:"):
            _, val = stripped.split(":", 1)
            return _coerce_boolish(val)
    return None


# @beacon[
#   id=carto-js-ts@_strip_beacon_meta_blocks_from_context-m8k3,
#   role=carto-js-ts,
#   slice_labels=carto-js-ts,carto-js-ts-beacons,f9-f12-handlers,ra-reconcile,nexus-md-header-path,
#   kind=ast,
# ]
def _strip_beacon_meta_blocks_from_context(context_lines: list[str]) -> list[str]:
    """Remove literal @beacon[...] / @beacon-close[...] metadata blocks from context.

    Delimiter-block based and language-agnostic.

    We strip sequences starting with a line whose *normalized* text starts with:
      - '@beacon[' or '@beacon-close['

    ...and continue stripping until the metadata terminator line, defined as a
    line whose normalized text *starts with* ']'.

    Using "starts with" (not equality) matches the more robust parsing style used
    elsewhere in this file (prevents edge cases around whitespace / trailing
    commas / minor formatting).

    Works for AST beacons as well (which typically have only the single
    @beacon[...] block).
    """
    if not context_lines:
        return []

    def _normalize_meta_line(raw: str) -> str:
        s = (raw or "").strip()
        # Defensive: if a comment prefix somehow survives into context_lines,
        # strip common single-line comment sugars.
        if s.startswith("#"):
            s = s.lstrip("#").lstrip()
        if s.startswith("--"):
            s = s[2:].lstrip()
        if s.startswith("//"):
            s = s[2:].lstrip()
        if s.startswith("*"):
            s = s.lstrip("*").lstrip()
        return s

    def _is_meta_block_end(norm: str) -> bool:
        # Close delimiter is a line that begins with ']'.
        # We intentionally do NOT use substring matching.
        return norm.strip().startswith("]")

    out: list[str] = []
    in_meta = False

    for raw in context_lines:
        norm = _normalize_meta_line(raw)

        if not in_meta and (norm.startswith("@beacon[") or norm.startswith("@beacon-close[")):
            # Single-line meta blocks (rare) or start of a multi-line block.
            if "]" in norm:
                continue
            in_meta = True
            continue

        if in_meta:
            if _is_meta_block_end(norm):
                in_meta = False
            continue

        out.append(raw)

    return out


# @beacon-close[
#   id=nmcv1@portable-note-and-identity-core,
# ]
# CORE V1 KEEPER:
# This cluster is the parser and beacon engine proper: Python/JS/TS/Vue outline
# builders, beacon parsing, duplicate-beacon hygiene, comment slurping, and AST/
# span attachment logic. It is core functionality, not optional decoration.
# @beacon[
#   id=nmcv1@parser-and-outline-core,
#   role=core keeper: parser, outline, and beacon-attachment engine,
#   slice_labels=nexus-portability,nexus-core-v1,
#   kind=span,
#   show_span=false,
# ]
# @beacon[
#   id=carto-js-ts@parse_python_beacon_blocks,
#   role=carto-js-ts,
#   slice_labels=carto-js-ts,carto-js-ts-beacons,f9-f12-handlers,ra-reconcile,
#   kind=span,
# ]
# Phase 2 JS/TS: Python beacon parser template.
# Reference for parse_js_beacon_blocks(...) (JS/TS @beacon[...] parser)
# so JS/TS beacon metadata matches the existing schema (id, role,
# slice_labels, kind, start_snippet, end_snippet, comment, comment_line).
def parse_python_beacon_blocks(lines: list[str]) -> list[dict[str, Any]]:
    """Parse @beacon[...] comment blocks from Python source lines.

    Expected form (we control this schema):

        # @beacon[
        #   id=example@1234,
        #   role=model:forward,
        #   slice_labels=FP,DA,
        #   kind=ast|span,
        #   start_snippet="def forward(",
        #   end_snippet="return y",
        # ]

    Returns a list of dicts with keys:
        id, role, slice_labels, kind, start_snippet, end_snippet,
        comment_line, kind_explicit.
    """
    beacons: list[dict[str, Any]] = []

    i = 0
    n = len(lines)
    while i < n:
        line = lines[i]
        stripped = line.lstrip()
        if stripped.startswith("#"):
            body = stripped.lstrip("#").lstrip()
            if body.startswith("@beacon["):
                comment_line = i + 1  # 1-based
                block_lines = [body]
                i += 1
                # Collect until a line containing ']' (inclusive)
                while i < n:
                    next_line = lines[i].lstrip()
                    if next_line.startswith("#"):
                        next_body = next_line.lstrip("#").lstrip()
                    else:
                        next_body = next_line
                    block_lines.append(next_body)
                    # Close only when the metadata delimiter line begins with ']'.
                    # This avoids premature termination when a value contains a stray ']'.
                    if next_body.strip().startswith("]"):
                        i += 1
                        break
                    i += 1

                # Parse block_lines into key/value pairs (skip first/last structural lines)
                fields: dict[str, str] = {}
                inner_lines = block_lines[1:-1] if len(block_lines) >= 2 else []
                for raw in inner_lines:
                    text = raw.strip()
                    if not text or text.startswith("@beacon"):
                        continue
                    # Drop trailing ',' or '],' or ']'
                    while text and text[-1] in ",]":
                        text = text[:-1].rstrip()
                    if not text:
                        continue
                    if "=" not in text:
                        continue
                    key, val = text.split("=", 1)
                    key = key.strip()
                    val = val.strip()
                    # Strip surrounding quotes if present
                    if (val.startswith("\"") and val.endswith("\"")) or (
                        val.startswith("'") and val.endswith("'")
                    ):
                        val = val[1:-1]
                    fields[key] = val

                kind_raw = fields.get("kind")
                kind = (kind_raw or "span").strip().lower() or "span"
                if kind not in {"ast", "span"}:
                    # Unknown/unsupported kind – skip silently for now
                    continue

                show_span, show_span_explicit = _parse_show_span_fields(fields)

                beacon = {
                    "id": fields.get("id"),
                    "role": fields.get("role"),
                    "slice_labels": fields.get("slice_labels"),
                    "kind": kind,
                    "start_snippet": fields.get("start_snippet"),
                    "end_snippet": fields.get("end_snippet"),
                    "comment": (fields.get("comment") if fields.get("comment") not in (None, "") else fields.get("comments")),
                    "comment_line": comment_line,
                    "kind_explicit": bool(kind_raw),
                    "show_span": show_span,
                    "show_span_explicit": show_span_explicit,
                }
                beacons.append(beacon)
                continue
        i += 1

    # Second pass: compute span ranges for Python span beacons using @beacon-close[...] by id.
    for beacon in beacons:
        if beacon.get("kind") != "span":
            continue

        # Only override when no span was previously set.
        if beacon.get("span_lineno_start") is not None and beacon.get("span_lineno_end") is not None:
            continue

        b_id = (beacon.get("id") or "").strip()
        if not b_id:
            continue

        comment_line = beacon.get("comment_line")
        if not isinstance(comment_line, int) or not (1 <= comment_line <= n):
            continue

        # Find end of opener's metadata block (first line containing ']')
        j = comment_line
        open_end = comment_line
        while j <= n:
            raw = lines[j - 1]
            stripped = raw.lstrip()
            if stripped.startswith("#"):
                body = stripped.lstrip("#").lstrip()
            else:
                body = stripped
            if body.strip().startswith("]"):
                open_end = j
                break
            j += 1

        # Scan forward for matching @beacon-close[...] with same id
        close_comment_line = None
        k = open_end + 1
        while k <= n:
            raw = lines[k - 1]
            if "@beacon-close[" in raw:
                close_lines = [raw]
                k += 1
                while k <= n:
                    next_raw = lines[k - 1]
                    close_lines.append(next_raw)
                    if "]" in next_raw:
                        k += 1
                        break
                    k += 1

                close_id = None
                for cl in close_lines:
                    text = cl.strip()
                    # Strip leading '#' and whitespace
                    if text.startswith("#"):
                        text = text.lstrip("#").lstrip()
                    # Drop trailing ',' and ']'
                    while text and text[-1] in ",]":
                        text = text[:-1].rstrip()
                    if text.startswith("id="):
                        _, val = text.split("=", 1)
                        close_id = val.strip()
                        break

                if close_id == b_id:
                    # Line where @beacon-close[...] started
                    close_comment_line = k - len(close_lines)
                    break

            k += 1

        if close_comment_line is not None:
            inner_start = open_end + 1
            inner_end = close_comment_line - 1
            if inner_start <= inner_end:
                beacon["span_lineno_start"] = inner_start
                beacon["span_lineno_end"] = inner_end

    return beacons


# ---------------------------------------------------------------------------
# Duplicate AST beacon normalization (hygiene)
# ---------------------------------------------------------------------------

# @beacon[
#   id=carto-hygiene@_is_numeric_suffix_beacon_id,
#   role=carto-hygiene: prefer numeric beacon ids when deduping,
#   slice_labels=carto-js-ts,carto-js-ts-beacons,f9-f12-handlers,ra-reconcile,
#   kind=ast,
#   comment=Helper: True iff id looks like prefix@000123 (digits after @). Used by F12 beacon normalization.
# ]
def _is_numeric_suffix_beacon_id(beacon_id: str | None) -> bool:
    """Return True when beacon_id looks like 'prefix@000123' (digits after @)."""
    if not isinstance(beacon_id, str):
        return False
    s = beacon_id.strip()
    if "@" not in s:
        return False
    suffix = s.split("@", 1)[1].strip()
    return bool(suffix) and suffix.isdigit()


def _split_csvish_tokens(raw: str | None) -> list[str]:
    if not isinstance(raw, str):
        return []
    parts = re.split(r"[\s,]+", raw.strip())
    return [p.strip() for p in parts if p and p.strip()]


def _merge_unique_strings(values: list[str], *, sep: str = " | ") -> str:
    out: list[str] = []
    seen: set[str] = set()
    for v in values:
        s = (v or "").strip()
        if not s:
            continue
        if s in seen:
            continue
        seen.add(s)
        out.append(s)
    return sep.join(out)


def _canonicalize_slice_labels_union(labels: list[str]) -> str:
    # Use the same per-token sanitization as _canonicalize_slice_labels, but
    # do NOT derive from role (we're unioning explicit tokens).
    tokens: list[str] = []
    seen: set[str] = set()
    for raw in labels:
        for part in _split_csvish_tokens(raw):
            sanitized = part.replace(":", "-").replace(".", "-")
            sanitized = re.sub(r"[^A-Za-z0-9_-]+", "-", sanitized)
            sanitized = sanitized.strip("-")
            if not sanitized:
                continue
            if sanitized in seen:
                continue
            seen.add(sanitized)
            tokens.append(sanitized)
    return ",".join(tokens)


# @beacon[
#   id=carto-hygiene@normalize_duplicate_ast_beacons_in_file,
#   role=carto-hygiene: normalize duplicate AST beacons in file,
#   slice_labels=carto-js-ts,carto-js-ts-beacons,f9-f12-handlers,ra-reconcile,
#   kind=ast,
#   comment=F12 hygiene: merge duplicate AST beacon blocks targeting the same AST header (Python/JS/TS/Vue).,
# ]
def normalize_duplicate_ast_beacons_in_file(file_path: str) -> dict[str, Any]:
    """Normalize duplicate AST beacons that target the same AST header.

    Motivation:
      Agents may add @beacon blocks via edit_file and accidentally create
      multiple AST beacons for the same function/class header. This hygiene
      pass merges duplicates so Cartographer/F12 refresh remains stable.

    Policy:
      - Only AST beacons are considered (span beacons are ignored).
      - Duplicates are detected by computing an 'anchor line' (the next
        significant non-comment/non-whitespace line after the beacon block,
        skipping decorators).
      - When duplicates exist for an anchor:
          * Keep one block (prefer numeric ids like prefix@000083 when trivial,
            else keep the first encountered position).
          * Union slice_labels.
          * Merge role/comment as a de-duplicated join.

    Returns: dict with changed flag and counts.
    """
    try:
        ext = os.path.splitext(file_path)[1].lower()
        if ext == ".py":
            return _normalize_duplicate_ast_beacons_python(file_path)
        if ext in {".js", ".jsx", ".ts", ".tsx", ".vue"}:
            return _normalize_duplicate_ast_beacons_js_ts(file_path)
        return {"success": True, "changed": False, "file_path": file_path, "reason": "unsupported_ext"}
    except Exception as e:  # noqa: BLE001
        return {"success": False, "changed": False, "file_path": file_path, "error": str(e)}


# @beacon[
#   id=carto-hygiene@_normalize_duplicate_ast_beacons_python,
#   role=carto-hygiene: dedupe Python AST beacons,
#   slice_labels=carto-js-ts,carto-js-ts-beacons,f9-f12-handlers,ra-reconcile,
#   kind=ast,
#   comment=Python implementation for normalize_duplicate_ast_beacons_in_file (anchor skips blank/#comments/@decorators).
# ]
def _normalize_duplicate_ast_beacons_python(file_path: str) -> dict[str, Any]:
    with open(file_path, "r", encoding="utf-8") as f:
        lines = f.readlines()

    n = len(lines)

    def _parse_blocks() -> list[dict[str, Any]]:
        blocks: list[dict[str, Any]] = []
        i = 0
        while i < n:
            raw = lines[i]
            stripped = raw.lstrip()
            if stripped.startswith("#"):
                body = stripped.lstrip("#").lstrip()
                if body.startswith("@beacon["):
                    start_i = i
                    comment_line = i + 1
                    block_bodies: list[str] = [body]
                    i += 1
                    end_i = start_i
                    while i < n:
                        nxt = lines[i].lstrip()
                        if nxt.startswith("#"):
                            nxt_body = nxt.lstrip("#").lstrip()
                        else:
                            nxt_body = nxt
                        block_bodies.append(nxt_body)
                        if nxt_body.strip().startswith("]"):
                            end_i = i
                            i += 1
                            break
                        i += 1

                    # Parse fields
                    fields: dict[str, str] = {}
                    inner = block_bodies[1:-1] if len(block_bodies) >= 2 else []
                    for row in inner:
                        text = (row or "").strip()
                        if not text or text.startswith("@beacon"):
                            continue
                        while text and text[-1] in ",]":
                            text = text[:-1].rstrip()
                        if not text or "=" not in text:
                            continue
                        k, v = text.split("=", 1)
                        k = k.strip()
                        v = v.strip()
                        if (v.startswith('"') and v.endswith('"')) or (v.startswith("'") and v.endswith("'")):
                            v = v[1:-1]
                        fields[k] = v

                    kind = (fields.get("kind") or "span").strip().lower() or "span"
                    blocks.append(
                        {
                            "start_i": start_i,
                            "end_i": end_i,
                            "comment_line": comment_line,
                            "fields": fields,
                            "kind": kind,
                        }
                    )
                    continue
            i += 1
        return blocks

    blocks = _parse_blocks()

    def _next_anchor_after(end_i: int) -> int | None:
        for j in range(end_i + 1, n):
            s = lines[j].lstrip()
            if not s.strip():
                continue
            if s.startswith("#"):
                continue
            if s.startswith("@"):
                # decorator
                continue
            return j + 1  # 1-based
        return None

    ast_blocks = []
    for b in blocks:
        if b.get("kind") != "ast":
            continue
        anchor = _next_anchor_after(int(b["end_i"]))
        if anchor is None:
            continue
        b2 = dict(b)
        b2["anchor_lineno"] = anchor
        ast_blocks.append(b2)

    by_anchor: dict[int, list[dict[str, Any]]] = {}
    for b in ast_blocks:
        by_anchor.setdefault(int(b["anchor_lineno"]), []).append(b)

    # Build edit plan
    changed = False
    merged_groups = 0
    removed_blocks = 0

    # We'll apply edits from bottom→top to preserve indices.
    deletions: list[tuple[int, int]] = []
    replacements: dict[int, list[str]] = {}  # start_i -> new block lines

    for anchor, group in by_anchor.items():
        if len(group) <= 1:
            continue

        group_sorted = sorted(group, key=lambda x: int(x["start_i"]))
        position_block = group_sorted[0]

        # Choose canonical id (prefer numeric suffix when trivial)
        ids = [str(g.get("fields", {}).get("id") or "").strip() for g in group_sorted]
        canonical_id = ""
        for cand in ids:
            if _is_numeric_suffix_beacon_id(cand):
                canonical_id = cand
                break
        if not canonical_id:
            canonical_id = ids[0] if ids else ""

        roles = [str(g.get("fields", {}).get("role") or "").strip() for g in group_sorted]
        comments = [str(g.get("fields", {}).get("comment") or "").strip() for g in group_sorted]
        slices = [str(g.get("fields", {}).get("slice_labels") or "").strip() for g in group_sorted]

        merged_role = _merge_unique_strings([r for r in roles if r])
        merged_comment = _merge_unique_strings([c for c in comments if c])
        merged_slice = _canonicalize_slice_labels_union(slices)

        indent = re.match(r"^\s*", lines[int(position_block["start_i"])])
        indent_str = indent.group(0) if indent else ""

        new_block: list[str] = [
            f"{indent_str}# @beacon[\n",
            f"{indent_str}#   id={canonical_id},\n",
        ]
        if merged_role:
            new_block.append(f"{indent_str}#   role={merged_role},\n")
        if merged_slice:
            new_block.append(f"{indent_str}#   slice_labels={merged_slice},\n")
        new_block.append(f"{indent_str}#   kind=ast,\n")
        if merged_comment:
            new_block.append(f"{indent_str}#   comment={merged_comment},\n")
        new_block.append(f"{indent_str}# ]\n")

        # Replace the first-position block with merged block; delete the rest.
        replacements[int(position_block["start_i"])] = new_block
        deletions.append((int(position_block["start_i"]), int(position_block["end_i"])))
        for other in group_sorted[1:]:
            deletions.append((int(other["start_i"]), int(other["end_i"])))
            removed_blocks += 1

        merged_groups += 1
        changed = True

    if not changed:
        return {"success": True, "changed": False, "file_path": file_path, "kind": "python"}

    # Apply deletions/replacements bottom-up.
    deletions_sorted = sorted(deletions, key=lambda t: t[0], reverse=True)

    for start_i, end_i in deletions_sorted:
        if start_i in replacements:
            # Replace this range with new block
            lines[start_i : end_i + 1] = replacements[start_i]
        else:
            # Delete
            del lines[start_i : end_i + 1]

    with open(file_path, "w", encoding="utf-8") as f:
        f.writelines(lines)

    return {
        "success": True,
        "changed": True,
        "file_path": file_path,
        "kind": "python",
        "merged_groups": merged_groups,
        "removed_blocks": removed_blocks,
    }


# @beacon[
#   id=carto-hygiene@_normalize_duplicate_ast_beacons_js_ts,
#   role=carto-hygiene: dedupe JS/TS/Vue AST beacons,
#   slice_labels=carto-js-ts,carto-js-ts-beacons,f9-f12-handlers,ra-reconcile,
#   kind=ast,
#   comment=JS/TS/Vue implementation for normalize_duplicate_ast_beacons_in_file (anchor skips blank/comments/@decorators).
# ]
def _normalize_duplicate_ast_beacons_js_ts(file_path: str) -> dict[str, Any]:
    with open(file_path, "r", encoding="utf-8") as f:
        lines = f.readlines()

    n = len(lines)

    def _strip_js_comment_sugar(text: str) -> str:
        t = (text or "").lstrip()
        if t.startswith("//"):
            t = t[2:].lstrip()
        if t.startswith("/*"):
            t = t[2:].lstrip()
        if t.startswith("*/"):
            t = t[2:].lstrip()
        if t.startswith("*"):
            t = t[1:].lstrip()
        if t.endswith("*/"):
            t = t[:-2].rstrip()
        return t

    def _looks_like_js_beacon_opener(raw: str) -> bool:
        s = (raw or "").lstrip()
        if "@beacon[" not in s:
            return False
        return s.startswith("//") or s.startswith("/*") or s.startswith("*")

    def _parse_blocks() -> list[dict[str, Any]]:
        blocks: list[dict[str, Any]] = []
        i = 0
        while i < n:
            raw = lines[i]
            if not _looks_like_js_beacon_opener(raw):
                i += 1
                continue

            start_i = i
            comment_line = i + 1
            block_lines = [lines[i]]
            i += 1
            end_i = start_i
            while i < n:
                block_lines.append(lines[i])
                body = _strip_js_comment_sugar(lines[i])
                if body.strip().startswith("]"):
                    end_i = i
                    i += 1
                    break
                i += 1

            # Parse fields from inner lines (strip sugar)
            fields: dict[str, str] = {}
            inner = block_lines[1:-1] if len(block_lines) >= 2 else []
            for raw2 in inner:
                text = _strip_js_comment_sugar(raw2).strip()
                if not text or text.startswith("@beacon"):
                    continue
                while text and text[-1] in ",]":
                    text = text[:-1].rstrip()
                if not text or "=" not in text:
                    continue
                k, v = text.split("=", 1)
                k = k.strip()
                v = v.strip()
                if (v.startswith('"') and v.endswith('"')) or (v.startswith("'") and v.endswith("'")):
                    v = v[1:-1]
                fields[k] = v

            kind = (fields.get("kind") or "span").strip().lower() or "span"
            blocks.append(
                {
                    "start_i": start_i,
                    "end_i": end_i,
                    "comment_line": comment_line,
                    "fields": fields,
                    "kind": kind,
                }
            )

        return blocks

    blocks = _parse_blocks()

    def _next_anchor_after(end_i: int) -> int | None:
        for j in range(end_i + 1, n):
            s = (lines[j] or "").lstrip()
            if not s.strip():
                continue
            if s.startswith("//"):
                continue
            if s.startswith("/*") or s.startswith("*") or s.startswith("*/"):
                continue
            if s.startswith("@"):
                # decorator
                continue
            return j + 1
        return None

    ast_blocks = []
    for b in blocks:
        if b.get("kind") != "ast":
            continue
        anchor = _next_anchor_after(int(b["end_i"]))
        if anchor is None:
            continue
        b2 = dict(b)
        b2["anchor_lineno"] = anchor
        ast_blocks.append(b2)

    by_anchor: dict[int, list[dict[str, Any]]] = {}
    for b in ast_blocks:
        by_anchor.setdefault(int(b["anchor_lineno"]), []).append(b)

    changed = False
    merged_groups = 0
    removed_blocks = 0
    deletions: list[tuple[int, int]] = []
    replacements: dict[int, list[str]] = {}

    for anchor, group in by_anchor.items():
        if len(group) <= 1:
            continue

        group_sorted = sorted(group, key=lambda x: int(x["start_i"]))
        position_block = group_sorted[0]

        ids = [str(g.get("fields", {}).get("id") or "").strip() for g in group_sorted]
        canonical_id = ""
        for cand in ids:
            if _is_numeric_suffix_beacon_id(cand):
                canonical_id = cand
                break
        if not canonical_id:
            canonical_id = ids[0] if ids else ""

        roles = [str(g.get("fields", {}).get("role") or "").strip() for g in group_sorted]
        comments = [str(g.get("fields", {}).get("comment") or "").strip() for g in group_sorted]
        slices = [str(g.get("fields", {}).get("slice_labels") or "").strip() for g in group_sorted]

        merged_role = _merge_unique_strings([r for r in roles if r])
        merged_comment = _merge_unique_strings([c for c in comments if c])
        merged_slice = _canonicalize_slice_labels_union(slices)

        indent = re.match(r"^\s*", lines[int(position_block["start_i"])])
        indent_str = indent.group(0) if indent else ""

        new_block: list[str] = [
            f"{indent_str}// @beacon[\n",
            f"{indent_str}//   id={canonical_id},\n",
        ]
        if merged_role:
            new_block.append(f"{indent_str}//   role={merged_role},\n")
        if merged_slice:
            new_block.append(f"{indent_str}//   slice_labels={merged_slice},\n")
        new_block.append(f"{indent_str}//   kind=ast,\n")
        if merged_comment:
            new_block.append(f"{indent_str}//   comment={merged_comment},\n")
        new_block.append(f"{indent_str}// ]\n")

        replacements[int(position_block["start_i"])] = new_block
        deletions.append((int(position_block["start_i"]), int(position_block["end_i"])))
        for other in group_sorted[1:]:
            deletions.append((int(other["start_i"]), int(other["end_i"])))
            removed_blocks += 1

        merged_groups += 1
        changed = True

    if not changed:
        return {"success": True, "changed": False, "file_path": file_path, "kind": "js_ts"}

    deletions_sorted = sorted(deletions, key=lambda t: t[0], reverse=True)
    for start_i, end_i in deletions_sorted:
        if start_i in replacements:
            lines[start_i : end_i + 1] = replacements[start_i]
        else:
            del lines[start_i : end_i + 1]

    with open(file_path, "w", encoding="utf-8") as f:
        f.writelines(lines)

    return {
        "success": True,
        "changed": True,
        "file_path": file_path,
        "kind": "js_ts",
        "merged_groups": merged_groups,
        "removed_blocks": removed_blocks,
    }


# @beacon[
#   id=carto-js-ts@_iter_ast_outline_nodes-nf4x,
#   role=carto-js-ts,
#   slice_labels=carto-js-ts,ra-snippet-range-ast-py,
#   kind=ast,
# ]
def _iter_ast_outline_nodes(nodes: list[dict[str, Any]]):
    """Yield all AST-backed outline nodes in a pre-order traversal.

    Nodes are expected to carry 'ast_type' when they correspond to
    Python AST elements (class/function/async/const).
    """
    for node in nodes:
        if isinstance(node, dict) and node.get("ast_type"):
            yield node
        children = (node.get("children") or []) if isinstance(node, dict) else []
        for ch in children:
            if isinstance(ch, dict):
                for sub in _iter_ast_outline_nodes([ch]):
                    yield sub


def _find_enclosing_ast_node_for_line(
    nodes: list[dict[str, Any]], start_line: int
) -> Optional[dict[str, Any]]:
    """Find the deepest AST node whose [start,end] span contains start_line."""
    best: Optional[dict[str, Any]] = None
    best_depth = -1

    def _recurse(node: dict[str, Any], depth: int) -> None:
        nonlocal best, best_depth
        if not isinstance(node, dict):
            return
        start = node.get("orig_lineno_start_unused")
        end = node.get("orig_lineno_end_unused")
        ast_type = node.get("ast_type")
        if (
            ast_type
            and isinstance(start, int)
            and isinstance(end, int)
            and start <= start_line <= end
        ):
            if depth > best_depth:
                best = node
                best_depth = depth
        for ch in node.get("children") or []:
            if isinstance(ch, dict):
                _recurse(ch, depth + 1)

    for root in nodes:
        _recurse(root, 0)
    return best


# @beacon[
#   id=carto-js-ts@apply_python_beacons,
#   role=carto-js-ts,
#   slice_labels=carto-js-ts,carto-js-ts-beacons,ra-snippet-range-ast-beacon-py,f9-f12-handlers,ra-reconcile,
#   kind=span,
# ]
# Phase 2 JS/TS: Python beacon attachment template.
# Reference for apply_js_beacons(...), which will decorate JS/TS
# Tree-sitter AST nodes (kind=ast) and attach span children
# (kind=span) in the same way.
def apply_python_beacons(
    file_path: str,
    lines: list[str],
    outline_nodes: list[dict[str, Any]],
) -> None:
    """Apply Python @beacon[...] metadata to an existing AST outline tree.

    - AST beacons (kind=ast): decorate existing AST nodes (no new nodes).
    - SPAN beacons (kind=span): create child nodes under the enclosing AST node
      (or at file-level if no enclosing AST node is found).

    Snippet-less beacons:
    - If kind is span and start_snippet is missing, we:
      1) Find the next non-blank, non-comment, non-decorator line after the
         beacon block, and treat that as the anchor line.
      2) If that line is exactly the start of a class/function/async AST node,
         we auto-upgrade the beacon to kind=ast and decorate that node.
      3) Otherwise, we treat it as a span beacon anchored under the enclosing
         AST node for that line.

    Comment context:
    - For both AST and SPAN beacons, we capture nearby Python comments and
      triple-quoted blocks (treated as комментарий-like) above and below the
      beacon block and append them into the beacon note for Workflowy.
    """
    # IMPORTANT: do not bail out just because the Python AST outline is empty.
    # File-level SPAN beacons are still valid for AST-less modules such as
    # package __init__.py files that only contain imports/re-exports/constants.
    beacons = parse_python_beacon_blocks(lines)
    if not beacons:
        return
    # Warn early if there are duplicate beacon IDs in the file.
    _prepend_duplicate_beacon_id_warning_nodes(outline_nodes, beacons, language="PY")

    # Precompute AST-backed nodes and a helper for line lookups
    ast_nodes = list(_iter_ast_outline_nodes(outline_nodes))

    # Precompute triple-quoted spans so we can treat them as comment-like.
    triple_spans: List[tuple[int, int]] = []
    in_block = False
    quote_type: Optional[str] = None
    start_line_q: Optional[int] = None

    for idx, raw in enumerate(lines, start=1):
        if not in_block:
            if '"""' in raw or "'''" in raw:
                # Prefer the first occurrence on the line
                dq_index = raw.find('"""') if '"""' in raw else -1
                sq_index = raw.find("'''") if "'''" in raw else -1
                if dq_index != -1 and (sq_index == -1 or dq_index <= sq_index):
                    q = '"""'
                else:
                    q = "'''"
                count = raw.count(q)
                if count >= 2:
                    triple_spans.append((idx, idx))
                else:
                    in_block = True
                    quote_type = q
                    start_line_q = idx
        else:
            if quote_type and quote_type in raw:
                triple_spans.append((start_line_q or idx, idx))
                in_block = False
                quote_type = None
                start_line_q = None

    def _find_triple_span_for_line(line_no: int) -> Optional[tuple[int, int]]:
        for s, e in triple_spans:
            if s <= line_no <= e:
                return (s, e)
        return None

    def _header_line_for_node(node: dict[str, Any]) -> Optional[str]:
        ln = node.get("orig_lineno_start_unused")
        if not isinstance(ln, int) or ln <= 0 or ln > len(lines):
            return None
        return lines[ln - 1]

    span_sort_lines: dict[int, int] = {}

    # @beacon[
    #   id=carto-beacon-order@py-node-source-order-line,
    #   role=apply_python_beacons._node_source_order_line,
    #   slice_labels=carto-js-ts,carto-js-ts-beacons,f9-f12-handlers,ra-reconcile,
    #   kind=ast,
    # ]
    def _node_source_order_line(node: dict[str, Any]) -> int:
        cached = span_sort_lines.get(id(node))
        if isinstance(cached, int):
            return cached
        ln = node.get("orig_lineno_start_unused") if isinstance(node, dict) else None
        if isinstance(ln, int):
            return ln
        return 10**9

    # @beacon[
    #   id=carto-beacon-order@py-insert-child-in-source-order,
    #   role=apply_python_beacons._insert_child_in_source_order,
    #   slice_labels=carto-js-ts,carto-js-ts-beacons,f9-f12-handlers,ra-reconcile,
    #   kind=ast,
    # ]
    def _insert_child_in_source_order(
        siblings: List[Dict[str, Any]],
        child_node: Dict[str, Any],
        sort_line: int,
    ) -> None:
        span_sort_lines[id(child_node)] = sort_line
        insert_at = len(siblings)
        for idx, existing in enumerate(siblings):
            if _node_source_order_line(existing) > sort_line:
                insert_at = idx
                break
        siblings.insert(insert_at, child_node)

    def _next_anchor_line_after(line_no: int) -> Optional[int]:
        """Return next non-blank, non-comment, non-decorator line after line_no.

        line_no is 1-based. We skip lines that are:
        - empty/whitespace
        - start with '#'
        - start with '@' (decorators)
        """
        for idx in range(line_no + 1, len(lines) + 1):
            raw = lines[idx - 1]
            stripped = raw.lstrip()
            if not stripped:
                continue
            if stripped.startswith("#"):
                continue
            if stripped.startswith("@"):
                continue
            return idx
        return None

    # @beacon[
    #   id=carto-js-ts@_extract_python_beacon_context-7u3n,
    #   role=carto-js-ts,
    #   slice_labels=carto-js-ts,ra-snippet-range-span-beacon,
    #   kind=ast,
    # ]
    def _extract_python_beacon_context(
        comment_line: int,
        decor_start: Optional[int] = None,
        beacon_id: Optional[str] = None,
    ) -> List[str]:
        """Extract nearby comment-like lines around a Python beacon.

        Includes:
        - # comments above/below the beacon block (stripped of leading '#')
        - triple-quoted blocks (triple quotes) treated as comment-like

        Skips:
        - blank lines
        - decorator lines starting with '@'
        """
        context: List[str] = []
        seen_spans: set[tuple[int, int]] = set()

        # Determine end of the beacon metadata block
        j = comment_line
        block_end = comment_line
        while j <= len(lines):
            raw = lines[j - 1]
            stripped = raw.lstrip()
            if stripped.startswith("#"):
                body = stripped.lstrip("#").lstrip()
            else:
                body = stripped
            if body.strip().startswith("]"):
                block_end = j
                break
            j += 1

        # Above: walk past decorators to reach true leading comments, and
        # skip any decorator region attached to the enclosing AST node
        # (when known) so multiline decorators do not block comment capture.
        j = comment_line - 1
        while j >= 1:
            raw = lines[j - 1]
            stripped = raw.lstrip()
            if not stripped:
                j -= 1
                continue
            if decor_start is not None and decor_start <= j <= block_end:
                j -= 1
                continue
            if stripped.startswith("#"):
                body = stripped.lstrip("#").lstrip()
                if body:
                    context.insert(0, body)
                j -= 1
                continue
            span = _find_triple_span_for_line(j)
            if span and span not in seen_spans:
                s, e = span
                # IMPORTANT: preserve original order when prepending a multi-line
                # triple-quoted block. Using insert(0, ...) in a forward loop
                # reverses the block.
                for k in range(e, s - 1, -1):
                    context.insert(0, lines[k - 1])
                seen_spans.add(span)
                j = s - 1
                continue
            if stripped.startswith("@"):
                # Skip decorator lines but keep walking upward so that
                # comments above a decorator are still captured as
                # CONTEXT COMMENTS (PYTHON).
                j -= 1
                continue
            break

        # Below
        j = block_end + 1
        while j <= len(lines):
            raw = lines[j - 1]
            stripped = raw.lstrip()
            if not stripped:
                j += 1
                continue
            if stripped.startswith("#"):
                body = stripped.lstrip("#").lstrip()
                # Never include beacon delimiter blocks as "context comments".
                # Also support overlapping span beacons by only stopping on a
                # matching @beacon-close id (when beacon_id is provided).
                if body.startswith("@beacon["):
                    # Skip nested opener metadata block.
                    j += 1
                    while j <= len(lines):
                        nxt = lines[j - 1].lstrip()
                        nb = nxt.lstrip("#").lstrip() if nxt.startswith("#") else nxt
                        if nb.strip().startswith("]"):
                            j += 1
                            break
                        j += 1
                    continue
                if body.startswith("@beacon-close["):
                    close_id: Optional[str] = None
                    j += 1
                    while j <= len(lines):
                        nxt = lines[j - 1].lstrip()
                        nb = nxt.lstrip("#").lstrip() if nxt.startswith("#") else nxt
                        nb_strip = nb.strip()
                        if nb_strip.startswith("id=") and close_id is None:
                            close_id = nb_strip.split("=", 1)[1].strip().strip(",").strip("]")
                        if nb_strip.startswith("]"):
                            break
                        j += 1
                    # Ignore close blocks for other beacon ids (supports overlap).
                    if beacon_id and close_id and close_id != beacon_id:
                        j += 1
                        continue
                    break
                if body.startswith("@beacon"):
                    break
                if body:
                    context.append(body)
                j += 1
                continue
            span = _find_triple_span_for_line(j)
            if span and span not in seen_spans:
                s, e = span
                for k in range(s, e + 1):
                    context.append(lines[k - 1])
                seen_spans.add(span)
                j = e + 1
                continue
            if stripped.startswith("@"):
                break
            break

        return _strip_beacon_meta_blocks_from_context(context)

    # Pre-pass: for snippet-less beacons (AST or SPAN), compute an anchor
    # lineno (the next significant line after the metadata block).
    #
    # For SPAN beacons only, we may auto-upgrade to AST when the anchor is a
    # clean class/function/async start.
    #
    # IMPORTANT RULES:
    # - Do NOT auto-upgrade an explicit span region (paired opener/closer),
    #   indicated by span_lineno_end.
    # - Do NOT auto-upgrade when the author explicitly wrote kind=span.
    #   Explicit span means “create a span node”, not “decorate the next AST”.
    for beacon in beacons:
        kind = beacon.get("kind")
        start_snippet = beacon.get("start_snippet")
        if kind not in {"span", "ast"}:
            continue
        if start_snippet:
            continue

        comment_line = beacon.get("comment_line") or 0
        if isinstance(comment_line, int) and comment_line > 0:
            anchor = _next_anchor_line_after(comment_line)
        else:
            anchor = None
        if anchor is None:
            continue
        beacon["_anchor_lineno"] = anchor

        # Auto-upgrade logic is SPAN-only.
        if kind != "span":
            continue

        # Never auto-upgrade an explicit span region.
        if isinstance(beacon.get("span_lineno_end"), int):
            continue

        # Never auto-upgrade an explicitly-declared kind=span beacon.
        if bool(beacon.get("kind_explicit")):
            continue

        # See if this line is exactly the start of a class/function/async
        # AST node. If so, we treat this beacon as an AST beacon by default.
        ast_candidates: list[dict[str, Any]] = []
        for node in ast_nodes:
            ast_type = node.get("ast_type")
            if ast_type not in {"class", "function", "async_function", "const", "const_decl"}:
                continue
            ln = node.get("orig_lineno_start_unused")
            if isinstance(ln, int) and ln == anchor:
                ast_candidates.append(node)

        if len(ast_candidates) == 1:
            beacon["kind"] = "ast"

    # Pass 1: AST beacons
    for beacon in beacons:
        if beacon.get("kind") != "ast":
            continue
        b_id = beacon.get("id") or "(no-id)"
        start_snippet = beacon.get("start_snippet")
        comment_line = beacon.get("comment_line") or 0
        anchor_lineno = beacon.get("_anchor_lineno")

        chosen: Optional[dict[str, Any]] = None

        if start_snippet:
            # Legacy mode: use start_snippet to match header line
            norm_snip = normalize_for_match(start_snippet)
            if not norm_snip:
                continue

            candidates: list[dict[str, Any]] = []
            for node in ast_nodes:
                header = _header_line_for_node(node)
                if header is None:
                    continue
                if norm_snip in normalize_for_match(header):
                    candidates.append(node)

            if not candidates:
                # Beacon is stale or misconfigured – skip
                continue

            if len(candidates) == 1:
                chosen = candidates[0]
            else:
                # Prefer the first candidate whose header is AFTER the beacon
                after = [
                    n
                    for n in candidates
                    if isinstance(n.get("orig_lineno_start_unused"), int)
                    and n["orig_lineno_start_unused"] > comment_line
                ]
                if len(after) == 1:
                    chosen = after[0]
                else:
                    # Ambiguous – skip for now
                    continue
        else:
            # Snippet-less AST beacon: use precomputed anchor lineno
            anchor = beacon.get("_anchor_lineno")
            if not isinstance(anchor, int):
                continue
            ast_candidates = [
                node
                for node in ast_nodes
                if node.get("ast_type") in {"class", "function", "async_function", "const", "const_decl"}
                and isinstance(node.get("orig_lineno_start_unused"), int)
                and node["orig_lineno_start_unused"] == anchor
            ]
            if len(ast_candidates) == 1:
                chosen = ast_candidates[0]
            else:
                continue

        if not chosen:
            continue

        # Decorate chosen AST node
        b_id = (beacon.get("id") or "").strip()
        role = (beacon.get("role") or "").strip()
        raw_slice_labels = (beacon.get("slice_labels") or "").strip()
        # Defaults: derive role from id prefix (before '@')
        if not role and b_id and "@" in b_id:
            role = b_id.split("@", 1)[0]
        slice_labels = _canonicalize_slice_labels(raw_slice_labels, role)

        display_role = role or b_id or "ast-beacon"
        display_slice = slice_labels or "-"

        tag_suffix = _slice_label_tags(slice_labels or display_slice)
        name = chosen.get("name") or "Untitled"
        if "🔱" not in name:
            name = f"{name} 🔱"
        if tag_suffix:
            name = f"{name} {tag_suffix}"
        chosen["name"] = name

        # Merge beacon metadata into note. For AST beacons, we rely on the
        # AST node itself to carry CONTEXT COMMENTS (PYTHON) so we do not
        # duplicate comment blocks in the BEACON section.
        comment = beacon.get("comment")
        meta_lines = [
            "BEACON (AST)",
            f"id: {b_id}",
            f"role: {role}",
            f"slice_labels: {slice_labels}",
            "kind: ast",
        ]
        if comment:
            meta_lines.append(f"comment: {comment}")
        note = chosen.get("note") or ""
        if note:
            # Keep the identifier (AST_QUALNAME) at the top, then insert the
            # BEACON metadata block, then the rest of the content.
            note_lines = note.splitlines()
            insert_idx = (
                1
                if (note_lines and note_lines[0].strip().startswith("AST_QUALNAME:"))
                else 0
            )
            new_note_lines: list[str] = []
            new_note_lines.extend(note_lines[:insert_idx])
            new_note_lines.extend(meta_lines)
            if insert_idx < len(note_lines):
                if note_lines[insert_idx].strip():
                    new_note_lines.append("")
                new_note_lines.extend(note_lines[insert_idx:])
            chosen["note"] = "\n".join(new_note_lines)
        else:
            chosen["note"] = "\n".join(meta_lines)

    # Pass 2: SPAN beacons
    for beacon in beacons:
        if beacon.get("kind") != "span":
            continue
        start_snippet = beacon.get("start_snippet")
        comment_line = beacon.get("comment_line") or 0

        attachment_line: Optional[int] = None

        if start_snippet:
            norm_snip = normalize_for_match(start_snippet)
            if not norm_snip:
                continue

            # Find candidate start lines, but IGNORE lines that are comments
            # (including the @beacon block itself) so we never anchor spans to
            # their own metadata.
            start_candidates: list[int] = []
            for idx, line in enumerate(lines, start=1):
                stripped = line.lstrip()
                if stripped.startswith("#"):
                    continue
                if norm_snip in normalize_for_match(line):
                    start_candidates.append(idx)

            if not start_candidates:
                # No match – skip for now
                continue

            if len(start_candidates) == 1:
                attachment_line = start_candidates[0]
            else:
                after = [ln for ln in start_candidates if ln > comment_line]
                if len(after) == 1:
                    attachment_line = after[0]
                else:
                    # Ambiguous span; require beacon refinement
                    continue
        else:
            # Snippet-less spans attach based on the beacon's own location,
            # not the next code line. This keeps file-level/documentation spans
            # at file scope even when the next AST node is a function/class.
            span_start = beacon.get("span_lineno_start")
            if isinstance(span_start, int):
                attachment_line = span_start
            elif isinstance(comment_line, int) and comment_line > 0:
                attachment_line = comment_line
            else:
                anchor = beacon.get("_anchor_lineno")
                attachment_line = anchor if isinstance(anchor, int) else None

        if attachment_line is None:
            continue

        # Decide enclosing AST node (if any)
        enclosing = _find_enclosing_ast_node_for_line(outline_nodes, attachment_line)

        b_id = (beacon.get("id") or "").strip()
        role = (beacon.get("role") or "").strip()
        raw_slice_labels = (beacon.get("slice_labels") or "").strip()
        # Defaults: derive role from id prefix (before '@')
        if not role and b_id and "@" in b_id:
            role = b_id.split("@", 1)[0]
        slice_labels = _canonicalize_slice_labels(raw_slice_labels, role)

        show_span, show_span_explicit = _beacon_show_span(beacon)

        display_role = role or b_id or "span-beacon"
        display_slice = slice_labels or "-"

        tag_suffix = _slice_label_tags(slice_labels or display_slice)
        name = f"🔱 {display_role}"
        if tag_suffix:
            name = f"{name} {tag_suffix}"

        enclosing_decor_start: Optional[int] = None
        if enclosing is not None:
            dsl = enclosing.get("decor_start_lineno")
            if isinstance(dsl, int):
                enclosing_decor_start = dsl
        context_lines = _extract_python_beacon_context(
            comment_line,
            enclosing_decor_start,
            beacon_id=b_id,
        )
        comment = beacon.get("comment")

        note_lines = [
            "BEACON (SPAN)",
            f"id: {b_id}",
            f"role: {role}",
            f"slice_labels: {slice_labels}",
            "kind: span",
        ]
        if show_span_explicit:
            note_lines.append(f"show_span: {'true' if show_span else 'false'}")
        if comment:
            note_lines.append(f"comment: {comment}")
        if context_lines:
            note_lines.append("")
            note_lines.append("CONTEXT COMMENTS (PYTHON):")
            note_lines.extend(context_lines)

        # Raw Python span text between @beacon[...] and @beacon-close[...] (if available)
        span_start = beacon.get("span_lineno_start")
        span_end = beacon.get("span_lineno_end")
        span_text_lines: List[str] = []
        if isinstance(span_start, int) and isinstance(span_end, int):
            span_start = max(1, span_start)
            span_end = min(len(lines), span_end)
            if span_start <= span_end:
                span_text_lines = lines[span_start - 1 : span_end]
                # Trim leading/trailing blank lines inside the span
                while span_text_lines and not span_text_lines[0].strip():
                    span_text_lines.pop(0)
                while span_text_lines and not span_text_lines[-1].strip():
                    span_text_lines.pop()

        if show_span and span_text_lines:
            note_lines.append("")
            note_lines.append("SPAN TEXT:")
            note_lines.extend(span_text_lines)

        span_node = {
            "name": name,
            "note": "\n".join(note_lines),
            "children": [],
        }

        if enclosing is not None:
            children = enclosing.get("children") or []
            _insert_child_in_source_order(children, span_node, attachment_line)
            enclosing["children"] = children
        else:
            # File-level span: attach directly under top-level outline
            _insert_child_in_source_order(outline_nodes, span_node, attachment_line)


# @beacon[
#   id=carto-js-ts@get_docstring-u9fp,
#   role=carto-js-ts,
#   slice_labels=carto-js-ts,ra-snippet-range-ast-py,
#   kind=ast,
# ]
def get_docstring(node: ast.AST) -> str:
    """Extract docstring from an AST node if present. (Synced Update)"""
    return ast.get_docstring(node) or ""


def get_function_signature(node: ast.FunctionDef) -> str:
    """Reconstruct function signature for display."""
    args = []
    
    # Handle positional arguments
    for arg in node.args.args:
        arg_str = arg.arg
        if arg.annotation:
            if isinstance(arg.annotation, ast.Name):
                arg_str += f": {arg.annotation.id}"
            elif isinstance(arg.annotation, ast.Subscript):
                try:
                    val = getattr(arg.annotation.value, 'id', '')
                    slice_val = getattr(arg.annotation.slice, 'id', '')
                    if not slice_val and hasattr(arg.annotation.slice, 'value'):
                         if isinstance(arg.annotation.slice, ast.Name):
                             slice_val = arg.annotation.slice.id
                    if val and slice_val:
                        arg_str += f": {val}[{slice_val}]"
                except:
                    pass
            elif isinstance(arg.annotation, ast.Attribute):
                arg_str += f": {arg.annotation.attr}"
        args.append(arg_str)
        
    return f"{node.name}({', '.join(args)})"

# @beacon[
#   id=carto-js-ts@parse_file_outline,
#   role=carto-js-ts,
#   slice_labels=carto-js-ts,ra-snippet-range-ast-py,ra-reconcile,
#   kind=span,
# ]
# Phase 1 JS/TS: Python AST outline template.
# Used as the reference shape for the new JS/TS Tree-sitter-based
# outline builder (parse_js_ts_outline) so JS/TS nodes match the
# same NEXUS schema (ast_type, ast_name, ast_qualname, file_path,
# line ranges, priority, children).
def parse_file_outline(file_path: str) -> List[Dict[str, Any]]:
    """Parse a single Python file into a NEXUS outline tree + beacon decorations.

    Steps (V1 Beacon-aware):
    1. Parse the file with `ast.parse` and build an AST-backed outline tree that
       records `ast_type`, `ast_name`, `ast_qualname`, `file_path`, and
       `orig_lineno_start_unused` / `orig_lineno_end_unused` for each node.
    2. Scan the raw source lines for `@beacon[...]` comment blocks.
    3. Attach AST beacons (kind=ast) to existing outline nodes (no new nodes).
    4. Attach SPAN beacons (kind=span) as child nodes under the enclosing AST
       node (or at file-level if no enclosing node is found).

    PRIORITY HANDLING: Existing class/function/const nodes still receive
    sequential priorities (100, 200, 300, ...) based on order in source code.
    Span beacon nodes do not currently participate in the priority sequence.
    """
    try:
        with open(file_path, 'r', encoding='utf-8') as f:
            content = f.read()

        tree = ast.parse(content, filename=file_path)
        lines = content.splitlines()

        def _extract_ast_comment_context(start_lineno: int, decor_start: Optional[int]) -> list[str]:
            context: list[str] = []
            # Above: skip decorator region between decor_start and the AST node.
            j = start_lineno - 1
            while j >= 1:
                raw = lines[j - 1]
                stripped = raw.lstrip()
                if not stripped:
                    j -= 1
                    continue
                if decor_start is not None and decor_start <= j < start_lineno:
                    # Inside decorator region (including multiline decorators);
                    # skip these lines entirely so we can reach comments that
                    # truly lead the AST node.
                    j -= 1
                    continue
                if stripped.startswith("#"):
                    body = stripped.lstrip("#").lstrip()
                    if body:
                        context.insert(0, body)
                    j -= 1
                    continue
                break

            # Below: immediate top-of-body comments (before docstring or code)
            j = start_lineno + 1
            while j <= len(lines):
                raw = lines[j - 1]
                stripped = raw.lstrip()
                if not stripped:
                    j += 1
                    continue
                if stripped.startswith("#"):
                    body = stripped.lstrip("#").lstrip()
                    if body:
                        context.append(body)
                    j += 1
                    continue
                break

            return _strip_beacon_meta_blocks_from_context(context)

        priority_counter = [100]  # Mutable list to share across recursion

        # @beacon[
        #   id=carto-parser@should-map-python-assigned-name,
        #   role=parse_file_outline._should_map_python_assigned_name,
        #   slice_labels=carto-js-ts,f9-f12-handlers,ra-reconcile,
        #   kind=ast,
        #   comment=Select Python assigned names that should become Cartographer outline nodes, including module-level dunder globals like __version__ and __all__,
        # ]
        def _should_map_python_assigned_name(name: str, *, qual_prefix: Optional[str]) -> bool:
            """Return True when an assigned Name should appear in the Python outline."""
            if not isinstance(name, str) or not name:
                return False
            if name.isupper():
                return True
            # Map module-level dunder globals like __version__ / __all__ so
            # package __init__.py and similar files remain structurally visible.
            if qual_prefix is None and len(name) > 4 and name.startswith("__") and name.endswith("__"):
                return True
            return False

        # @beacon[
        #   id=carto-parser@assigned-name-note-label,
        #   role=parse_file_outline._assigned_name_note_label,
        #   slice_labels=carto-js-ts,f9-f12-handlers,ra-reconcile,
        #   kind=ast,
        #   comment=Choose the note label for mapped Python assigned names, distinguishing module-level dunder globals from regular constants,
        # ]
        def _assigned_name_note_label(name: str, *, qual_prefix: Optional[str]) -> str:
            if qual_prefix is None and len(name) > 4 and name.startswith("__") and name.endswith("__"):
                return "Module global"
            return "Constant"

        # @beacon[
        #   id=carto-parser@iter-nested-statement-bodies-py,
        #   role=parse_file_outline._iter_nested_statement_bodies,
        #   slice_labels=carto-js-ts,f9-f12-handlers,ra-reconcile,
        #   kind=ast,
        # ]
        def _iter_nested_statement_bodies(stmt: ast.AST) -> List[List[ast.AST]]:
            """Return nested statement lists for control-flow containers.

            We intentionally do NOT create outline nodes for statements like
            if/try/with/for/match, but we *do* need to descend into their
            bodies so nested defs/classes become visible to Cartographer/F12.

            The returned bodies are sorted by their first source line so nested
            AST nodes appear in lexical order regardless of construct type.
            """
            candidates: List[tuple[int, int, List[ast.AST]]] = []
            ordinal = 0

            def _add(body: Any) -> None:
                nonlocal ordinal
                if not isinstance(body, list) or not body:
                    return
                first_stmt = body[0]
                first_lineno = getattr(first_stmt, "lineno", None)
                if not isinstance(first_lineno, int):
                    first_lineno = 10**9
                candidates.append((first_lineno, ordinal, body))
                ordinal += 1

            for attr in ("body", "orelse", "finalbody"):
                _add(getattr(stmt, attr, None))

            handlers = getattr(stmt, "handlers", None)
            if isinstance(handlers, list):
                for handler in handlers:
                    _add(getattr(handler, "body", None))

            cases = getattr(stmt, "cases", None)
            if isinstance(cases, list):
                for case in cases:
                    _add(getattr(case, "body", None))

            candidates.sort(key=lambda item: (item[0], item[1]))
            return [body for _, _, body in candidates]

        def walk_body(
            body_items: List[ast.AST],
            qual_prefix: Optional[str] = None,
        ) -> List[Dict[str, Any]]:
            results: List[Dict[str, Any]] = []
            for item in body_items:
                if isinstance(item, ast.ClassDef):
                    qual = item.name if not qual_prefix else f"{qual_prefix}.{item.name}"
                    start = getattr(item, "lineno", None)
                    end = getattr(item, "end_lineno", start)
                    decorators = getattr(item, "decorator_list", None) or []
                    decor_start: Optional[int] = None
                    if decorators and isinstance(start, int):
                        dec_lines = [
                            getattr(d, "lineno", None)
                            for d in decorators
                            if getattr(d, "lineno", None)
                        ]
                        if dec_lines:
                            decor_start = min(dec_lines)
                    # Build note: AST_QUALNAME header, then optional separator and docstring.
                    doc = get_docstring(item)
                    note_lines: list[str] = [f"AST_QUALNAME: {qual}"]
                    if doc:
                        note_lines.append("---")
                        note_lines.append(doc)
                    context_lines = _extract_ast_comment_context(start, decor_start) if isinstance(start, int) else []
                    if context_lines:
                        note_lines.append("")
                        note_lines.append("CONTEXT COMMENTS (PYTHON):")
                        note_lines.extend(context_lines)
                    note_text = "\n".join(note_lines)

                    node = {
                        "name": f"{EMOJI_CLASS} class {item.name}",
                        "priority": priority_counter[0],
                        "note": note_text,
                        "children": walk_body(item.body, qual_prefix=qual),
                        "ast_type": "class",
                        "ast_name": item.name,
                        "ast_qualname": qual,
                        "file_path": file_path,
                        "orig_lineno_start_unused": start,
                        "orig_lineno_end_unused": end,
                        "decor_start_lineno": decor_start,
                    }
                    priority_counter[0] += 100
                    results.append(node)
                elif isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
                    prefix = EMOJI_ASYNC if isinstance(item, ast.AsyncFunctionDef) else EMOJI_FUNC
                    sig = get_function_signature(item)
                    qual = item.name if not qual_prefix else f"{qual_prefix}.{item.name}"
                    start = getattr(item, "lineno", None)
                    end = getattr(item, "end_lineno", start)
                    decorators = getattr(item, "decorator_list", None) or []
                    decor_start: Optional[int] = None
                    if decorators and isinstance(start, int):
                        dec_lines = [
                            getattr(d, "lineno", None)
                            for d in decorators
                            if getattr(d, "lineno", None)
                        ]
                        if dec_lines:
                            decor_start = min(dec_lines)

                    doc = get_docstring(item)
                    note_lines: list[str] = [f"AST_QUALNAME: {qual}"]
                    if doc:
                        note_lines.append("---")
                        note_lines.append(doc)
                    context_lines = _extract_ast_comment_context(start, decor_start) if isinstance(start, int) else []
                    if context_lines:
                        note_lines.append("")
                        note_lines.append("CONTEXT COMMENTS (PYTHON):")
                        note_lines.extend(context_lines)
                    note_text = "\n".join(note_lines)

                    node = {
                        "name": f"{prefix} {sig}",
                        "priority": priority_counter[0],
                        "note": note_text,
                        "children": walk_body(item.body, qual_prefix=qual),
                        "ast_type": "async_function" if isinstance(item, ast.AsyncFunctionDef) else "function",
                        "ast_name": item.name,
                        "ast_qualname": qual,
                        "file_path": file_path,
                        "orig_lineno_start_unused": start,
                        "orig_lineno_end_unused": end,
                        "decor_start_lineno": decor_start,
                    }
                    priority_counter[0] += 100
                    results.append(node)
                elif isinstance(item, ast.Assign):
                    # Optional: Capture constants and selected module globals at this structural level.
                    for target in item.targets:
                        if isinstance(target, ast.Name) and _should_map_python_assigned_name(
                            target.id,
                            qual_prefix=qual_prefix,
                        ):
                            start = getattr(item, "lineno", None)
                            end = getattr(item, "end_lineno", start)
                            qual_const = target.id if not qual_prefix else f"{qual_prefix}.{target.id}"
                            note_label = _assigned_name_note_label(target.id, qual_prefix=qual_prefix)
                            note_text = f"AST_QUALNAME: {qual_const}\n---\n{note_label}"
                            node = {
                                "name": f"{EMOJI_CONST} {target.id}",
                                "priority": priority_counter[0],
                                "note": note_text,
                                "children": [],
                                "ast_type": "const",
                                "ast_name": target.id,
                                "ast_qualname": qual_const,
                                "file_path": file_path,
                                "orig_lineno_start_unused": start,
                                "orig_lineno_end_unused": end,
                            }
                            priority_counter[0] += 100
                            results.append(node)
                elif isinstance(item, ast.AnnAssign):
                    target = item.target
                    if isinstance(target, ast.Name) and _should_map_python_assigned_name(
                        target.id,
                        qual_prefix=qual_prefix,
                    ):
                        start = getattr(item, "lineno", None)
                        end = getattr(item, "end_lineno", start)
                        qual_const = target.id if not qual_prefix else f"{qual_prefix}.{target.id}"
                        note_label = _assigned_name_note_label(target.id, qual_prefix=qual_prefix)
                        note_text = f"AST_QUALNAME: {qual_const}\n---\n{note_label}"
                        node = {
                            "name": f"{EMOJI_CONST} {target.id}",
                            "priority": priority_counter[0],
                            "note": note_text,
                            "children": [],
                            "ast_type": "const",
                            "ast_name": target.id,
                            "ast_qualname": qual_const,
                            "file_path": file_path,
                            "orig_lineno_start_unused": start,
                            "orig_lineno_end_unused": end,
                        }
                        priority_counter[0] += 100
                        results.append(node)
                else:
                    for nested_body in _iter_nested_statement_bodies(item):
                        results.extend(walk_body(nested_body, qual_prefix=qual_prefix))
            return results

        outline_nodes = walk_body(tree.body)
        apply_python_beacons(file_path, lines, outline_nodes)
        return outline_nodes

    except Exception as e:
        return [{
            "name": _warn_name("⚠️ Parse Error"),
            "note": str(e),
            "children": []
        }]

# @beacon[
#   id=carto-js-ts@parse_js_ts_outline,
#   role=carto-js-ts,
#   slice_labels=carto-js-ts,ra-snippet-range-ast-js-ts,ra-reconcile,
#   kind=span,
# ]
# Phase 1 JS/TS: placeholder anchor for the future parse_js_ts_outline(...)
# function. The next agent will define the JS/TS Tree-sitter-based outline
# builder immediately above or below this beacon so Cartographer can
# produce JS/TS AST nodes in the same shape as Python.

def parse_js_ts_outline(file_path: str) -> List[Dict[str, Any]]:
    """Parse a single JavaScript / TypeScript file into a NEXUS outline tree.

    This mirrors parse_file_outline for Python but uses Tree-sitter to
    discover classes, functions, and methods and produces nodes with the
    same schema (ast_type, ast_name, ast_qualname, file_path,
    orig_lineno_start_unused, orig_lineno_end_unused, children, priority).
    """
    ext = os.path.splitext(file_path)[1].lower()
    if ext not in {".js", ".jsx", ".ts", ".tsx"}:
        return [{
            "name": _warn_name("⚠️ Unsupported JS/TS extension"),
            "note": f"File {file_path!r} does not look like a JS/TS source file.",
            "children": [],
        }]

    if not _HAVE_TREE_SITTER:
        return [{
            "name": _warn_name("⚠️ JS/TS parsing not available"),
            "note": (
                "Tree-sitter / tree_sitter_language_pack could not be imported. "
                "Install 'tree_sitter' and 'tree_sitter-language-pack' "
                "(plus language wheels like 'tree-sitter-javascript' and 'tree-sitter-typescript') "
                "in the Windows Python environment to enable JS/TS Cartographer support."
            ),
            "children": [],
        }]

    language_name = "javascript"
    if ext == ".ts":
        language_name = "typescript"
    elif ext == ".tsx":
        language_name = "tsx"

    try:
        with open(file_path, "r", encoding="utf-8") as f:
            source_text = f.read()
        source_bytes = source_text.encode("utf-8")

        parser = Parser()
        language = get_language(language_name)  # type: ignore[operator]
        parser.language = language
        tree = parser.parse(source_bytes)
        root = tree.root_node

        # Precompute comment mask and cleaned comment text for JS/TS files so
        # AST nodes can slurp nearby comments into their Workflowy notes.
        lines = source_text.splitlines()
        n = len(lines)

        # @beacon[
        #   id=carto-js-ts@_build_js_comment_mask-9p1f,
        #   role=carto-js-ts,
        #   slice_labels=carto-js-ts,ra-snippet-range-ast-js-ts,
        #   kind=ast,
        # ]
        def _build_js_comment_mask(src_lines: list[str]) -> tuple[list[bool], list[str]]:
            comment_mask: list[bool] = [False] * len(src_lines)
            cleaned: list[str] = ["" for _ in range(len(src_lines))]
            in_block = False

            for idx, raw in enumerate(src_lines, start=1):
                stripped = raw.lstrip()
                if not stripped:
                    continue
                if "@beacon" in stripped:
                    # Beacon metadata is handled separately; do not treat it as
                    # human context for AST nodes.
                    continue

                is_comment = False
                text = ""

                if not in_block:
                    if stripped.startswith("//"):
                        is_comment = True
                        text = stripped[2:].lstrip()
                    elif "/*" in stripped:
                        is_comment = True
                        in_block = True
                        after = stripped.split("/*", 1)[1]
                        if "*/" in after:
                            before_close, _ = after.split("*/", 1)
                            text = before_close.strip()
                            in_block = False
                        else:
                            text = after.strip()
                else:
                    is_comment = True
                    if "*/" in stripped:
                        before_close, _ = stripped.split("*/", 1)
                        text = before_close.strip()
                        in_block = False
                    else:
                        text = stripped

                if is_comment:
                    comment_mask[idx - 1] = True
                    cleaned[idx - 1] = text

            return comment_mask, cleaned

        comment_mask, cleaned_comments = _build_js_comment_mask(lines)

        # @beacon[
        #   id=carto-js-ts@_extract_js_ast_comment_context-v3sd,
        #   role=carto-js-ts,
        #   slice_labels=carto-js-ts,ra-snippet-range-ast-js-ts,
        #   kind=ast,
        # ]
        def _extract_js_ast_comment_context(start_line: int) -> list[str]:
            ctx: list[str] = []

            # Above: walk upward through contiguous comment lines, skipping
            # decorator-like lines that start with '@'.
            j = start_line - 1
            while j >= 1:
                raw = lines[j - 1]
                stripped = raw.lstrip()
                if not stripped:
                    j -= 1
                    continue
                if stripped.startswith("@"):
                    j -= 1
                    continue
                if comment_mask[j - 1]:
                    text = cleaned_comments[j - 1]
                    if text:
                        ctx.insert(0, text)
                    j -= 1
                    continue
                break

            # Below: immediate top-of-body comments (before code).
            j = start_line + 1
            while j <= n:
                raw = lines[j - 1]
                stripped = raw.lstrip()
                if not stripped:
                    j += 1
                    continue
                if comment_mask[j - 1]:
                    text = cleaned_comments[j - 1]
                    if text:
                        ctx.append(text)
                    j += 1
                    continue
                break

            return ctx

        priority_counter = [100]

        def node_text(n) -> str:
            if n is None:
                return ""
            return source_bytes[n.start_byte:n.end_byte].decode("utf-8", errors="ignore")

        def make_note(qual: str, start_line: int | None = None, doc: Optional[str] = None) -> str:
            note_lines: List[str] = [f"AST_QUALNAME: {qual}"]
            if doc:
                note_lines.append("---")
                note_lines.append(doc)
            if isinstance(start_line, int):
                ctx = _extract_js_ast_comment_context(start_line)
                if ctx:
                    note_lines.append("")
                    note_lines.append("CONTEXT COMMENTS (JS/TS):")
                    note_lines.extend(ctx)
            return "\n".join(note_lines)

        def walk(
            node,
            qual_prefix: Optional[str] = None,
            scope_state: Optional[dict[str, Any]] = None,
        ) -> List[Dict[str, Any]]:
            if scope_state is None:
                scope_state = _new_js_scope_state(is_lambda=False)

            results: List[Dict[str, Any]] = []

            for child in node.children:
                t = child.type

                if t == "class_declaration":
                    name_node = child.child_by_field_name("name")
                    class_name = node_text(name_node).strip() or "AnonymousClass"
                    qual = class_name if not qual_prefix else f"{qual_prefix}.{class_name}"
                    start_line = child.start_point[0] + 1
                    end_line = child.end_point[0] + 1

                    # TODO: in future, harvest JSDoc comments into doc
                    note_text = make_note(qual, start_line)

                    class_node: Dict[str, Any] = {
                        "name": f"{EMOJI_CLASS} class {class_name}",
                        "priority": priority_counter[0],
                        "note": note_text,
                        "children": [],
                        "ast_type": "class",
                        "ast_name": class_name,
                        "ast_qualname": qual,
                        "file_path": file_path,
                        "orig_lineno_start_unused": start_line,
                        "orig_lineno_end_unused": end_line,
                    }
                    priority_counter[0] += 100

                    body = child.child_by_field_name("body")
                    if body is not None:
                        class_node["children"] = walk(
                            body,
                            qual_prefix=qual,
                            scope_state=_new_js_scope_state(is_lambda=False),
                        )

                    results.append(class_node)
                    continue

                # TypeScript surface types (top-level or nested in namespaces/modules).
                # These are important for navigation but should not explode into deep trees.
                if t in {"interface_declaration", "type_alias_declaration", "enum_declaration"}:
                    name_node = child.child_by_field_name("name")
                    type_name = node_text(name_node).strip() or "anonymous"
                    qual = type_name if not qual_prefix else f"{qual_prefix}.{type_name}"
                    start_line = child.start_point[0] + 1
                    end_line = child.end_point[0] + 1
                    note_text = make_note(qual, start_line)

                    kind_label = (
                        "interface" if t == "interface_declaration" else
                        "type" if t == "type_alias_declaration" else
                        "enum"
                    )
                    type_node: Dict[str, Any] = {
                        "name": f"{EMOJI_CLASS} {kind_label} {type_name}",
                        "priority": priority_counter[0],
                        "note": note_text,
                        "children": [],
                        "ast_type": kind_label,
                        "ast_name": type_name,
                        "ast_qualname": qual,
                        "file_path": file_path,
                        "orig_lineno_start_unused": start_line,
                        "orig_lineno_end_unused": end_line,
                    }
                    priority_counter[0] += 100
                    results.append(type_node)
                    continue

                if t == "function_declaration":
                    name_node = child.child_by_field_name("name")
                    func_name = node_text(name_node).strip() or "anonymous"
                    qual = func_name if not qual_prefix else f"{qual_prefix}.{func_name}"
                    start_line = child.start_point[0] + 1
                    end_line = child.end_point[0] + 1

                    signature = func_name
                    params_node = child.child_by_field_name("parameters")
                    if params_node is not None:
                        params_text = node_text(params_node).strip()
                        signature = f"{func_name}{params_text}"

                    note_text = make_note(qual, start_line)

                    func_node: Dict[str, Any] = {
                        "name": f"{EMOJI_FUNC} function {signature}",
                        "priority": priority_counter[0],
                        "note": note_text,
                        "children": [],
                        "ast_type": "function",
                        "ast_name": func_name,
                        "ast_qualname": qual,
                        "file_path": file_path,
                        "orig_lineno_start_unused": start_line,
                        "orig_lineno_end_unused": end_line,
                    }
                    priority_counter[0] += 100

                    body = child.child_by_field_name("body")
                    if body is not None:
                        func_node["children"] = walk(
                            body,
                            qual_prefix=qual,
                            scope_state=_new_js_scope_state(is_lambda=False),
                        )

                    results.append(func_node)
                    continue

                if t == "method_definition":
                    name_node = child.child_by_field_name("name")
                    method_name = node_text(name_node).strip() or "anonymous"
                    qual = method_name if not qual_prefix else f"{qual_prefix}.{method_name}"
                    start_line = child.start_point[0] + 1
                    end_line = child.end_point[0] + 1

                    params_node = child.child_by_field_name("parameters")
                    signature = method_name
                    if params_node is not None:
                        params_text = node_text(params_node).strip()
                        signature = f"{method_name}{params_text}"

                    note_text = make_note(qual, start_line)

                    method_node: Dict[str, Any] = {
                        "name": f"{EMOJI_FUNC} method {signature}",
                        "priority": priority_counter[0],
                        "note": note_text,
                        "children": [],
                        "ast_type": "method",
                        "ast_name": method_name,
                        "ast_qualname": qual,
                        "file_path": file_path,
                        "orig_lineno_start_unused": start_line,
                        "orig_lineno_end_unused": end_line,
                    }
                    priority_counter[0] += 100

                    body = child.child_by_field_name("body")
                    if body is not None:
                        method_node["children"] = walk(
                            body,
                            qual_prefix=qual,
                            scope_state=_new_js_scope_state(is_lambda=False),
                        )

                    results.append(method_node)
                    continue

                # const/let/var declarations.
                #
                # We ALWAYS parse variable declarations so we can represent common
                # JS/TS patterns like Pinia/Vue stores:
                #
                #   export const useXStore = defineStore('x', () => {
                #       const doThing = () => { ... }
                #       function helper() { ... }
                #       return { doThing }
                #   })
                #
                # Policy to avoid outline explosion:
                # - At module scope (qual_prefix is None): emit nodes for simple
                #   identifier declarators (existing behavior).
                # - Inside an existing qual_prefix (nested scope): emit ONLY
                #   declarators whose RHS is function-like (arrow/function) or a
                #   known "container" call like defineStore(...) that contains a
                #   function body.
                if t in {"lexical_declaration", "variable_declaration"}:
                    decl_text = node_text(child).lstrip()
                    decl_kind = (decl_text.split(None, 1)[0] if decl_text else "const").strip()
                    if decl_kind not in {"const", "let", "var"}:
                        decl_kind = "const"

                    def _is_function_like(v) -> bool:
                        return bool(v) and getattr(v, "type", None) in {"arrow_function", "function"}

                    def _callee_simple_name(v) -> str:
                        if not v or getattr(v, "type", None) != "call_expression":
                            return ""
                        fn = v.child_by_field_name("function")
                        if fn is None:
                            return ""
                        fn_text = node_text(fn).strip()
                        m = re.search(r"([A-Za-z_][A-Za-z0-9_]*)\s*$", fn_text)
                        return m.group(1) if m else ""

                    # @beacon[
                    #   id=carto-js-ts@parse_js_ts_outline._find_function_wrapper_body-c6f1,
                    #   role=carto-js-ts,
                    #   slice_labels=carto-js-ts,carto-js-ts-beacons,f9-f12-handlers,ra-reconcile,
                    #   kind=ast,
                    #   comment=Detect wrapper calls like computed(() => ...) so nested computed declarations appear in Workflowy AST maps.
                    # ]
                    def _find_function_wrapper_body(v):
                        # Recognize wrapper calls that carry a function body in their args,
                        # e.g. computed(() => { ... }).
                        if not v or getattr(v, "type", None) != "call_expression":
                            return None
                        callee = _callee_simple_name(v)
                        if callee not in {"computed"}:
                            return None
                        args = v.child_by_field_name("arguments")
                        if args is None:
                            return None
                        for a in getattr(args, "named_children", []) or []:
                            if _is_function_like(a):
                                body = a.child_by_field_name("body")
                                if body is not None:
                                    return body
                        return None

                    def _find_define_store_setup_body(v):
                        # Return the BODY node of the setup function passed to defineStore, else None.
                        if not v or getattr(v, "type", None) != "call_expression":
                            return None
                        fn = v.child_by_field_name("function")
                        if fn is None:
                            return None
                        fn_text = node_text(fn).strip()
                        if not fn_text.endswith("defineStore"):
                            return None
                        args = v.child_by_field_name("arguments")
                        if args is None:
                            return None
                        for a in getattr(args, "named_children", []) or []:
                            if getattr(a, "type", None) in {"arrow_function", "function"}:
                                body = a.child_by_field_name("body")
                                if body is not None:
                                    return body
                        return None

                    def _find_define_store_options_object(v):
                        # Options store form: defineStore('id', { actions: {...}, getters: {...} })
                        if not v or getattr(v, "type", None) != "call_expression":
                            return None
                        fn = v.child_by_field_name("function")
                        if fn is None:
                            return None
                        fn_text = node_text(fn).strip()
                        if not fn_text.endswith("defineStore"):
                            return None
                        args = v.child_by_field_name("arguments")
                        if args is None:
                            return None
                        for a in getattr(args, "named_children", []) or []:
                            if getattr(a, "type", None) == "object":
                                return a
                        return None

                    def _extract_define_store_options_children(*, options_obj, store_qual: str) -> list[dict[str, Any]]:
                        # Parse defineStore options object and emit actions/getters functions.
                        out: list[dict[str, Any]] = []

                        def _key_text(n) -> str:
                            if n is None:
                                return ""
                            txt = node_text(n).strip()
                            return txt.strip("\"'")

                        def _params_text(fn_node) -> str:
                            if fn_node is None:
                                return "()"
                            p = fn_node.child_by_field_name("parameters")
                            if p is None:
                                p = fn_node.child_by_field_name("parameter")
                            if p is None:
                                return "()"
                            t = node_text(p).strip()
                            return t if t.startswith("(") else f"({t})"

                        def _body_node(fn_node):
                            if fn_node is None:
                                return None
                            return fn_node.child_by_field_name("body")

                        def _emit_obj_functions(*, section: str, obj_node) -> None:
                            if obj_node is None:
                                return
                            for prop in getattr(obj_node, "children", []) or []:
                                pt = getattr(prop, "type", None)
                                if pt == "method_definition":
                                    name_n = prop.child_by_field_name("name")
                                    fname = _key_text(name_n) or "anonymous"
                                    qual = f"{store_qual}.{section}.{fname}"
                                    start_line = prop.start_point[0] + 1
                                    end_line = prop.end_point[0] + 1
                                    sig = f"{fname}{_params_text(prop)}"
                                    note_text = make_note(qual, start_line)
                                    body = _body_node(prop)
                                    children_local = walk(
                                        body,
                                        qual_prefix=qual,
                                        scope_state=_new_js_scope_state(is_lambda=False),
                                    ) if body is not None else []
                                    out.append({
                                        "name": f"{EMOJI_FUNC} {section} {sig}",
                                        "priority": priority_counter[0],
                                        "note": note_text,
                                        "children": children_local,
                                        "ast_type": "method",
                                        "ast_name": fname,
                                        "ast_qualname": qual,
                                        "file_path": file_path,
                                        "orig_lineno_start_unused": start_line,
                                        "orig_lineno_end_unused": end_line,
                                    })
                                    priority_counter[0] += 100
                                    continue
                                if pt == "pair":
                                    k = prop.child_by_field_name("key")
                                    v = prop.child_by_field_name("value")
                                    fname = _key_text(k) or "anonymous"
                                    if v is None or getattr(v, "type", None) not in {"arrow_function", "function"}:
                                        continue
                                    qual = f"{store_qual}.{section}.{fname}"
                                    start_line = prop.start_point[0] + 1
                                    end_line = prop.end_point[0] + 1
                                    sig = f"{fname}{_params_text(v)}"
                                    note_text = make_note(qual, start_line)
                                    body = _body_node(v)
                                    children_local = walk(
                                        body,
                                        qual_prefix=qual,
                                        scope_state=_new_js_scope_state(is_lambda=False),
                                    ) if body is not None else []
                                    out.append({
                                        "name": f"{EMOJI_FUNC} {section} {sig}",
                                        "priority": priority_counter[0],
                                        "note": note_text,
                                        "children": children_local,
                                        "ast_type": "function",
                                        "ast_name": fname,
                                        "ast_qualname": qual,
                                        "file_path": file_path,
                                        "orig_lineno_start_unused": start_line,
                                        "orig_lineno_end_unused": end_line,
                                    })
                                    priority_counter[0] += 100
                                    continue

                        # locate actions/getters objects
                        for prop in getattr(options_obj, "children", []) or []:
                            if getattr(prop, "type", None) != "pair":
                                continue
                            k = prop.child_by_field_name("key")
                            v = prop.child_by_field_name("value")
                            key = _key_text(k)
                            if key not in {"actions", "getters"}:
                                continue
                            if v is None or getattr(v, "type", None) != "object":
                                continue
                            _emit_obj_functions(section=key[:-1] if key.endswith("s") else key, obj_node=v)

                        return out

                    for decl_child in child.children:
                        if decl_child.type != "variable_declarator":
                            continue
                        name_node = decl_child.child_by_field_name("name")
                        if name_node is None:
                            continue
                        # Skip destructuring patterns (object_pattern/array_pattern)
                        if getattr(name_node, "type", None) != "identifier":
                            continue
                        var_name = node_text(name_node).strip()
                        if not var_name:
                            continue

                        value_node = decl_child.child_by_field_name("value")
                        setup_body = None
                        options_obj = None
                        if value_node is not None:
                            if _is_function_like(value_node):
                                setup_body = value_node.child_by_field_name("body")
                            else:
                                setup_body = _find_function_wrapper_body(value_node)
                                if setup_body is None:
                                    setup_body = _find_define_store_setup_body(value_node)
                                    if setup_body is None:
                                        options_obj = _find_define_store_options_object(value_node)

                        in_lambda_scope = bool(isinstance(scope_state, dict) and scope_state.get("is_lambda"))
                        emit_here = (not qual_prefix) or in_lambda_scope or (setup_body is not None) or (options_obj is not None)
                        if not emit_here:
                            continue

                        start_line = decl_child.start_point[0] + 1
                        end_line = decl_child.end_point[0] + 1

                        if in_lambda_scope and setup_body is None and options_obj is None:
                            if not _is_meaningful_js_local_name(var_name):
                                continue

                        if in_lambda_scope:
                            local_suffix = _js_next_lambda_local_suffix(scope_state, var_name)
                            qual = f"{qual_prefix}.{var_name}@{local_suffix}"
                        else:
                            qual = var_name if not qual_prefix else f"{qual_prefix}.{var_name}"
                        note_text = make_note(qual, start_line)

                        children_local: list[dict[str, Any]] = []
                        if setup_body is not None:
                            children_local = walk(
                                setup_body,
                                qual_prefix=qual,
                                scope_state=_new_js_scope_state(is_lambda=False),
                            )
                        elif options_obj is not None:
                            children_local = _extract_define_store_options_children(
                                options_obj=options_obj,
                                store_qual=qual,
                            )

                        node_dict: Dict[str, Any] = {
                            "name": f"{EMOJI_FUNC} {decl_kind} {var_name}",
                            "priority": priority_counter[0],
                            "note": note_text,
                            "children": children_local,
                            "ast_type": f"{decl_kind}_decl",
                            "ast_name": var_name,
                            "ast_qualname": qual,
                            "file_path": file_path,
                            "orig_lineno_start_unused": start_line,
                            "orig_lineno_end_unused": end_line,
                        }
                        priority_counter[0] += 100
                        results.append(node_dict)

                    continue

                # Recurse into other nodes to discover nested declarations.
                #
                # IMPORTANT: anonymous function scopes (arrow/function expressions)
                # can contain local declarations with repeated names (e.g. two
                # separate callbacks each declaring `const tintOpts`). If we recurse
                # with the same qual_prefix, those locals collide on AST_QUALNAME.
                #
                # We therefore derive a deterministic pseudo-scope suffix from source
                # coordinates for function-like anonymous scopes.
                next_prefix = qual_prefix
                next_scope_state = scope_state
                if t in {"arrow_function", "function", "function_expression"}:
                    anon_scope = _js_next_anonymous_scope_name(scope_state)
                    next_prefix = f"{qual_prefix}.{anon_scope}" if qual_prefix else anon_scope
                    next_scope_state = _new_js_scope_state(is_lambda=True)

                if child.children:
                    results.extend(walk(child, qual_prefix=next_prefix, scope_state=next_scope_state))

            return results

        outline_nodes = walk(root)

        # Phase 2: JS/TS beacon parsing + attachment
        lines = source_text.splitlines()
        js_beacons = parse_js_beacon_blocks(lines)
        apply_js_beacons(file_path, lines, outline_nodes, js_beacons)
        return outline_nodes

    except Exception as e:  # pragma: no cover - safety net
        return [{
            "name": _warn_name("⚠️ Parse Error (JS/TS)"),
            "note": str(e),
            "children": [],
        }]


def _vue_compact_start_tag_text(raw: str) -> str:
    """Return a stable single-line representation of a Vue start tag."""
    s = (raw or "").replace("\t", " ").replace("\r", "").replace("\n", " ")
    while "  " in s:
        s = s.replace("  ", " ")
    return s.strip()


def _vue_rebase_beacons(beacons: list[dict[str, Any]], line_offset0: int) -> list[dict[str, Any]]:
    """Return a shallow-copied beacon list with line numbers rebased to file lines.

    line_offset0 is 0-based file row of the first line in the section's raw_text.
    """
    out: list[dict[str, Any]] = []
    for b in beacons or []:
        if not isinstance(b, dict):
            continue
        b2 = dict(b)
        for k in ("comment_line", "span_lineno_start", "span_lineno_end"):
            v = b2.get(k)
            if isinstance(v, int) and v > 0:
                b2[k] = v + line_offset0
        out.append(b2)
    return out


# @beacon[
#   id=auto-beacon@_parse_js_ts_outline_from_source,
#   role=_parse_js_ts_outline_from_source,
#   slice_labels=carto-js-ts,ra-snippet-range-ast-js-ts,
#   kind=ast,
# ]
def _parse_js_ts_outline_from_source(
    *,
    source_text: str,
    file_path: str,
    language_name: str,
    line_offset0: int,
    vue_qual_prefix: str,
) -> List[Dict[str, Any]]:
    """Parse JS/TS AST from a source string and rebase node line numbers.

    - line_offset0: 0-based file row where source_text line 1 lives.
    - vue_qual_prefix: prefix to prepend to every AST_QUALNAME for uniqueness.
    """
    if not _HAVE_TREE_SITTER:
        return [{
            "name": _warn_name("⚠️ JS/TS parsing not available"),
            "note": (
                "Tree-sitter / tree_sitter_language_pack could not be imported. "
                "Install 'tree_sitter' and 'tree_sitter-language-pack' "
                "(plus language wheels like 'tree-sitter-javascript' and 'tree-sitter-typescript') "
                "in the Windows Python environment to enable JS/TS Cartographer support."
            ),
            "children": [],
        }]

    try:
        source_bytes = source_text.encode("utf-8")

        parser = Parser()
        language = get_language(language_name)  # type: ignore[operator]
        parser.language = language
        tree = parser.parse(source_bytes)
        root = tree.root_node

        lines_local = source_text.splitlines()
        n_local = len(lines_local)

        # Precompute comment mask and cleaned comment text for JS/TS files so
        # AST nodes can slurp nearby comments into their Workflowy notes.
        def _build_js_comment_mask(src_lines: list[str]) -> tuple[list[bool], list[str]]:
            comment_mask: list[bool] = [False] * len(src_lines)
            cleaned: list[str] = ["" for _ in range(len(src_lines))]
            in_block = False

            for idx, raw in enumerate(src_lines, start=1):
                stripped = raw.lstrip()
                if not stripped:
                    continue
                if "@beacon" in stripped:
                    continue

                is_comment = False
                text = ""

                if not in_block:
                    if stripped.startswith("//"):
                        is_comment = True
                        text = stripped[2:].lstrip()
                    elif "/*" in stripped:
                        is_comment = True
                        in_block = True
                        after = stripped.split("/*", 1)[1]
                        if "*/" in after:
                            before_close, _ = after.split("*/", 1)
                            text = before_close.strip()
                            in_block = False
                        else:
                            text = after.strip()
                else:
                    is_comment = True
                    if "*/" in stripped:
                        before_close, _ = stripped.split("*/", 1)
                        text = before_close.strip()
                        in_block = False
                    else:
                        text = stripped

                if is_comment:
                    comment_mask[idx - 1] = True
                    cleaned[idx - 1] = text

            return comment_mask, cleaned

        comment_mask, cleaned_comments = _build_js_comment_mask(lines_local)

        def _extract_js_ast_comment_context(start_line_local: int) -> list[str]:
            ctx: list[str] = []

            j = start_line_local - 1
            while j >= 1:
                raw = lines_local[j - 1]
                stripped = raw.lstrip()
                if not stripped:
                    j -= 1
                    continue
                if stripped.startswith("@"):  # decorator-like
                    j -= 1
                    continue
                if comment_mask[j - 1]:
                    text = cleaned_comments[j - 1]
                    if text:
                        ctx.insert(0, text)
                    j -= 1
                    continue
                break

            j = start_line_local + 1
            while j <= n_local:
                raw = lines_local[j - 1]
                stripped = raw.lstrip()
                if not stripped:
                    j += 1
                    continue
                if comment_mask[j - 1]:
                    text = cleaned_comments[j - 1]
                    if text:
                        ctx.append(text)
                    j += 1
                    continue
                break

            return ctx

        priority_counter = [100]

        def node_text(n) -> str:
            if n is None:
                return ""
            return source_bytes[n.start_byte:n.end_byte].decode("utf-8", errors="ignore")

        def make_note(qual: str, start_line_local: int | None = None) -> str:
            note_lines: List[str] = [f"AST_QUALNAME: {qual}"]
            if isinstance(start_line_local, int):
                ctx = _extract_js_ast_comment_context(start_line_local)
                if ctx:
                    note_lines.append("")
                    note_lines.append("CONTEXT COMMENTS (JS/TS):")
                    note_lines.extend(ctx)
            return "\n".join(note_lines)

        def _qual(inner_qual: str) -> str:
            pref = (vue_qual_prefix or "").strip()
            if pref and not pref.endswith(":"):
                pref = pref + ":"
            return f"{pref}{inner_qual}" if pref else inner_qual

        def walk(
            node,
            qual_prefix: Optional[str] = None,
            scope_state: Optional[dict[str, Any]] = None,
        ) -> List[Dict[str, Any]]:
            if scope_state is None:
                scope_state = _new_js_scope_state(is_lambda=False)

            results: List[Dict[str, Any]] = []

            for child in node.children:
                t = child.type

                if t == "class_declaration":
                    name_node = child.child_by_field_name("name")
                    class_name = node_text(name_node).strip() or "AnonymousClass"
                    inner = class_name if not qual_prefix else f"{qual_prefix}.{class_name}"
                    qual = _qual(inner)
                    start_line_local = child.start_point[0] + 1
                    end_line_local = child.end_point[0] + 1
                    start_line_abs = start_line_local + line_offset0
                    end_line_abs = end_line_local + line_offset0

                    note_text = make_note(qual, start_line_local)

                    class_node: Dict[str, Any] = {
                        "name": f"{EMOJI_CLASS} class {class_name}",
                        "priority": priority_counter[0],
                        "note": note_text,
                        "children": [],
                        "ast_type": "class",
                        "ast_name": class_name,
                        "ast_qualname": qual,
                        "file_path": file_path,
                        "orig_lineno_start_unused": start_line_abs,
                        "orig_lineno_end_unused": end_line_abs,
                    }
                    priority_counter[0] += 100

                    body = child.child_by_field_name("body")
                    if body is not None:
                        class_node["children"] = walk(
                            body,
                            qual_prefix=inner,
                            scope_state=_new_js_scope_state(is_lambda=False),
                        )

                    results.append(class_node)
                    continue

                # TypeScript surface types (interfaces/types/enums) inside Vue <script>.
                if t in {"interface_declaration", "type_alias_declaration", "enum_declaration"}:
                    name_node = child.child_by_field_name("name")
                    type_name = node_text(name_node).strip() or "anonymous"
                    inner = type_name if not qual_prefix else f"{qual_prefix}.{type_name}"
                    qual = _qual(inner)
                    start_line_local = child.start_point[0] + 1
                    end_line_local = child.end_point[0] + 1
                    start_line_abs = start_line_local + line_offset0
                    end_line_abs = end_line_local + line_offset0
                    note_text = make_note(qual, start_line_local)

                    kind_label = (
                        "interface" if t == "interface_declaration" else
                        "type" if t == "type_alias_declaration" else
                        "enum"
                    )
                    type_node: Dict[str, Any] = {
                        "name": f"{EMOJI_CLASS} {kind_label} {type_name}",
                        "priority": priority_counter[0],
                        "note": note_text,
                        "children": [],
                        "ast_type": kind_label,
                        "ast_name": type_name,
                        "ast_qualname": qual,
                        "file_path": file_path,
                        "orig_lineno_start_unused": start_line_abs,
                        "orig_lineno_end_unused": end_line_abs,
                    }
                    priority_counter[0] += 100
                    results.append(type_node)
                    continue

                if t == "function_declaration":
                    name_node = child.child_by_field_name("name")
                    func_name = node_text(name_node).strip() or "anonymous"
                    inner = func_name if not qual_prefix else f"{qual_prefix}.{func_name}"
                    qual = _qual(inner)
                    start_line_local = child.start_point[0] + 1
                    end_line_local = child.end_point[0] + 1
                    start_line_abs = start_line_local + line_offset0
                    end_line_abs = end_line_local + line_offset0

                    signature = func_name
                    params_node = child.child_by_field_name("parameters")
                    if params_node is not None:
                        params_text = node_text(params_node).strip()
                        signature = f"{func_name}{params_text}"

                    note_text = make_note(qual, start_line_local)

                    func_node: Dict[str, Any] = {
                        "name": f"{EMOJI_FUNC} function {signature}",
                        "priority": priority_counter[0],
                        "note": note_text,
                        "children": [],
                        "ast_type": "function",
                        "ast_name": func_name,
                        "ast_qualname": qual,
                        "file_path": file_path,
                        "orig_lineno_start_unused": start_line_abs,
                        "orig_lineno_end_unused": end_line_abs,
                    }
                    priority_counter[0] += 100

                    body = child.child_by_field_name("body")
                    if body is not None:
                        func_node["children"] = walk(
                            body,
                            qual_prefix=inner,
                            scope_state=_new_js_scope_state(is_lambda=False),
                        )

                    results.append(func_node)
                    continue

                if t == "method_definition":
                    name_node = child.child_by_field_name("name")
                    method_name = node_text(name_node).strip() or "anonymous"
                    inner = method_name if not qual_prefix else f"{qual_prefix}.{method_name}"
                    qual = _qual(inner)
                    start_line_local = child.start_point[0] + 1
                    end_line_local = child.end_point[0] + 1
                    start_line_abs = start_line_local + line_offset0
                    end_line_abs = end_line_local + line_offset0

                    params_node = child.child_by_field_name("parameters")
                    signature = method_name
                    if params_node is not None:
                        params_text = node_text(params_node).strip()
                        signature = f"{method_name}{params_text}"

                    note_text = make_note(qual, start_line_local)

                    method_node: Dict[str, Any] = {
                        "name": f"{EMOJI_FUNC} method {signature}",
                        "priority": priority_counter[0],
                        "note": note_text,
                        "children": [],
                        "ast_type": "method",
                        "ast_name": method_name,
                        "ast_qualname": qual,
                        "file_path": file_path,
                        "orig_lineno_start_unused": start_line_abs,
                        "orig_lineno_end_unused": end_line_abs,
                    }
                    priority_counter[0] += 100

                    body = child.child_by_field_name("body")
                    if body is not None:
                        method_node["children"] = walk(
                            body,
                            qual_prefix=inner,
                            scope_state=_new_js_scope_state(is_lambda=False),
                        )

                    results.append(method_node)
                    continue

                # const/let/var declarations in Vue <script> sections.
                #
                # We emit module-scope identifiers as navigational entry points,
                # but we ALSO emit nested function-like declarations so patterns
                # like defineStore(...) show their inner helpers/actions.
                if t in {"lexical_declaration", "variable_declaration"}:
                    decl_text = node_text(child).lstrip()
                    decl_kind = (decl_text.split(None, 1)[0] if decl_text else "const").strip()
                    if decl_kind not in {"const", "let", "var"}:
                        decl_kind = "const"

                    def _is_function_like(v) -> bool:
                        return bool(v) and getattr(v, "type", None) in {"arrow_function", "function"}

                    def _callee_simple_name(v) -> str:
                        if not v or getattr(v, "type", None) != "call_expression":
                            return ""
                        fn = v.child_by_field_name("function")
                        if fn is None:
                            return ""
                        fn_text = node_text(fn).strip()
                        m = re.search(r"([A-Za-z_][A-Za-z0-9_]*)\s*$", fn_text)
                        return m.group(1) if m else ""

                    # @beacon[
                    #   id=carto-js-ts@_parse_js_ts_outline_from_source._find_function_wrapper_body-u2a4,
                    #   role=carto-js-ts,
                    #   slice_labels=carto-js-ts,carto-js-ts-beacons,f9-f12-handlers,ra-reconcile,
                    #   kind=ast,
                    #   comment=Detect wrapper calls like computed(() => ...) inside extracted Vue script sources so computed declarations map as AST nodes.
                    # ]
                    def _find_function_wrapper_body(v):
                        # Recognize wrapper calls that carry a function body in their args,
                        # e.g. computed(() => { ... }).
                        if not v or getattr(v, "type", None) != "call_expression":
                            return None
                        callee = _callee_simple_name(v)
                        if callee not in {"computed"}:
                            return None
                        args = v.child_by_field_name("arguments")
                        if args is None:
                            return None
                        for a in getattr(args, "named_children", []) or []:
                            if _is_function_like(a):
                                body = a.child_by_field_name("body")
                                if body is not None:
                                    return body
                        return None

                    def _find_define_store_setup_body(v):
                        if not v or getattr(v, "type", None) != "call_expression":
                            return None
                        fn = v.child_by_field_name("function")
                        if fn is None:
                            return None
                        fn_text = node_text(fn).strip()
                        if not fn_text.endswith("defineStore"):
                            return None
                        args = v.child_by_field_name("arguments")
                        if args is None:
                            return None
                        for a in getattr(args, "named_children", []) or []:
                            if getattr(a, "type", None) in {"arrow_function", "function"}:
                                body = a.child_by_field_name("body")
                                if body is not None:
                                    return body
                        return None

                    def _find_define_store_options_object(v):
                        if not v or getattr(v, "type", None) != "call_expression":
                            return None
                        fn = v.child_by_field_name("function")
                        if fn is None:
                            return None
                        fn_text = node_text(fn).strip()
                        if not fn_text.endswith("defineStore"):
                            return None
                        args = v.child_by_field_name("arguments")
                        if args is None:
                            return None
                        for a in getattr(args, "named_children", []) or []:
                            if getattr(a, "type", None) == "object":
                                return a
                        return None

                    def _extract_define_store_options_children(*, options_obj, store_inner: str, store_qual: str) -> list[dict[str, Any]]:
                        out: list[dict[str, Any]] = []

                        def _key_text(n) -> str:
                            if n is None:
                                return ""
                            txt = node_text(n).strip()
                            return txt.strip("\"'")

                        def _params_text(fn_node) -> str:
                            if fn_node is None:
                                return "()"
                            p = fn_node.child_by_field_name("parameters")
                            if p is None:
                                p = fn_node.child_by_field_name("parameter")
                            if p is None:
                                return "()"
                            t = node_text(p).strip()
                            return t if t.startswith("(") else f"({t})"

                        def _body_node(fn_node):
                            if fn_node is None:
                                return None
                            return fn_node.child_by_field_name("body")

                        def _emit_obj_functions(*, section: str, obj_node) -> None:
                            if obj_node is None:
                                return
                            for prop in getattr(obj_node, "children", []) or []:
                                pt = getattr(prop, "type", None)
                                if pt == "method_definition":
                                    name_n = prop.child_by_field_name("name")
                                    fname = _key_text(name_n) or "anonymous"
                                    inner = f"{store_inner}.{section}.{fname}"
                                    qual = _qual(inner)
                                    start_line_local = prop.start_point[0] + 1
                                    end_line_local = prop.end_point[0] + 1
                                    start_line_abs = start_line_local + line_offset0
                                    end_line_abs = end_line_local + line_offset0
                                    sig = f"{fname}{_params_text(prop)}"
                                    note_text = make_note(qual, start_line_local)
                                    body = _body_node(prop)
                                    children_local = walk(
                                        body,
                                        qual_prefix=inner,
                                        scope_state=_new_js_scope_state(is_lambda=False),
                                    ) if body is not None else []
                                    out.append({
                                        "name": f"{EMOJI_FUNC} {section} {sig}",
                                        "priority": priority_counter[0],
                                        "note": note_text,
                                        "children": children_local,
                                        "ast_type": "method",
                                        "ast_name": fname,
                                        "ast_qualname": qual,
                                        "file_path": file_path,
                                        "orig_lineno_start_unused": start_line_abs,
                                        "orig_lineno_end_unused": end_line_abs,
                                    })
                                    priority_counter[0] += 100
                                    continue
                                if pt == "pair":
                                    k = prop.child_by_field_name("key")
                                    v = prop.child_by_field_name("value")
                                    fname = _key_text(k) or "anonymous"
                                    if v is None or getattr(v, "type", None) not in {"arrow_function", "function"}:
                                        continue
                                    inner = f"{store_inner}.{section}.{fname}"
                                    qual = _qual(inner)
                                    start_line_local = prop.start_point[0] + 1
                                    end_line_local = prop.end_point[0] + 1
                                    start_line_abs = start_line_local + line_offset0
                                    end_line_abs = end_line_local + line_offset0
                                    sig = f"{fname}{_params_text(v)}"
                                    note_text = make_note(qual, start_line_local)
                                    body = _body_node(v)
                                    children_local = walk(
                                        body,
                                        qual_prefix=inner,
                                        scope_state=_new_js_scope_state(is_lambda=False),
                                    ) if body is not None else []
                                    out.append({
                                        "name": f"{EMOJI_FUNC} {section} {sig}",
                                        "priority": priority_counter[0],
                                        "note": note_text,
                                        "children": children_local,
                                        "ast_type": "function",
                                        "ast_name": fname,
                                        "ast_qualname": qual,
                                        "file_path": file_path,
                                        "orig_lineno_start_unused": start_line_abs,
                                        "orig_lineno_end_unused": end_line_abs,
                                    })
                                    priority_counter[0] += 100
                                    continue

                        for prop in getattr(options_obj, "children", []) or []:
                            if getattr(prop, "type", None) != "pair":
                                continue
                            k = prop.child_by_field_name("key")
                            v = prop.child_by_field_name("value")
                            key = _key_text(k)
                            if key not in {"actions", "getters"}:
                                continue
                            if v is None or getattr(v, "type", None) != "object":
                                continue
                            _emit_obj_functions(section=key[:-1] if key.endswith("s") else key, obj_node=v)

                        return out

                    for decl_child in child.children:
                        if decl_child.type != "variable_declarator":
                            continue
                        name_node = decl_child.child_by_field_name("name")
                        if name_node is None:
                            continue
                        # Skip destructuring patterns (object_pattern/array_pattern)
                        if getattr(name_node, "type", None) != "identifier":
                            continue
                        var_name = node_text(name_node).strip()
                        if not var_name:
                            continue

                        value_node = decl_child.child_by_field_name("value")
                        setup_body = None
                        options_obj = None
                        if value_node is not None:
                            if _is_function_like(value_node):
                                setup_body = value_node.child_by_field_name("body")
                            else:
                                setup_body = _find_function_wrapper_body(value_node)
                                if setup_body is None:
                                    setup_body = _find_define_store_setup_body(value_node)
                                    if setup_body is None:
                                        options_obj = _find_define_store_options_object(value_node)

                        in_lambda_scope = bool(isinstance(scope_state, dict) and scope_state.get("is_lambda"))
                        emit_here = (not qual_prefix) or in_lambda_scope or (setup_body is not None) or (options_obj is not None)
                        if not emit_here:
                            continue

                        start_line_local = decl_child.start_point[0] + 1
                        end_line_local = decl_child.end_point[0] + 1

                        if in_lambda_scope and setup_body is None and options_obj is None:
                            if not _is_meaningful_js_local_name(var_name):
                                continue

                        if in_lambda_scope:
                            local_suffix = _js_next_lambda_local_suffix(scope_state, var_name)
                            inner = f"{qual_prefix}.{var_name}@{local_suffix}"
                        else:
                            inner = var_name if not qual_prefix else f"{qual_prefix}.{var_name}"
                        qual = _qual(inner)

                        start_line_abs = start_line_local + line_offset0
                        end_line_abs = end_line_local + line_offset0

                        note_text = make_note(qual, start_line_local)

                        children_local: list[dict[str, Any]] = []
                        if setup_body is not None:
                            children_local = walk(
                                setup_body,
                                qual_prefix=inner,
                                scope_state=_new_js_scope_state(is_lambda=False),
                            )
                        elif options_obj is not None:
                            children_local = _extract_define_store_options_children(
                                options_obj=options_obj,
                                store_inner=inner,
                                store_qual=qual,
                            )

                        node_dict: Dict[str, Any] = {
                            "name": f"{EMOJI_FUNC} {decl_kind} {var_name}",
                            "priority": priority_counter[0],
                            "note": note_text,
                            "children": children_local,
                            "ast_type": f"{decl_kind}_decl",
                            "ast_name": var_name,
                            "ast_qualname": qual,
                            "file_path": file_path,
                            "orig_lineno_start_unused": start_line_abs,
                            "orig_lineno_end_unused": end_line_abs,
                        }
                        priority_counter[0] += 100
                        results.append(node_dict)

                    continue

                # Recurse into other nodes to discover nested declarations.
                #
                # IMPORTANT: anonymous function scopes (arrow/function expressions)
                # can contain local declarations with repeated names (e.g. two
                # separate callbacks each declaring `const tintOpts`). If we recurse
                # with the same qual_prefix, those locals collide on AST_QUALNAME.
                #
                # We therefore derive a deterministic pseudo-scope suffix from source
                # coordinates for function-like anonymous scopes.
                next_prefix = qual_prefix
                next_scope_state = scope_state
                if t in {"arrow_function", "function", "function_expression"}:
                    anon_scope = _js_next_anonymous_scope_name(scope_state)
                    next_prefix = f"{qual_prefix}.{anon_scope}" if qual_prefix else anon_scope
                    next_scope_state = _new_js_scope_state(is_lambda=True)

                if child.children:
                    results.extend(walk(child, qual_prefix=next_prefix, scope_state=next_scope_state))

            return results

        return walk(root)

    except Exception as e:  # pragma: no cover
        return [{
            "name": _warn_name("⚠️ Parse Error (VUE script JS/TS)"),
            "note": str(e),
            "children": [],
        }]


# @beacon[
#   id=auto-beacon@parse_vue_outline,
#   role=parse_vue_outline,
#   slice_labels=carto-js-ts,ra-snippet-range-ast-js-ts,
#   kind=ast,
# ]
def parse_vue_outline(file_path: str) -> List[Dict[str, Any]]:
    """Parse a Vue SFC (.vue) file into deterministic section subnodes.

    Structure:
      - ⦿ <template ...>  (span beacons only, MVP)
      - ⦿ <script ...> / <script setup ...> (AST + span beacons)
      - ⦿ <style ...> (span beacons only, MVP)

    Script AST nodes are built by running the existing JS/TS outline builder
    against the extracted script raw_text, then rebasing line numbers back
    into the .vue file.
    """
    if not _HAVE_TREE_SITTER:
        return [{
            "name": _warn_name("⚠️ Vue parsing not available"),
            "note": (
                "Tree-sitter / tree_sitter_language_pack could not be imported. "
                "Install 'tree_sitter' and 'tree_sitter-language-pack' "
                "in the Windows Python environment to enable .vue Cartographer support."
            ),
            "children": [],
        }]

    try:
        with open(file_path, "r", encoding="utf-8") as f:
            source_text = f.read()
    except Exception as e:  # noqa: BLE001
        return [{
            "name": _warn_name("⚠️ Parse Error (VUE)"),
            "note": f"failed_to_read_file: {e}",
            "children": [],
        }]

    source_bytes = source_text.encode("utf-8")
    file_lines = source_text.splitlines()

    try:
        parser = Parser()
        parser.language = get_language("vue")  # type: ignore[operator]
        tree = parser.parse(source_bytes)
        root = tree.root_node
    except Exception as e:  # pragma: no cover
        return [{
            "name": _warn_name("⚠️ Parse Error (VUE)"),
            "note": str(e),
            "children": [],
        }]

    # Collect top-level SFC blocks in order of appearance.
    blocks: list[dict[str, Any]] = []
    for ch in root.children:
        if ch.type not in {"template_element", "script_element", "style_element"}:
            continue

        start_tag = None
        raw_text = None
        end_tag = None
        for c2 in ch.children:
            if c2.type == "start_tag":
                start_tag = c2
            elif c2.type == "raw_text":
                raw_text = c2
            elif c2.type == "end_tag":
                end_tag = c2

        if start_tag is None:
            continue

        start_tag_text = source_bytes[start_tag.start_byte:start_tag.end_byte].decode("utf-8", errors="ignore")
        start_tag_compact = _vue_compact_start_tag_text(start_tag_text)

        # Extract content bytes.
        if raw_text is not None:
            # script/style blocks: raw_text is present.
            content_row0 = int(raw_text.start_point[0])
            content_text = source_bytes[raw_text.start_byte:raw_text.end_byte].decode("utf-8", errors="ignore")
        else:
            # template blocks: Vue grammar expands inner HTML into child nodes.
            if end_tag is None:
                continue
            content_row0 = int(start_tag.end_point[0])
            content_text = source_bytes[start_tag.end_byte:end_tag.start_byte].decode("utf-8", errors="ignore")

        blocks.append({
            "type": ch.type,
            "start_tag": start_tag_compact,
            "content_row0": content_row0,
            "raw_text": content_text,
        })

    # Build section nodes.
    out_nodes: list[dict[str, Any]] = []
    priority = 100

    script_ix = 0
    style_ix = 0

    for blk in blocks:
        btype = blk.get("type")
        start_tag_compact = str(blk.get("start_tag") or "").strip() or "<unknown>"
        raw_text_str = str(blk.get("raw_text") or "")
        content_row0 = int(blk.get("content_row0") or 0)

        # Section node
        # NOTE: Workflowy treats '<...>' as tag-like markup and may render it as blank.
        # Use square brackets to ensure section headings are visible.
        display_tag = start_tag_compact.replace("<", "[").replace(">", "]")
        section_name = f"⦿ {display_tag}"
        section_note_lines = [
            f"VUE_SECTION: {btype}",
            f"VUE_START_TAG: {start_tag_compact}",
            f"VUE_CONTENT_ROW0: {content_row0}",
        ]

        section_children: list[dict[str, Any]] = []

        if btype == "template_element":
            # Template: HTML-comment beacons (Markdown-style) as SPAN nodes.
            try:
                local_lines = raw_text_str.splitlines()
                beacons_local = parse_markdown_beacon_blocks(local_lines)
                beacons_abs = _vue_rebase_beacons(beacons_local, content_row0)
            except Exception:
                beacons_abs = []

            for b in beacons_abs:
                if (b.get("kind") or "").strip().lower() != "span":
                    continue
                bid = (b.get("id") or "").strip()
                role = (b.get("role") or "").strip() or (bid.split("@", 1)[0] if "@" in bid else "")
                slice_labels = _canonicalize_slice_labels((b.get("slice_labels") or "").strip(), role)
                show_span, show_span_explicit = _beacon_show_span(b)

                tag_suffix = _slice_label_tags(slice_labels)
                name = f"🔱 {role or bid or 'vue-template-span'}"
                if tag_suffix:
                    name = f"{name} {tag_suffix}"

                note_lines = [
                    "BEACON (VUE TEMPLATE SPAN)",
                    f"id: {bid}",
                    f"role: {role}",
                    f"slice_labels: {slice_labels}",
                    "kind: span",
                ]
                if show_span_explicit:
                    note_lines.append(f"show_span: {'true' if show_span else 'false'}")
                comment = b.get("comment")
                if comment:
                    note_lines.append(f"comment: {comment}")

                span_node = {"name": name, "note": "\n".join(note_lines), "children": []}
                section_children.append(span_node)

        elif btype == "script_element":
            # Determine language for this script block (ts/tsx vs js).
            lang = "javascript"
            start_tag_low = start_tag_compact.lower()
            if "lang=\"ts\"" in start_tag_low or "lang='ts'" in start_tag_low or "lang=ts" in start_tag_low:
                lang = "typescript"
            if "lang=\"tsx\"" in start_tag_low or "lang='tsx'" in start_tag_low or "lang=tsx" in start_tag_low:
                lang = "tsx"

            vue_prefix = f"vue:script{script_ix}"
            section_note_lines.append(f"VUE_SCRIPT_INDEX: {script_ix}")
            section_note_lines.append(f"VUE_SCRIPT_LANG: {lang}")

            outline_nodes = _parse_js_ts_outline_from_source(
                source_text=raw_text_str,
                file_path=file_path,
                language_name=lang,
                line_offset0=content_row0,
                vue_qual_prefix=vue_prefix,
            )

            # Attach JS/TS beacons inside this script block.
            try:
                local_lines = raw_text_str.splitlines()
                beacons_local = parse_js_beacon_blocks(local_lines)
                beacons_abs = _vue_rebase_beacons(beacons_local, content_row0)
                apply_js_beacons(file_path, file_lines, outline_nodes, beacons_abs)
            except Exception:
                pass

            section_children.extend(outline_nodes)
            script_ix += 1

        elif btype == "style_element":
            section_note_lines.append(f"VUE_STYLE_INDEX: {style_ix}")

            # Style: CSS comment beacons (block-comment syntax) treated as span-only.
            try:
                local_lines = raw_text_str.splitlines()
                beacons_local = parse_js_beacon_blocks(local_lines)
                beacons_abs = _vue_rebase_beacons(beacons_local, content_row0)
            except Exception:
                beacons_abs = []

            for b in beacons_abs:
                if (b.get("kind") or "").strip().lower() != "span":
                    continue
                bid = (b.get("id") or "").strip()
                role = (b.get("role") or "").strip() or (bid.split("@", 1)[0] if "@" in bid else "")
                slice_labels = _canonicalize_slice_labels((b.get("slice_labels") or "").strip(), role)
                show_span, show_span_explicit = _beacon_show_span(b)

                tag_suffix = _slice_label_tags(slice_labels)
                name = f"🔱 {role or bid or 'vue-style-span'}"
                if tag_suffix:
                    name = f"{name} {tag_suffix}"

                note_lines = [
                    "BEACON (VUE STYLE SPAN)",
                    f"id: {bid}",
                    f"role: {role}",
                    f"slice_labels: {slice_labels}",
                    "kind: span",
                ]
                if show_span_explicit:
                    note_lines.append(f"show_span: {'true' if show_span else 'false'}")
                comment = b.get("comment")
                if comment:
                    note_lines.append(f"comment: {comment}")

                span_node = {"name": name, "note": "\n".join(note_lines), "children": []}
                section_children.append(span_node)

            style_ix += 1

        # Default: section node
        out_nodes.append(
            {
                "name": section_name,
                "priority": priority,
                "note": "\n".join(section_note_lines),
                "children": section_children,
            }
        )
        priority += 100

    return out_nodes


# @beacon-close[
#   id=nmcv1@parser-and-outline-core,
# ]
# SPLIT BOUNDARY:
# Full recursive codebase initialization is valuable and may still belong in Core,
# but if the minimal public surface must shrink, the parsers and F12/update helpers
# matter more than exposing this full directory-walk entrypoint directly.
# @beacon[
#   id=nmcv1@recursive-map-boundary,
#   role=boundary split: full recursive codebase mapping and initialization entrypoint,
#   slice_labels=nexus-portability,nexus-split-boundary,
#   kind=span,
#   show_span=false,
# ]
# @beacon[
#   id=auto-beacon@map_codebase,
#   role=map_codebase,
#   slice_labels=carto-js-ts,f9-f12-handlers,
#   kind=ast,
# ]
# Phase 1 JS/TS: directory + single-file dispatcher. This will be extended
# to call the JS/TS outline builder (parse_js_ts_outline) for .js/.ts/.tsx
# files alongside parse_file_outline for Python.
def map_codebase(
    root_path: str,
    include_exts: List[str] = None,
    exclude_patterns: List[str] = None,
    *,
    repo_root: str | None = None,
) -> Dict[str, Any]:
    """
    Wraps the inner file parsing into a directory walker.
    Returns a single root NEXUS node representing the codebase tree.

    NOTE: This function is used to initialize a Cartographer codebase map
    via MCP tool calls, but this full-codebase mapping is not considered
    part of the minimal NEXUS Core v1 surface. It remains here for
    convenience and advanced workflows.
    """

    # Load .nexusignore patterns (optional) with ancestor walk.
    #
    # Semantics:
    # - Start at root_path (directory mapping root).
    # - Walk upward, loading any .nexusignore files found.
    # - Stop when we reach repo_root (when provided) or the filesystem root.
    #
    # Patterns are basename-only globs (no path separators).
    ignore_patterns: List[str] | None = None
    ignore_sources: List[str] = []

    # @beacon[
    #   id=auto-beacon@map_codebase._collect_nexusignore_patterns-3h3e,
    #   role=map_codebase._collect_nexusignore_patterns,
    #   slice_labels=f9-f12-handlers,
    #   kind=ast,
    # ]
    def _collect_nexusignore_patterns(
        *,
        start_dir: str,
        stop_dir: str | None,
    ) -> tuple[List[str], List[str]]:
        patterns_out: List[str] = []
        sources_out: List[str] = []

        cur = os.path.normpath(start_dir)
        stop_norm = os.path.normcase(os.path.normpath(stop_dir)) if stop_dir else None

        visited: set[str] = set()
        while cur and cur not in visited:
            visited.add(cur)

            ig_path = os.path.join(cur, ".nexusignore")
            if os.path.isfile(ig_path):
                sources_out.append(ig_path)
                invalid: List[str] = []
                with open(ig_path, "r", encoding="utf-8") as ig:
                    for line in ig:
                        raw = line.rstrip("\n\r")
                        stripped = raw.strip()
                        if not stripped or stripped.startswith("#"):
                            continue
                        if "/" in stripped or "\\" in stripped:
                            invalid.append(stripped)
                            continue
                        patterns_out.append(stripped)

                if invalid:
                    print(
                        "[NEXUS MAP] Ignoring .nexusignore patterns with path separators in "
                        f"{ig_path!r}: {invalid!r}",
                        file=sys.stderr,
                    )

            if stop_norm and os.path.normcase(cur) == stop_norm:
                break

            parent = os.path.dirname(cur)
            if not parent or parent == cur:
                break
            cur = parent

        # De-dupe while preserving order
        seen: set[str] = set()
        deduped: List[str] = []
        for p in patterns_out:
            if p not in seen:
                seen.add(p)
                deduped.append(p)

        return (deduped, sources_out)

    try:
        start_dir = root_path if os.path.isdir(root_path) else os.path.dirname(root_path)
        if start_dir and os.path.isdir(start_dir):
            ignore_patterns, ignore_sources = _collect_nexusignore_patterns(
                start_dir=str(start_dir),
                stop_dir=str(repo_root) if repo_root else None,
            )
            if ignore_patterns:
                print(
                    f"[NEXUS MAP] Using .nexusignore patterns={ignore_patterns!r} from sources={ignore_sources!r}",
                    file=sys.stderr,
                )
            else:
                ignore_patterns = None
    except Exception as e:  # pragma: no cover - safety net
        print(
            f"[NEXUS MAP] Failed to discover .nexusignore via ancestor walk from {root_path!r}: {e}",
            file=sys.stderr,
        )
        ignore_patterns = None

    def _is_ignored_name(name: str) -> bool:
        if name == "__pycache__":
            return True
        if not ignore_patterns:
            return False
        # Simple fnmatch-style globbing over basenames (no path semantics).
        import fnmatch

        for pat in ignore_patterns:
            if fnmatch.fnmatch(name, pat):
                return True
        return False

    # Portability: descendant FILE/FOLDER nodes should usually store relative Path:
    # values. When repo_root is supplied, we use it; otherwise, for directory maps
    # we default to root_path as the note root.
    repo_root_for_notes: str | None = None
    if repo_root and isinstance(repo_root, str):
        repo_root_for_notes = repo_root
    elif os.path.isdir(root_path):
        repo_root_for_notes = root_path

    # @beacon[
    #   id=auto-beacon@map_codebase.should_include-td2v,
    #   role=map_codebase.should_include,
    #   slice_labels=f9-f12-handlers,
    #   kind=ast,
    # ]
    def should_include(name: str) -> bool:
        if exclude_patterns:
            for pat in exclude_patterns:
                if pat in name:
                    return False

        if _is_ignored_name(name):
            return False

        # If include list is provided, must match extension (files only)
        if include_exts:
            _, ext = os.path.splitext(name)
            if ext.lower() not in include_exts:
                return False
        return True

    # @beacon[
    #   id=auto-beacon@map_codebase.scan_dir-k123,
    #   role=map_codebase.scan_dir,
    #   slice_labels=f9-f12-handlers,
    #   kind=ast,
    # ]
    def scan_dir(current_path: str) -> List[Dict[str, Any]]:
        nodes = []
        try:
            items = sorted(os.listdir(current_path))
            for item in items:
                full_path = os.path.join(current_path, item)

                # Ignore hidden/system dirs
                if item.startswith('.') or item == "__pycache__":
                    continue

                # Apply .nexusignore semantics (directories and files)
                if _is_ignored_name(item):
                    continue

                if exclude_patterns and any(pat in item for pat in exclude_patterns):
                    continue

                if os.path.isdir(full_path):
                    # Directories are filtered only by exclude_patterns and .nexusignore;
                    # include_exts apply to files, not folders.
                    children = scan_dir(full_path)
                    if children:  # Only add non-empty directories
                        folder_note = format_file_note(full_path, repo_root=repo_root_for_notes)
                        nodes.append({
                            "name": f"{EMOJI_FOLDER} {item}",
                            "note": folder_note,
                            "children": children,
                        })

                elif os.path.isfile(full_path):
                    # Extension Check for files only
                    _, ext = os.path.splitext(item)
                    ext = ext.lower()

                    if include_exts and ext not in include_exts:
                        continue

                    # Dispatch
                    line_count: Optional[int] = None
                    if ext == '.py':
                        icon = EMOJI_PYTHON
                        children = parse_file_outline(full_path)
                        line_count = _get_line_count(full_path)
                    elif ext == '.md':
                        icon = EMOJI_MARKDOWN
                        children = parse_markdown_structure(full_path)
                        line_count = _get_line_count(full_path)
                    elif ext in {'.js', '.jsx'}:
                        icon = EMOJI_JS
                        children = parse_js_ts_outline(full_path)
                        line_count = _get_line_count(full_path)
                    elif ext in {'.ts', '.tsx'}:
                        icon = EMOJI_TS
                        children = parse_js_ts_outline(full_path)
                        line_count = _get_line_count(full_path)
                    elif ext == '.vue':
                        icon = EMOJI_VUE
                        children = parse_vue_outline(full_path)
                        line_count = _get_line_count(full_path)
                    elif ext == '.sql':
                        icon = EMOJI_SQL
                        with open(full_path, 'r', encoding='utf-8') as f:
                            sql_lines = f.read().splitlines()
                        line_count = len(sql_lines)
                        children: List[Dict[str, Any]] = []
                        sql_beacons = parse_sql_beacon_blocks(sql_lines)
                        apply_sql_beacons(sql_lines, children, sql_beacons)
                    elif ext == '.sh':
                        icon = EMOJI_SHELL
                        with open(full_path, 'r', encoding='utf-8') as f:
                            sh_lines = f.read().splitlines()
                        line_count = len(sh_lines)
                        children = []
                        sh_beacons = parse_sh_beacon_blocks(sh_lines)
                        apply_sh_beacons(sh_lines, children, sh_beacons)
                    else:
                        icon = EMOJI_FILE
                        children = []  # Generic file = Leaf node
                        line_count = _get_line_count(full_path)

                    note = format_file_note(full_path, line_count=line_count, repo_root=repo_root_for_notes)

                    nodes.append({
                        "name": f"{icon} {item}",
                        "note": note,
                        "children": children,
                    })

        except Exception as e:
            print(f"Error scanning {current_path}: {e}")

        return nodes

    root_name = os.path.basename(root_path) or "Source Code"
    if os.path.isfile(root_path):
        # Single file mode dispatch
        _, ext = os.path.splitext(root_path)
        ext = ext.lower()
        if ext == '.py':
            children = parse_file_outline(root_path)
            lc = _get_line_count(root_path)
            note = format_file_note(root_path, line_count=lc, repo_root=repo_root_for_notes)
            return {
                "name": f"{EMOJI_PYTHON} {os.path.basename(root_path)}",
                "note": note,
                "children": children
            }
        elif ext == '.md':
            children = parse_markdown_structure(root_path)
            lc = _get_line_count(root_path)
            note = format_file_note(root_path, line_count=lc, repo_root=repo_root_for_notes)
            return {
                "name": f"{EMOJI_MARKDOWN} {os.path.basename(root_path)}",
                "note": note,
                "children": children
            }
        elif ext in ('.js', '.jsx'):
            children = parse_js_ts_outline(root_path)
            lc = _get_line_count(root_path)
            note = format_file_note(root_path, line_count=lc, repo_root=repo_root_for_notes)
            return {
                "name": f"{EMOJI_JS} {os.path.basename(root_path)}",
                "note": note,
                "children": children,
            }
        elif ext in ('.ts', '.tsx'):
            children = parse_js_ts_outline(root_path)
            lc = _get_line_count(root_path)
            note = format_file_note(root_path, line_count=lc, repo_root=repo_root_for_notes)
            return {
                "name": f"{EMOJI_TS} {os.path.basename(root_path)}",
                "note": note,
                "children": children,
            }
        elif ext == '.vue':
            children = parse_vue_outline(root_path)
            lc = _get_line_count(root_path)
            note = format_file_note(root_path, line_count=lc, repo_root=repo_root_for_notes)
            return {
                "name": f"{EMOJI_VUE} {os.path.basename(root_path)}",
                "note": note,
                "children": children,
            }
        elif ext == '.sql':
            with open(root_path, 'r', encoding='utf-8') as f:
                sql_lines = f.read().splitlines()
            children: List[Dict[str, Any]] = []
            sql_beacons = parse_sql_beacon_blocks(sql_lines)
            apply_sql_beacons(sql_lines, children, sql_beacons)
            note = format_file_note(root_path, line_count=len(sql_lines), repo_root=repo_root_for_notes)
            return {
                "name": f"{EMOJI_SQL} {os.path.basename(root_path)}",
                "note": note,
                "children": children,
            }
        elif ext == '.sh':
            with open(root_path, 'r', encoding='utf-8') as f:
                sh_lines = f.read().splitlines()
            children: List[Dict[str, Any]] = []
            sh_beacons = parse_sh_beacon_blocks(sh_lines)
            apply_sh_beacons(sh_lines, children, sh_beacons)
            note = format_file_note(root_path, line_count=len(sh_lines), repo_root=repo_root_for_notes)
            return {
                "name": f"{EMOJI_SHELL} {os.path.basename(root_path)}",
                "note": note,
                "children": children,
            }
        elif ext in ('.yml', '.yaml'):
            with open(root_path, 'r', encoding='utf-8') as f:
                yml_lines = f.read().splitlines()
            children: List[Dict[str, Any]] = []
            yml_beacons = parse_yaml_beacon_blocks(yml_lines)
            apply_yaml_beacons(yml_lines, children, yml_beacons)
            note = format_file_note(root_path, line_count=len(yml_lines), repo_root=repo_root_for_notes)
            return {
                "name": f"{EMOJI_FILE} {os.path.basename(root_path)}",
                "note": note,
                "children": children,
            }
        else:
             lc = _get_line_count(root_path)
             note = format_file_note(root_path, line_count=lc, repo_root=repo_root_for_notes)
             return {
                "name": f"{EMOJI_FILE} {os.path.basename(root_path)}",
                "note": note,
                "children": []
            }
    
    # Directory mode
    return {
        "name": f"🗺️ Source Map: {root_name}",
        "note": f"Root: {repo_root_for_notes or root_path}",
        "children": scan_dir(root_path)
    }

# @beacon-close[
#   id=nmcv1@recursive-map-boundary,
# ]
# CORE V1 KEEPER:
# Multi-language beacon parsers plus update_beacon_from_node_* helpers are a core
# part of the F12 experience. Keep these with Cartographer so per-node beacon edits
# remain language-aware and machine-portable.
# @beacon[
#   id=nmcv1@multilang-update-core,
#   role=core keeper: multi-language beacon parsing and update-from-node helpers,
#   slice_labels=nexus-portability,nexus-core-v1,
#   kind=span,
#   show_span=false,
# ]
# @beacon[
#   id=auto-beacon@parse_sql_beacon_blocks-xpb1,
#   role=parse_sql_beacon_blocks,
#   slice_labels=ra-reconcile,f9-f12-handlers,
#   kind=ast,
# ]
def parse_sql_beacon_blocks(lines: list[str]) -> list[dict[str, Any]]:
    """Parse @beacon[...] comment blocks from SQL source lines.

    Syntax (mirrors Python/Markdown beacons):

        -- @beacon[
        --   id=segment@001,
        --   role=query:fraud_filter,   # optional
        --   slice_labels=QUERY-FRAUD,  # optional
        --   kind=span,                 # optional, defaults to span
        -- ]

    All metadata fields are optional except id; defaults are applied later.
    """
    beacons: list[dict[str, Any]] = []
    i = 0
    n = len(lines)
    while i < n:
        line = lines[i]
        stripped = line.lstrip()
        if stripped.startswith("--"):
            body = stripped.lstrip("-").lstrip()
            if body.startswith("@beacon["):
                comment_line = i + 1  # 1-based
                block_lines = [body]
                i += 1
                # Collect until a line containing ']' (inclusive)
                while i < n:
                    next_line = lines[i].lstrip()
                    if next_line.startswith("--"):
                        next_body = next_line.lstrip("-").lstrip()
                    else:
                        next_body = next_line
                    block_lines.append(next_body)
                    # Close only when the metadata delimiter line begins with ']'.
                    # This avoids premature termination when a value contains a stray ']'.
                    if next_body.strip().startswith("]"):
                        i += 1
                        break
                    i += 1

                # Parse block_lines into key/value pairs (skip first/last structural lines)
                fields: dict[str, str] = {}
                inner_lines = block_lines[1:-1] if len(block_lines) >= 2 else []
                for raw in inner_lines:
                    text = raw.strip()
                    if not text or text.startswith("@beacon"):
                        continue
                    # Drop trailing ',' or '],' or ']'
                    while text and text[-1] in ",]":
                        text = text[:-1].rstrip()
                    if not text:
                        continue
                    if "=" not in text:
                        continue
                    key, val = text.split("=", 1)
                    key = key.strip()
                    val = val.strip()
                    # Strip surrounding quotes if present
                    if (val.startswith("\"") and val.endswith("\"")) or (
                        val.startswith("'") and val.endswith("'")
                    ):
                        val = val[1:-1]
                    fields[key] = val

                kind = (fields.get("kind") or "span").strip().lower() or "span"
                if kind not in {"ast", "span"}:
                    # Unknown/unsupported kind – skip silently for now
                    continue

                show_span, show_span_explicit = _parse_show_span_fields(fields)

                beacon = {
                    "id": fields.get("id"),
                    "role": fields.get("role"),
                    "slice_labels": fields.get("slice_labels"),
                    "kind": kind,
                    "start_snippet": fields.get("start_snippet"),
                    "end_snippet": fields.get("end_snippet"),
                    "comment": (fields.get("comment") if fields.get("comment") not in (None, "") else fields.get("comments")),
                    "comment_line": comment_line,
                    "show_span": show_span,
                    "show_span_explicit": show_span_explicit,
                }
                beacons.append(beacon)
                continue
        i += 1

    # Second pass: compute span ranges for SQL span beacons
    for beacon in beacons:
        if beacon.get("kind") != "span":
            continue

        b_id = (beacon.get("id") or "").strip()
        if not b_id:
            continue

        comment_line = beacon.get("comment_line")
        if not isinstance(comment_line, int) or not (1 <= comment_line <= n):
            continue

        # Find end of opener's metadata block (first line containing ']')
        j = comment_line
        open_end = comment_line
        while j <= n:
            raw = lines[j - 1].lstrip()
            if raw.startswith("--"):
                body = raw.lstrip("-").lstrip()
            else:
                body = raw
            if body.strip().startswith("]"):
                open_end = j
                break
            j += 1

        # Scan forward for matching @beacon-close[...] with same id
        close_comment_line = None
        k = open_end + 1
        while k <= n:
            raw = lines[k - 1].lstrip()
            if raw.startswith("--"):
                body = raw.lstrip("-").lstrip()
            else:
                body = raw

            if "@beacon-close[" in body:
                # Collect full close block (may span multiple lines)
                close_lines = [body]
                k += 1
                while k <= n:
                    next_raw = lines[k - 1].lstrip()
                    if next_raw.startswith("--"):
                        next_body = next_raw.lstrip("-").lstrip()
                    else:
                        next_body = next_raw
                    close_lines.append(next_body)
                    if next_body.strip().startswith("]"):
                        k += 1
                        break
                    k += 1

                # Extract id from close block
                close_id = None
                for cl in close_lines:
                    cl = cl.strip()
                    if cl.startswith("id="):
                        close_id = cl.split("=", 1)[1].strip().strip(",").strip("]")
                        break

                if close_id == b_id:
                    # Line where @beacon-close[...] started
                    close_comment_line = k - len(close_lines)
                    break

            k += 1

        if close_comment_line is not None:
            inner_start = open_end + 1
            inner_end = close_comment_line - 1
            if inner_start <= inner_end:
                beacon["span_lineno_start"] = inner_start
                beacon["span_lineno_end"] = inner_end

    return beacons


# @beacon[
#   id=carto-js-ts@parse_js_beacon_blocks,
#   role=carto-js-ts,
#   slice_labels=carto-js-ts,carto-js-ts-beacons,f9-f12-handlers,ra-reconcile,
#   kind=span,
# ]
# Phase 2 JS/TS: JS/TS beacon parser.
# Supports both line-comment (//) and block-comment (/* ... */) forms
# with the same metadata schema as Python/Markdown beacons.
def parse_js_beacon_blocks(lines: list[str]) -> list[dict[str, Any]]:
    """Parse @beacon[...] comment blocks from JS/TS source lines.

    Supported forms (we control this schema):

        // @beacon[
        //   id=feature@1234,
        //   role=glimpse:refresh,
        //   slice_labels=glimpse-extension,
        //   kind=ast|span,
        //   start_snippet="function handleRefresh(",
        //   end_snippet="}",
        //   comment=One-line human note,
        // ]

        /* @beacon[
           id=feature@1234,
           slice_labels=glimpse-extension,
           kind=ast,
         ] */

    Returns a list of dicts with keys:
        id, role, slice_labels, kind, start_snippet, end_snippet,
        comment, comment_line, kind_explicit.
    """
    beacons: list[dict[str, Any]] = []
    n = len(lines)
    i = 0

    def _strip_js_comment_sugar(text: str) -> str:
        t = text.lstrip()
        # Leading JS comment prefixes
        if t.startswith("//"):
            t = t[2:].lstrip()
        if t.startswith("/*"):
            t = t[2:].lstrip()
        if t.startswith("*/"):
            t = t[2:].lstrip()
        if t.startswith("*"):
            t = t[1:].lstrip()
        # Trailing block-comment closer
        if t.endswith("*/"):
            t = t[:-2].rstrip()
        return t

    while i < n:
        line = lines[i]
        if "@beacon[" in line:
            comment_line = i + 1  # 1-based
            block_lines = [line]
            i += 1
            # Collect until a line containing ']' (inclusive)
            while i < n:
                block_lines.append(lines[i])
                if "]" in lines[i]:
                    i += 1
                    break
                i += 1

            # Parse block_lines into key/value pairs (skip first/last structural lines)
            fields: dict[str, str] = {}
            inner_lines = block_lines[1:-1] if len(block_lines) >= 2 else []
            for raw in inner_lines:
                text = raw.strip()
                if not text:
                    continue
                text = _strip_js_comment_sugar(text)
                if not text or text.startswith("@beacon"):
                    continue
                # Drop trailing ',' or '],' or ']'
                while text and text[-1] in ",]":
                    text = text[:-1].rstrip()
                if not text or "=" not in text:
                    continue
                key, val = text.split("=", 1)
                key = key.strip()
                val = val.strip()
                # Strip surrounding quotes if present
                if (val.startswith("\"") and val.endswith("\"")) or (
                    val.startswith("'") and val.endswith("'")
                ):
                    val = val[1:-1]
                fields[key] = val

            kind_raw = fields.get("kind")
            kind = (kind_raw or "span").strip().lower() or "span"
            if kind not in {"ast", "span"}:
                continue

            show_span, show_span_explicit = _parse_show_span_fields(fields)

            beacon = {
                "id": fields.get("id"),
                "role": fields.get("role"),
                "slice_labels": fields.get("slice_labels"),
                "kind": kind,
                "start_snippet": fields.get("start_snippet"),
                "end_snippet": fields.get("end_snippet"),
                "comment": (fields.get("comment") if fields.get("comment") not in (None, "") else fields.get("comments")),
                "comment_line": comment_line,
                "kind_explicit": bool(kind_raw),
                "show_span": show_span,
                "show_span_explicit": show_span_explicit,
            }
            beacons.append(beacon)
        else:
            i += 1

    # Second pass: compute span ranges for JS/TS span beacons using @beacon-close[...] by id.
    for beacon in beacons:
        if beacon.get("kind") != "span":
            continue

        # Only override when no span was previously set.
        if beacon.get("span_lineno_start") is not None and beacon.get("span_lineno_end") is not None:
            continue

        b_id = (beacon.get("id") or "").strip()
        if not b_id:
            continue

        comment_line = beacon.get("comment_line")
        if not isinstance(comment_line, int) or not (1 <= comment_line <= n):
            continue

        # Find end of opener's metadata block (first line containing ']')
        j = comment_line
        open_end = comment_line
        while j <= n:
            raw = lines[j - 1]
            body = _strip_js_comment_sugar(raw)
            if body.strip().startswith("]"):
                open_end = j
                break
            j += 1

        # Scan forward for matching @beacon-close[...] with same id
        close_comment_line = None
        k = open_end + 1
        while k <= n:
            raw = lines[k - 1]
            body = _strip_js_comment_sugar(raw)
            if "@beacon-close[" in body:
                close_lines = [body]
                k += 1
                while k <= n:
                    next_raw = lines[k - 1]
                    next_body = _strip_js_comment_sugar(next_raw)
                    close_lines.append(next_body)
                    if next_body.strip().startswith("]"):
                        k += 1
                        break
                    k += 1

                close_id = None
                for cl in close_lines:
                    text = cl.strip()
                    # Drop trailing ',' and ']'
                    while text and text[-1] in ",]":
                        text = text[:-1].rstrip()
                    if text.startswith("id="):
                        _, val = text.split("=", 1)
                        close_id = val.strip()
                        break

                if close_id == b_id:
                    # Line where @beacon-close[...] started
                    close_comment_line = k - len(close_lines)
                    break

            k += 1

        if close_comment_line is not None:
            inner_start = open_end + 1
            inner_end = close_comment_line - 1
            if inner_start <= inner_end:
                beacon["span_lineno_start"] = inner_start
                beacon["span_lineno_end"] = inner_end

    return beacons


# @beacon[
#   id=carto-js-ts@parse_sh_beacon_blocks,
#   role=carto-js-ts,
#   slice_labels=carto-js-ts,carto-js-ts-beacons,ra-reconcile,f9-f12-handlers,
#   kind=span,
# ]
# Phase 2 JS/TS: shell beacon parser example.
# Another line-comment @beacon[...] parser useful for cross-checking
# JS/TS behavior.
def parse_sh_beacon_blocks(lines: list[str]) -> list[dict[str, Any]]:
    """Parse @beacon[...] blocks from shell scripts using '#'-style comments.

    Syntax mirrors the Python beacon form but is language-agnostic:

        # @beacon[
        #   id=segment@001,
        #   role=my:role,             # optional
        #   slice_labels=TAG1,TAG2,   # optional
        #   kind=span,                # optional, defaults to span
        # ]
    """
    beacons: list[dict[str, Any]] = []
    i = 0
    n = len(lines)
    while i < n:
        line = lines[i]
        stripped = line.lstrip()
        if stripped.startswith("#"):
            body = stripped.lstrip("#").lstrip()
            if body.startswith("@beacon["):
                comment_line = i + 1
                block_lines = [body]
                i += 1
                while i < n:
                    next_line = lines[i].lstrip()
                    if next_line.startswith("#"):
                        next_body = next_line.lstrip("#").lstrip()
                    else:
                        next_body = next_line
                    block_lines.append(next_body)
                    # Close only when the metadata delimiter line begins with ']'.
                    # This avoids premature termination when a value contains a stray ']'.
                    if next_body.strip().startswith("]"):
                        i += 1
                        break
                    i += 1

                fields: dict[str, str] = {}
                inner_lines = block_lines[1:-1] if len(block_lines) >= 2 else []
                for raw in inner_lines:
                    text = raw.strip()
                    if not text or text.startswith("@beacon"):
                        continue
                    while text and text[-1] in ",]":
                        text = text[:-1].rstrip()
                    if not text or "=" not in text:
                        continue
                    key, val = text.split("=", 1)
                    key = key.strip()
                    val = val.strip()
                    if (val.startswith("\"") and val.endswith("\"")) or (
                        val.startswith("'") and val.endswith("'")
                    ):
                        val = val[1:-1]
                    fields[key] = val

                kind = (fields.get("kind") or "span").strip().lower() or "span"
                if kind not in {"ast", "span"}:
                    continue

                show_span, show_span_explicit = _parse_show_span_fields(fields)

                beacon = {
                    "id": fields.get("id"),
                    "role": fields.get("role"),
                    "slice_labels": fields.get("slice_labels"),
                    "kind": kind,
                    "start_snippet": fields.get("start_snippet"),
                    "end_snippet": fields.get("end_snippet"),
                    "comment": (fields.get("comment") if fields.get("comment") not in (None, "") else fields.get("comments")),
                    "comment_line": comment_line,
                    "show_span": show_span,
                    "show_span_explicit": show_span_explicit,
                }
                beacons.append(beacon)
                continue
        i += 1

    # Second pass: compute span ranges for shell span beacons
    for beacon in beacons:
        if beacon.get("kind") != "span":
            continue

        b_id = (beacon.get("id") or "").strip()
        if not b_id:
            continue

        comment_line = beacon.get("comment_line")
        if not isinstance(comment_line, int) or not (1 <= comment_line <= n):
            continue

        # Find end of opener's metadata block (first line containing ']')
        j = comment_line
        open_end = comment_line
        while j <= n:
            raw = lines[j - 1].lstrip()
            if raw.startswith("#"):
                body = raw.lstrip("#").lstrip()
            else:
                body = raw
            if "]" in body:
                open_end = j
                break
            j += 1

        # Scan forward for matching @beacon-close[...] with same id
        close_comment_line = None
        k = open_end + 1
        while k <= n:
            raw = lines[k - 1].lstrip()
            if raw.startswith("#"):
                body = raw.lstrip("#").lstrip()
            else:
                body = raw

            if "@beacon-close[" in body:
                close_lines = [body]
                k += 1
                while k <= n:
                    next_raw = lines[k - 1].lstrip()
                    if next_raw.startswith("#"):
                        next_body = next_raw.lstrip("#").lstrip()
                    else:
                        next_body = next_raw
                    close_lines.append(next_body)
                    if next_body.strip().startswith("]"):
                        k += 1
                        break
                    k += 1

                close_id = None
                for cl in close_lines:
                    cl = cl.strip()
                    if cl.startswith("id="):
                        close_id = cl.split("=", 1)[1].strip().strip(",").strip("]")
                        break

                if close_id == b_id:
                    close_comment_line = k - len(close_lines)
                    break

            k += 1

        if close_comment_line is not None:
            inner_start = open_end + 1
            inner_end = close_comment_line - 1
            if inner_start <= inner_end:
                beacon["span_lineno_start"] = inner_start
                beacon["span_lineno_end"] = inner_end

    return beacons


# @beacon[
#   id=carto-js-ts@parse_yaml_beacon_blocks,
#   role=carto-js-ts,
#   slice_labels=carto-js-ts,carto-js-ts-beacons,ra-reconcile,f9-f12-handlers,
#   kind=span,
# ]
def parse_yaml_beacon_blocks(lines: list[str]) -> list[dict[str, Any]]:
    """Parse @beacon[...] blocks from YAML/Helm using '#'-style comments.

    Syntax mirrors the Python beacon form but is language-agnostic:

        # @beacon[
        #   id=segment@001,
        #   role=my:role,             # optional
        #   slice_labels=TAG1,TAG2,   # optional
        #   kind=span,                # optional, defaults to span
        # ]
    """
    beacons: list[dict[str, Any]] = []
    i = 0
    n = len(lines)
    while i < n:
        line = lines[i]
        stripped = line.lstrip()
        if stripped.startswith("#"):
            body = stripped.lstrip("#").lstrip()
            if body.startswith("@beacon["):
                comment_line = i + 1
                block_lines = [body]
                i += 1
                while i < n:
                    next_line = lines[i].lstrip()
                    if next_line.startswith("#"):
                        next_body = next_line.lstrip("#").lstrip()
                    else:
                        next_body = next_line
                    block_lines.append(next_body)
                    if "]" in next_body:
                        i += 1
                        break
                    i += 1

                fields: dict[str, str] = {}
                inner_lines = block_lines[1:-1] if len(block_lines) >= 2 else []
                for raw in inner_lines:
                    text = raw.strip()
                    if not text or text.startswith("@beacon"):
                        continue
                    while text and text[-1] in ",]":
                        text = text[:-1].rstrip()
                    if not text or "=" not in text:
                        continue
                    key, val = text.split("=", 1)
                    key = key.strip()
                    val = val.strip()
                    if (val.startswith("\"") and val.endswith("\"")) or (
                        val.startswith("'") and val.endswith("'")
                    ):
                        val = val[1:-1]
                    fields[key] = val

                kind = (fields.get("kind") or "span").strip().lower() or "span"
                if kind not in {"ast", "span"}:
                    continue

                show_span, show_span_explicit = _parse_show_span_fields(fields)

                beacon = {
                    "id": fields.get("id"),
                    "role": fields.get("role"),
                    "slice_labels": fields.get("slice_labels"),
                    "kind": kind,
                    "start_snippet": fields.get("start_snippet"),
                    "end_snippet": fields.get("end_snippet"),
                    "comment": (fields.get("comment") if fields.get("comment") not in (None, "") else fields.get("comments")),
                    "comment_line": comment_line,
                    "show_span": show_span,
                    "show_span_explicit": show_span_explicit,
                }
                beacons.append(beacon)
                continue
        i += 1

    # Second pass: compute span ranges for YAML span beacons
    for beacon in beacons:
        if beacon.get("kind") != "span":
            continue

        b_id = (beacon.get("id") or "").strip()
        if not b_id:
            continue

        comment_line = beacon.get("comment_line")
        if not isinstance(comment_line, int) or not (1 <= comment_line <= n):
            continue

        # Find end of opener's metadata block (first line containing ']')
        j = comment_line
        open_end = comment_line
        while j <= n:
            raw = lines[j - 1].lstrip()
            if raw.startswith("#"):
                body = raw.lstrip("#").lstrip()
            else:
                body = raw
            if "]" in body:
                open_end = j
                break
            j += 1

        # Scan forward for matching @beacon-close[...] with same id
        close_comment_line = None
        k = open_end + 1
        while k <= n:
            raw = lines[k - 1].lstrip()
            if raw.startswith("#"):
                body = raw.lstrip("#").lstrip()
            else:
                body = raw

            if "@beacon-close[" in body:
                close_lines = [body]
                k += 1
                while k <= n:
                    next_raw = lines[k - 1].lstrip()
                    if next_raw.startswith("#"):
                        next_body = next_raw.lstrip("#").lstrip()
                    else:
                        next_body = next_raw
                    close_lines.append(next_body)
                    if "]" in next_body:
                        k += 1
                        break
                    k += 1

                close_id = None
                for cl in close_lines:
                    cl = cl.strip()
                    if cl.startswith("id="):
                        close_id = cl.split("=", 1)[1].strip().strip(",").strip("]")
                        break

                if close_id == b_id:
                    close_comment_line = k - len(close_lines)
                    break

            k += 1

        if close_comment_line is not None:
            inner_start = open_end + 1
            inner_end = close_comment_line - 1
            if inner_start <= inner_end:
                beacon["span_lineno_start"] = inner_start
                beacon["span_lineno_end"] = inner_end

    return beacons


# @beacon[
#   id=auto-beacon@_extract_sql_beacon_context-9w82,
#   role=_extract_sql_beacon_context,
#   slice_labels=ra-reconcile,f9-f12-handlers,ra-reconcile,
#   kind=ast,
# ]
def _extract_sql_beacon_context(
    lines: list[str],
    comment_line: int,
    beacon_id: Optional[str] = None,
) -> List[str]:
    """Extract nearby SQL comments (non-beacon) around a SQL beacon.
    This populates the "CONTEXT COMMENTS (SQL)" section of Workflowy notes.

    Includes:
    - Lines that are part of a line comment starting with '--'
    - Lines that are part of a block comment /* ... */ above/below the beacon
      (we treat the entire contiguous comment region as context).

    Excludes:
    - Any @beacon[...] / @beacon-close[...] delimiter blocks (and their metadata lines).
    Close-block semantics:
    - When encountering a @beacon-close block, treat it as the terminator ONLY if
      its id matches `beacon_id` (supports overlapping/nested span beacons).
    """
    context: List[str] = []

    n = len(lines)
    # @beacon[
    #   id=auto-beacon@_extract_sql_beacon_context._sql_body-lr4m,
    #   role=_extract_sql_beacon_context._sql_body,
    #   slice_labels=ra-reconcile,
    #   kind=ast,
    # ]
    def _sql_body(raw_line: str) -> str:
        s = raw_line.lstrip()
        if s.startswith("--"):
            return s[2:].lstrip()
        return s
    # @beacon[
    #   id=auto-beacon@_extract_sql_beacon_context._is_meta_block_end-y1eq,
    #   role=_extract_sql_beacon_context._is_meta_block_end,
    #   slice_labels=ra-reconcile,
    #   kind=ast,
    # ]
    def _is_meta_block_end(body: str) -> bool:
        return body.strip().startswith("]")

    # Precompute which lines are comment-like and a cleaned text version.
    # For block comments we treat every line between /* and */ (inclusive)
    # as comment-like, so that interior lines are visible in CONTEXT COMMENTS.
    comment_mask: list[bool] = [False] * n
    cleaned: list[str] = ["" for _ in range(n)]
    in_block = False

    for idx, raw in enumerate(lines, start=1):
        stripped = raw.lstrip()
        if not stripped:
            continue
        # Do not treat beacon delimiter blocks as human context.
        if "@beacon" in stripped:
            continue

        is_comment = False
        text = ""

        if not in_block:
            if stripped.startswith("--"):
                is_comment = True
                text = stripped[2:].lstrip()
            elif "/*" in stripped:
                is_comment = True
                in_block = True
                after = stripped.split("/*", 1)[1]
                if "*/" in after:
                    before_close, _ = after.split("*/", 1)
                    text = before_close.strip()
                    in_block = False
                else:
                    text = after.strip()
        else:
            # Inside a /* ... */ block
            is_comment = True
            if "*/" in stripped:
                before_close, _ = stripped.split("*/", 1)
                text = before_close.strip()
                in_block = False
            else:
                text = stripped

        if is_comment:
            comment_mask[idx - 1] = True
            cleaned[idx - 1] = text

    # Determine end of the beacon metadata block (similar to parse_sql_beacon_blocks)
    j = comment_line
    block_end = comment_line
    while j <= n:
        body = _sql_body(lines[j - 1])
        if _is_meta_block_end(body):
            block_end = j
            break
        j += 1

    # Above
    j = comment_line - 1
    while j >= 1:
        raw = lines[j - 1]
        if not raw.strip():
            j -= 1
            continue
        if comment_mask[j - 1]:
            if cleaned[j - 1]:
                context.insert(0, cleaned[j - 1])
            j -= 1
            continue
        break

    # Below
    j = block_end + 1
    while j <= n:
        raw = lines[j - 1]
        if not raw.strip():
            j += 1
            continue
        body = _sql_body(raw)
        # Skip nested beacon opener blocks entirely.
        if body.startswith("@beacon["):
            j += 1
            while j <= n:
                inner_body = _sql_body(lines[j - 1])
                if _is_meta_block_end(inner_body):
                    j += 1
                    break
                j += 1
            continue
        # Stop at a matching close block; ignore close blocks for other beacon ids.
        if body.startswith("@beacon-close["):
            close_id: Optional[str] = None
            j += 1
            while j <= n:
                inner_body = _sql_body(lines[j - 1]).strip()
                if inner_body.startswith("id=") and close_id is None:
                    close_id = inner_body.split("=", 1)[1].strip()
                    close_id = close_id.rstrip(",").rstrip("]").strip()
                if _is_meta_block_end(inner_body):
                    j += 1
                    break
                j += 1
            if beacon_id and close_id and close_id != beacon_id:
                continue
            break
        if comment_mask[j - 1]:
            if cleaned[j - 1]:
                context.append(cleaned[j - 1])
            j += 1
            continue
        break

    return _strip_beacon_meta_blocks_from_context(context)


# @beacon[
#   id=carto-js-ts@apply_sql_beacons,
#   role=carto-js-ts,
#   slice_labels=carto-js-ts,carto-js-ts-beacons,ra-reconcile,
#   kind=span,
# ]
# Phase 2 JS/TS: SQL beacon attachment example.
# Secondary template for attaching span-only beacons as children
# under a FILE node for non-AST languages.
def apply_sql_beacons(
    lines: list[str],
    file_children: List[Dict[str, Any]],
    beacons: list[dict[str, Any]],
) -> None:
    """Attach SQL span beacons as child nodes under the file node.

    For now, SQL beacons are purely location-centric annotations on the file.
    We do not compute or store explicit line ranges; future tools can re-scan
    the file to recover spans if needed.
    """
    if not beacons:
        return

    n = len(lines)
    _prepend_duplicate_beacon_id_warning_nodes(file_children, beacons, language="SQL")

    for beacon in beacons:
        if beacon.get("kind") != "span":
            continue

        b_id = (beacon.get("id") or "").strip()
        role = (beacon.get("role") or "").strip()
        raw_slice_labels = (beacon.get("slice_labels") or "").strip()

        # Defaults: derive role from id prefix (before '@')
        if not role and b_id and "@" in b_id:
            role = b_id.split("@", 1)[0]
        slice_labels = _canonicalize_slice_labels(raw_slice_labels, role)

        show_span, show_span_explicit = _beacon_show_span(beacon)

        display_role = role or b_id or "sql-span-beacon"
        display_slice = slice_labels or "-"

        tag_suffix = _slice_label_tags(slice_labels or display_slice)
        name = f"🔱 {display_role}"
        if tag_suffix:
            name = f"{name} {tag_suffix}"

        context_lines = _extract_sql_beacon_context(
            lines,
            beacon.get("comment_line") or 0,
            beacon_id=b_id,
        )
        comment = beacon.get("comment")

        note_lines = [
            "BEACON (SQL SPAN)",
            f"id: {b_id}",
            f"role: {role}",
            f"slice_labels: {slice_labels}",
            "kind: span",
        ]
        if show_span_explicit:
            note_lines.append(f"show_span: {'true' if show_span else 'false'}")
        if comment:
            note_lines.append(f"comment: {comment}")
        if context_lines:
            note_lines.append("")
            note_lines.append("CONTEXT COMMENTS (SQL):")
            note_lines.extend(context_lines)

        # Raw SQL span text between opener/closer (if Cartographer computed it)
        span_text_lines: List[str] = []
        span_start = beacon.get("span_lineno_start")
        span_end = beacon.get("span_lineno_end")
        if isinstance(span_start, int) and isinstance(span_end, int):
            span_start = max(1, span_start)
            span_end = min(n, span_end)
            if span_start <= span_end:
                span_text_lines = lines[span_start - 1 : span_end]
                # Trim leading/trailing blank lines inside the span
                while span_text_lines and not span_text_lines[0].strip():
                    span_text_lines.pop(0)
                while span_text_lines and not span_text_lines[-1].strip():
                    span_text_lines.pop()

        if show_span and span_text_lines:
            note_lines.append("")
            note_lines.append("SPAN TEXT:")
            note_lines.extend(span_text_lines)

        span_node = {
            "name": name,
            "note": "\n".join(note_lines),
            "children": [],
        }

        file_children.append(span_node)


# @beacon[
#   id=auto-beacon@_extract_sh_beacon_context-s7r8,
#   role=_extract_sh_beacon_context,
#   slice_labels=ra-reconcile,f9-f12-handlers,ra-reconcile,
#   kind=ast,
# ]
def _extract_sh_beacon_context(
    lines: list[str],
    comment_line: int,
    beacon_id: Optional[str] = None,
) -> List[str]:
    """Extract nearby shell comments (non-beacon) around a shell @beacon block.
    This populates the "CONTEXT COMMENTS (SH)" section of Workflowy notes.
    Rules:
    - Never include any @beacon[...] / @beacon-close[...] delimiter blocks (or their metadata lines).
    - When encountering a @beacon-close block, treat it as the terminator ONLY if its id matches
      `beacon_id` (supports overlapping/nested span beacons).

    - Skip empty comment bodies and hash-only separators (e.g. "###").
    """
    n = len(lines)
    context: List[str] = []
    # @beacon[
    #   id=auto-beacon@_extract_sh_beacon_context._strip_hash_prefix-89ha,
    #   role=_extract_sh_beacon_context._strip_hash_prefix,
    #   slice_labels=ra-reconcile,
    #   kind=ast,
    # ]
    def _strip_hash_prefix(raw_line: str) -> str:
        s = raw_line.lstrip()
        if s.startswith("#"):
            # Remove only ONE leading '#'. This avoids turning '###' into ''
            # (which produced blank lines in the extracted context).
            return s[1:].lstrip()
        return s
    # @beacon[
    #   id=auto-beacon@_extract_sh_beacon_context._is_meta_block_end-lxa3,
    #   role=_extract_sh_beacon_context._is_meta_block_end,
    #   slice_labels=ra-reconcile,
    #   kind=ast,
    # ]
    def _is_meta_block_end(body: str) -> bool:
        # Close delimiter is a line that begins with ']'.
        # We intentionally do NOT use substring matching to avoid false positives.
        return body.strip().startswith("]")
    # Locate the end of the opener metadata block so we can start scanning below it.
    open_end = comment_line

    j = comment_line
    while 1 <= j <= n:
        body = _strip_hash_prefix(lines[j - 1])
        if _is_meta_block_end(body):
            open_end = j
            break
        j += 1

    # ABOVE: collect contiguous comment bodies above the opener.
    j = comment_line - 1
    while j >= 1:
        raw = lines[j - 1]
        if not raw.strip():
            j -= 1
            continue
        stripped = raw.lstrip()
        if not stripped.startswith("#"):
            break
        body = _strip_hash_prefix(raw)
        if not body:
            j -= 1
            continue
        if body.startswith("@beacon") or _is_meta_block_end(body):
            break
        if set(body.strip()) <= {"#"}:
            j -= 1
            continue
        context.insert(0, body)
        j -= 1

    # BELOW: collect contiguous comment bodies below the opener until we hit
    # a non-comment line or a matching @beacon-close block.
    j = open_end + 1
    while j <= n:
        raw = lines[j - 1]
        if not raw.strip():
            j += 1
            continue
        stripped = raw.lstrip()
        if not stripped.startswith("#"):
            break
        body = _strip_hash_prefix(raw)
        if not body:
            j += 1
            continue
        # Skip nested opener blocks entirely (do not treat as a terminator).
        if body.startswith("@beacon["):
            j += 1
            while j <= n:
                inner_body = _strip_hash_prefix(lines[j - 1])
                if _is_meta_block_end(inner_body):
                    j += 1
                    break
                j += 1
            continue
        # Stop at a matching close block; ignore close blocks for other beacon ids.
        if body.startswith("@beacon-close["):
            close_id: Optional[str] = None
            j += 1
            while j <= n:
                inner_body = _strip_hash_prefix(lines[j - 1]).strip()
                if inner_body.startswith("id=") and close_id is None:
                    close_id = inner_body.split("=", 1)[1].strip()
                    # Drop common trailing punctuation
                    close_id = close_id.rstrip(",").rstrip("]").strip()
                if _is_meta_block_end(inner_body):
                    j += 1
                    break
                j += 1
            # Only stop when the close id matches this beacon id.
            if beacon_id and close_id and close_id != beacon_id:
                continue
            break
        # Any other beacon marker terminates the context region.
        if body.startswith("@beacon"):
            break
        if set(body.strip()) <= {"#"}:
            j += 1
            continue
        context.append(body)
        j += 1

    return _strip_beacon_meta_blocks_from_context(context)


# @beacon[
#   id=carto-js-ts@apply_sh_beacons,
#   role=carto-js-ts,
#   slice_labels=carto-js-ts,carto-js-ts-beacons,ra-reconcile,
#   kind=span,
# ]
# Phase 2 JS/TS: shell beacon attachment example.
# Secondary template similar to SQL for span-only beacons.
def _prepend_duplicate_beacon_id_warning_nodes(
    children: List[Dict[str, Any]],
    beacons: list[dict[str, Any]],
    *,
    language: str,
) -> None:
    """Prepend warning nodes when duplicate beacon IDs appear in a single file.
    This is a UX guardrail. Duplicate beacon ids (often due to a mistaken
    `@beacon[` opener where `@beacon-close[` was intended) cause ambiguous
    id-based matching during F12 refresh.
    We emit a *salvageable* warning node so the user sees the problem at the
    top of the file subtree.
    """
    if not beacons:
        return
    seen_beacon_ids: set[str] = set()
    duplicate_beacon_ids: set[str] = set()
    for b in beacons:
        bid = (b.get("id") or "").strip()
        if not bid:
            continue
        if bid in seen_beacon_ids:
            duplicate_beacon_ids.add(bid)
        seen_beacon_ids.add(bid)
    if not duplicate_beacon_ids:
        return
    warning_nodes: List[Dict[str, Any]] = []
    for dup_id in sorted(duplicate_beacon_ids):
        warning_nodes.append(
            {
                "name": f"🚨 Duplicate beacon ID ({language}): {dup_id}",
                "note": (
                    "This file contains multiple @beacon blocks with the same id.\n\n"
                    "Why this matters:\n"
                    "- F12 refresh matches nodes by beacon id.\n"
                    "- Duplicate ids create ambiguous matches and may cause reorder storms.\n\n"
                    "Fix:\n"
                    "- Make beacon ids unique (or correct @beacon-close blocks).\n"
                    "- Then press F12 again."
                ),
                "children": [],
                "_position_hint": "top",
            }
        )
    # Insert at the TOP so it is immediately visible in Workflowy.
    children[:0] = warning_nodes
def apply_sh_beacons(
    lines: list[str],
    file_children: List[Dict[str, Any]],
    beacons: list[dict[str, Any]],
) -> None:
    """Attach shell span beacons as child nodes under the file node.

    Behavior mirrors SQL: purely location-centric annotations; explicit spans
    are left to snippet tools.
    """
    if not beacons:
        return

    n = len(lines)
    _prepend_duplicate_beacon_id_warning_nodes(file_children, beacons, language="SH")

    for beacon in beacons:
        if beacon.get("kind") != "span":
            continue

        b_id = (beacon.get("id") or "").strip()
        role = (beacon.get("role") or "").strip()
        raw_slice_labels = (beacon.get("slice_labels") or "").strip()

        if not role and b_id and "@" in b_id:
            role = b_id.split("@", 1)[0]
        slice_labels = _canonicalize_slice_labels(raw_slice_labels, role)

        show_span, show_span_explicit = _beacon_show_span(beacon)

        display_role = role or b_id or "sh-span-beacon"
        display_slice = slice_labels or "-"

        tag_suffix = _slice_label_tags(slice_labels or display_slice)
        name = f"🔱 {display_role}"
        if tag_suffix:
            name = f"{name} {tag_suffix}"

        context_lines = _extract_sh_beacon_context(
            lines,
            beacon.get("comment_line") or 0,
            beacon_id=b_id,
        )
        comment = beacon.get("comment")

        note_lines = [
            "BEACON (SH SPAN)",
            f"id: {b_id}",
            f"role: {role}",
            f"slice_labels: {slice_labels}",
            "kind: span",
        ]
        if show_span_explicit:
            note_lines.append(f"show_span: {'true' if show_span else 'false'}")
        if comment:
            note_lines.append(f"comment: {comment}")
        if context_lines:
            note_lines.append("")
            note_lines.append("CONTEXT COMMENTS (SH):")
            note_lines.extend(context_lines)

        # Raw shell span text between opener/closer (if Cartographer computed it)
        span_text_lines: List[str] = []
        span_start = beacon.get("span_lineno_start")
        span_end = beacon.get("span_lineno_end")
        if isinstance(span_start, int) and isinstance(span_end, int):
            span_start = max(1, span_start)
            span_end = min(n, span_end)
            if span_start <= span_end:
                span_text_lines = lines[span_start - 1 : span_end]
                while span_text_lines and not span_text_lines[0].strip():
                    span_text_lines.pop(0)
                while span_text_lines and not span_text_lines[-1].strip():
                    span_text_lines.pop()

        if show_span and span_text_lines:
            note_lines.append("")
            note_lines.append("SPAN TEXT:")
            note_lines.extend(span_text_lines)

        span_node = {
            "name": name,
            "note": "\n".join(note_lines),
            "children": [],
        }

        file_children.append(span_node)


# @beacon[
#   id=carto-js-ts@apply_yaml_beacon_context,
#   role=carto-js-ts,
#   slice_labels=carto-js-ts,carto-js-ts-beacons,ra-reconcile,
#   kind=span,
# ]
def _extract_yaml_beacon_context(
    lines: list[str],
    comment_line: int,
    beacon_id: Optional[str] = None,
) -> List[str]:
    """Extract nearby YAML comments (non-beacon) around a YAML @beacon block.
    Mirrors _extract_sh_beacon_context semantics:
    - Exclude @beacon[...] / @beacon-close[...] delimiter blocks and their metadata.

    - Stop at a matching @beacon-close (id match when beacon_id is provided).
    - Skip empty/hash-only separator lines.
    """
    n = len(lines)
    context: List[str] = []
    # @beacon[
    #   id=auto-beacon@_extract_yaml_beacon_context._strip_hash_prefix-5iy9,
    #   role=_extract_yaml_beacon_context._strip_hash_prefix,
    #   slice_labels=ra-reconcile,
    #   kind=ast,
    # ]
    def _strip_hash_prefix(raw_line: str) -> str:
        s = raw_line.lstrip()
        if s.startswith("#"):
            return s[1:].lstrip()
        return s
    # @beacon[
    #   id=auto-beacon@_extract_yaml_beacon_context._is_meta_block_end-c8x6,
    #   role=_extract_yaml_beacon_context._is_meta_block_end,
    #   slice_labels=ra-reconcile,
    #   kind=ast,
    # ]
    def _is_meta_block_end(body: str) -> bool:
        return body.strip().startswith("]")
    open_end = comment_line

    j = comment_line
    while 1 <= j <= n:
        body = _strip_hash_prefix(lines[j - 1])
        if _is_meta_block_end(body):
            open_end = j
            break
        j += 1

    # Above
    j = comment_line - 1
    while j >= 1:
        raw = lines[j - 1]
        if not raw.strip():
            j -= 1
            continue
        stripped = raw.lstrip()
        if not stripped.startswith("#"):
            break
        body = _strip_hash_prefix(raw)
        if not body:
            j -= 1
            continue
        if body.startswith("@beacon") or _is_meta_block_end(body):
            break
        if set(body.strip()) <= {"#"}:
            j -= 1
            continue
        context.insert(0, body)
        j -= 1

    # Below
    j = open_end + 1
    while j <= n:
        raw = lines[j - 1]
        if not raw.strip():
            j += 1
            continue
        stripped = raw.lstrip()
        if not stripped.startswith("#"):
            break
        body = _strip_hash_prefix(raw)
        if not body:
            j += 1
            continue
        if body.startswith("@beacon["):
            j += 1
            while j <= n:
                inner_body = _strip_hash_prefix(lines[j - 1])
                if _is_meta_block_end(inner_body):
                    j += 1
                    break
                j += 1
            continue
        if body.startswith("@beacon-close["):
            close_id: Optional[str] = None
            j += 1
            while j <= n:
                inner_body = _strip_hash_prefix(lines[j - 1]).strip()
                if inner_body.startswith("id=") and close_id is None:
                    close_id = inner_body.split("=", 1)[1].strip()
                    close_id = close_id.rstrip(",").rstrip("]").strip()
                if _is_meta_block_end(inner_body):
                    j += 1
                    break
                j += 1
            if beacon_id and close_id and close_id != beacon_id:
                continue
            break
        if body.startswith("@beacon"):
            break
        if set(body.strip()) <= {"#"}:
            j += 1
            continue
        context.append(body)
        j += 1

    return _strip_beacon_meta_blocks_from_context(context)


# @beacon[
#   id=carto-js-ts@apply_yaml_beacons,
#   role=carto-js-ts,
#   slice_labels=carto-js-ts,carto-js-ts-beacons,ra-reconcile,
#   kind=span,
# ]
# YAML beacon attachment example.
# Span-only beacons attached as children under a FILE node for YAML/Helm configs.
def apply_yaml_beacons(
    lines: list[str],
    file_children: List[Dict[str, Any]],
    beacons: list[dict[str, Any]],
) -> None:
    """Attach YAML span beacons as child nodes under the file node.

    Behavior mirrors SQL/SH: purely location-centric annotations; explicit spans
    are left to snippet tools.
    """
    if not beacons:
        return

    n = len(lines)
    _prepend_duplicate_beacon_id_warning_nodes(file_children, beacons, language="YAML")

    for beacon in beacons:
        if beacon.get("kind") != "span":
            continue

        b_id = (beacon.get("id") or "").strip()
        role = (beacon.get("role") or "").strip()
        raw_slice_labels = (beacon.get("slice_labels") or "").strip()

        if not role and b_id and "@" in b_id:
            role = b_id.split("@", 1)[0]
        slice_labels = _canonicalize_slice_labels(raw_slice_labels, role)

        show_span, show_span_explicit = _beacon_show_span(beacon)

        display_role = role or b_id or "yaml-span-beacon"
        display_slice = slice_labels or "-"

        tag_suffix = _slice_label_tags(slice_labels or display_slice)
        name = f"🔱 {display_role}"
        if tag_suffix:
            name = f"{name} {tag_suffix}"

        context_lines = _extract_yaml_beacon_context(
            lines,
            beacon.get("comment_line") or 0,
            beacon_id=b_id,
        )
        comment = beacon.get("comment")

        note_lines = [
            "BEACON (YAML SPAN)",
            f"id: {b_id}",
            f"role: {role}",
            f"slice_labels: {slice_labels}",
            "kind: span",
        ]
        if show_span_explicit:
            note_lines.append(f"show_span: {'true' if show_span else 'false'}")
        if comment:
            note_lines.append(f"comment: {comment}")
        if context_lines:
            note_lines.append("")
            note_lines.append("CONTEXT COMMENTS (YAML):")
            note_lines.extend(context_lines)

        # Raw YAML span text between opener/closer (if Cartographer computed it)
        span_text_lines: List[str] = []
        span_start = beacon.get("span_lineno_start")
        span_end = beacon.get("span_lineno_end")
        if isinstance(span_start, int) and isinstance(span_end, int):
            span_start = max(1, span_start)
            span_end = min(n, span_end)
            if span_start <= span_end:
                span_text_lines = lines[span_start - 1 : span_end]
                while span_text_lines and not span_text_lines[0].strip():
                    span_text_lines.pop(0)
                while span_text_lines and not span_text_lines[-1].strip():
                    span_text_lines.pop()

        if show_span and span_text_lines:
            note_lines.append("")
            note_lines.append("SPAN TEXT:")
            note_lines.extend(span_text_lines)

        span_node = {
            "name": name,
            "note": "\n".join(note_lines),
            "children": [],
        }

        file_children.append(span_node)


# @beacon[
#   id=carto-js-ts@apply_js_beacons,
#   role=carto-js-ts,
#   slice_labels=carto-js-ts,carto-js-ts-beacons,ra-snippet-range-ast-beacon-js-ts,f9-f12-handlers,ra-reconcile,
#   kind=span,
# ]
# Phase 2 JS/TS: JS/TS beacon attachment.
# Decorates JS/TS AST nodes (kind=ast) and attaches span children
# (kind=span) similarly to Python beacons.
def apply_js_beacons(
    file_path: str,
    lines: list[str],
    outline_nodes: List[Dict[str, Any]],
    beacons: list[dict[str, Any]],
) -> None:
    if not beacons:
        return

    # NOTE: outline_nodes may be empty for "flat" modules (no class/function/method
    # declarations). We still want to attach SPAN beacons at file-level in that case.
    ast_nodes = list(_iter_ast_outline_nodes(outline_nodes))

    n = len(lines)
    _prepend_duplicate_beacon_id_warning_nodes(outline_nodes, beacons, language="JS/TS")

    def _js_next_anchor_line_after(line_no: int) -> Optional[int]:
        for idx in range(line_no + 1, n + 1):
            raw = lines[idx - 1]
            stripped = raw.lstrip()
            if not stripped:
                continue
            if stripped.startswith("//"):
                continue
            if stripped.startswith("/*") or stripped.startswith("*") or stripped.startswith("*/"):
                continue
            return idx
        return None

    def _header_line_for_node(node: dict[str, Any]) -> Optional[str]:
        ln = node.get("orig_lineno_start_unused")
        if not isinstance(ln, int) or ln <= 0 or ln > len(lines):
            return None
        return lines[ln - 1]

    span_sort_lines: dict[int, int] = {}

    # @beacon[
    #   id=carto-beacon-order@js-node-source-order-line,
    #   role=apply_js_beacons._node_source_order_line,
    #   slice_labels=carto-js-ts,carto-js-ts-beacons,f9-f12-handlers,ra-reconcile,
    #   kind=ast,
    # ]
    def _node_source_order_line(node: dict[str, Any]) -> int:
        cached = span_sort_lines.get(id(node))
        if isinstance(cached, int):
            return cached
        ln = node.get("orig_lineno_start_unused") if isinstance(node, dict) else None
        if isinstance(ln, int):
            return ln
        return 10**9

    # @beacon[
    #   id=carto-beacon-order@js-insert-child-in-source-order,
    #   role=apply_js_beacons._insert_child_in_source_order,
    #   slice_labels=carto-js-ts,carto-js-ts-beacons,f9-f12-handlers,ra-reconcile,
    #   kind=ast,
    # ]
    def _insert_child_in_source_order(
        siblings: List[Dict[str, Any]],
        child_node: Dict[str, Any],
        sort_line: int,
    ) -> None:
        span_sort_lines[id(child_node)] = sort_line
        insert_at = len(siblings)
        for idx, existing in enumerate(siblings):
            if _node_source_order_line(existing) > sort_line:
                insert_at = idx
                break
        siblings.insert(insert_at, child_node)

    def _extract_js_beacon_context(comment_line: int) -> List[str]:
        """Extract nearby JS/TS comments (non-beacon) around a JS/TS beacon.

        Includes:
        - Lines that are part of a '//' line comment
        - Lines that are part of a block comment /* ... */ above/below the beacon

        Skips:
        - blank lines
        - lines containing '@beacon' (metadata)
        """
        context: List[str] = []

        # Precompute which lines are comment-like and a cleaned text version.
        # For block comments we treat every line between /* and */ (inclusive)
        # as comment-like, so that interior lines are visible in CONTEXT COMMENTS.
        comment_mask: list[bool] = [False] * n
        cleaned: list[str] = ["" for _ in range(n)]
        in_block = False

        for idx, raw in enumerate(lines, start=1):
            stripped = raw.lstrip()
            if not stripped:
                continue
            # NOTE: we intentionally do NOT skip '@beacon' lines here.
            # We collect them into context and later strip the entire
            # delimiter block via _strip_beacon_meta_blocks_from_context(...).

            is_comment = False
            text = ""

            if not in_block:
                if stripped.startswith("//"):
                    is_comment = True
                    text = stripped[2:].lstrip()
                elif "/*" in stripped:
                    is_comment = True
                    in_block = True
                    after = stripped.split("/*", 1)[1]
                    if "*/" in after:
                        before_close, _ = after.split("*/", 1)
                        text = before_close.strip()
                        in_block = False
                    else:
                        text = after.strip()
            else:
                is_comment = True
                if "*/" in stripped:
                    before_close, _ = stripped.split("*/", 1)
                    text = before_close.strip()
                    in_block = False
                else:
                    text = stripped

            if is_comment:
                comment_mask[idx - 1] = True
                cleaned[idx - 1] = text

        # Find end of beacon block (first line containing ']')
        j = comment_line
        block_end = comment_line
        while j <= n:
            raw = lines[j - 1]
            body = raw.lstrip()
            if body.startswith("//"):
                body = body[2:].lstrip()
            if body.startswith("/*"):
                body = body[2:].lstrip()
            if body.startswith("*/"):
                body = body[2:].lstrip()
            if body.startswith("*"):
                body = body[1:].lstrip()
            if body.rstrip().endswith("*/"):
                body = body.rstrip()[:-2].rstrip()
            if body.strip().startswith("]"):
                block_end = j
                break
            j += 1

        # Above
        j = comment_line - 1
        while j >= 1:
            raw = lines[j - 1]
            if not raw.strip():
                j -= 1
                continue
            if comment_mask[j - 1]:
                if cleaned[j - 1]:
                    context.insert(0, cleaned[j - 1])
                j -= 1
                continue
            break

        # Below
        j = block_end + 1
        while j <= n:
            raw = lines[j - 1]
            if not raw.strip():
                j += 1
                continue
            if comment_mask[j - 1]:
                if cleaned[j - 1]:
                    context.append(cleaned[j - 1])
                j += 1
                continue
            break

        return _strip_beacon_meta_blocks_from_context(context)

    # Pre-pass: for snippet-less beacons (span OR ast), compute anchor lineno.
    # For span beacons, we *sometimes* auto-upgrade to AST when anchor is a
    # class/function/method.
    #
    # IMPORTANT VUE/JS/TS RULES:
    # - If a span beacon has an explicit closing delimiter (span_lineno_end is set),
    #   it is a TRUE SPAN region and must NOT be auto-upgraded to AST.
    # - If the author explicitly wrote kind=span, preserve that intent.
    #   Auto-upgrade is only for implicit single-beacon inline anchors.
    for beacon in beacons:
        kind = beacon.get("kind")
        start_snippet = beacon.get("start_snippet")
        b_id = beacon.get("id") or "(no-id)"
        if kind in {"span", "ast"} and not start_snippet:
            comment_line = beacon.get("comment_line") or 0
            if isinstance(comment_line, int) and comment_line > 0:
                anchor = _js_next_anchor_line_after(comment_line)
            else:
                anchor = None
            if anchor is None:
                continue
            beacon["_anchor_lineno"] = anchor

            # Never auto-upgrade an explicit span region (paired opener/closer).
            if kind == "span" and isinstance(beacon.get("span_lineno_end"), int):
                continue

            if kind == "span" and bool(beacon.get("kind_explicit")):
                continue

            ast_candidates: list[dict[str, Any]] = []
            for node in ast_nodes:
                ast_type = node.get("ast_type")
                if ast_type not in {"class", "function", "method", "const_decl", "let_decl", "var_decl"}:
                    continue
                ln = node.get("orig_lineno_start_unused")
                if isinstance(ln, int) and ln == anchor:
                    ast_candidates.append(node)
            if kind == "span" and len(ast_candidates) == 1:
                beacon["kind"] = "ast"

    # Pass 1: AST beacons
    for beacon in beacons:
        if beacon.get("kind") != "ast":
            continue
        b_id = beacon.get("id") or "(no-id)"
        start_snippet = beacon.get("start_snippet")
        comment_line = beacon.get("comment_line") or 0
        anchor_lineno = beacon.get("_anchor_lineno")
        print(f"[CARTOGRAPHER] apply_js_beacons Pass1: id={b_id} start_snippet={start_snippet!r} _anchor_lineno={anchor_lineno}", file=sys.stderr)

        chosen: Optional[dict[str, Any]] = None

        if start_snippet:
            norm_snip = normalize_for_match(start_snippet)
            if not norm_snip:
                continue

            candidates: list[dict[str, Any]] = []
            for node in ast_nodes:
                header = _header_line_for_node(node)
                if header is None:
                    continue
                if norm_snip in normalize_for_match(header):
                    candidates.append(node)

            if not candidates:
                continue

            if len(candidates) == 1:
                chosen = candidates[0]
            else:
                after = [
                    n
                    for n in candidates
                    if isinstance(n.get("orig_lineno_start_unused"), int)
                    and n["orig_lineno_start_unused"] > comment_line
                ]
                if len(after) == 1:
                    chosen = after[0]
                else:
                    continue
        else:
            anchor = beacon.get("_anchor_lineno")
            if not isinstance(anchor, int):
                continue
            ast_candidates = [
                node
                for node in ast_nodes
                if node.get("ast_type") in {"class", "function", "method", "const_decl", "let_decl", "var_decl"}
                and isinstance(node.get("orig_lineno_start_unused"), int)
                and node["orig_lineno_start_unused"] == anchor
            ]
            if len(ast_candidates) == 1:
                chosen = ast_candidates[0]
            else:
                continue

        if not chosen:
            continue

        b_id = (beacon.get("id") or "").strip()
        role = (beacon.get("role") or "").strip()
        raw_slice_labels = (beacon.get("slice_labels") or "").strip()
        if not role and b_id and "@" in b_id:
            role = b_id.split("@", 1)[0]
        slice_labels = _canonicalize_slice_labels(raw_slice_labels, role)

        display_role = role or b_id or "js-ast-beacon"
        display_slice = slice_labels or "-"
        tag_suffix = _slice_label_tags(slice_labels or display_slice)

        name = chosen.get("name") or "Untitled"
        if "🔱" not in name:
            name = f"{name} 🔱"
        if tag_suffix:
            name = f"{name} {tag_suffix}"
        chosen["name"] = name

        comment = beacon.get("comment")
        meta_lines = [
            "BEACON (JS/TS AST)",
            f"id: {b_id}",
            f"role: {role}",
            f"slice_labels: {slice_labels}",
            "kind: ast",
        ]
        if comment:
            meta_lines.append(f"comment: {comment}")
        context_lines = _extract_js_beacon_context(comment_line)
        if context_lines:
            meta_lines.append("")
            meta_lines.append("CONTEXT COMMENTS (JS/TS):")
            meta_lines.extend(context_lines)
        note = chosen.get("note") or ""
        if note:
            # Keep the identifier (AST_QUALNAME) at the top, then insert the
            # BEACON metadata block, then the rest of the content.
            note_lines = note.splitlines()
            insert_idx = (
                1
                if (note_lines and note_lines[0].strip().startswith("AST_QUALNAME:"))
                else 0
            )
            new_note_lines: list[str] = []
            new_note_lines.extend(note_lines[:insert_idx])
            new_note_lines.extend(meta_lines)
            if insert_idx < len(note_lines):
                if note_lines[insert_idx].strip():
                    new_note_lines.append("")
                new_note_lines.extend(note_lines[insert_idx:])
            chosen["note"] = "\n".join(new_note_lines)
        else:
            chosen["note"] = "\n".join(meta_lines)

    # Pass 2: SPAN beacons
    for beacon in beacons:
        if beacon.get("kind") != "span":
            continue
        start_snippet = beacon.get("start_snippet")
        comment_line = beacon.get("comment_line") or 0

        attachment_line: Optional[int] = None

        if start_snippet:
            norm_snip = normalize_for_match(start_snippet)
            if not norm_snip:
                continue
            start_candidates: list[int] = []
            for idx, line in enumerate(lines, start=1):
                stripped = line.lstrip()
                if stripped.startswith("//") or stripped.startswith("/*") or stripped.startswith("*") or stripped.startswith("*/"):
                    continue
                if norm_snip in normalize_for_match(line):
                    start_candidates.append(idx)
            if not start_candidates:
                continue
            if len(start_candidates) == 1:
                attachment_line = start_candidates[0]
            else:
                after = [ln for ln in start_candidates if ln > comment_line]
                if len(after) == 1:
                    attachment_line = after[0]
                else:
                    continue
        else:
            # Snippet-less spans attach based on beacon location so root-level
            # documentation spans stay at file scope instead of slipping under
            # the next AST node.
            span_start = beacon.get("span_lineno_start")
            if isinstance(span_start, int):
                attachment_line = span_start
            elif isinstance(comment_line, int) and comment_line > 0:
                attachment_line = comment_line
            else:
                anchor = beacon.get("_anchor_lineno")
                attachment_line = anchor if isinstance(anchor, int) else None

        if attachment_line is None:
            continue

        enclosing = _find_enclosing_ast_node_for_line(outline_nodes, attachment_line)

        b_id = (beacon.get("id") or "").strip()
        role = (beacon.get("role") or "").strip()
        raw_slice_labels = (beacon.get("slice_labels") or "").strip()
        if not role and b_id and "@" in b_id:
            role = b_id.split("@", 1)[0]
        slice_labels = _canonicalize_slice_labels(raw_slice_labels, role)

        show_span, show_span_explicit = _beacon_show_span(beacon)

        display_role = role or b_id or "js-span-beacon"
        display_slice = slice_labels or "-"
        tag_suffix = _slice_label_tags(slice_labels or display_slice)

        name = f"🔱 {display_role}"
        if tag_suffix:
            name = f"{name} {tag_suffix}"

        context_lines = _extract_js_beacon_context(comment_line)
        comment = beacon.get("comment")

        note_lines = [
            "BEACON (JS/TS SPAN)",
            f"id: {b_id}",
            f"role: {role}",
            f"slice_labels: {slice_labels}",
            "kind: span",
        ]
        if show_span_explicit:
            note_lines.append(f"show_span: {'true' if show_span else 'false'}")
        if comment:
            note_lines.append(f"comment: {comment}")
        if context_lines:
            note_lines.append("")
            note_lines.append("CONTEXT COMMENTS (JS/TS):")
            note_lines.extend(context_lines)

        # Raw JS/TS span text between @beacon[...] and @beacon-close[...] (if available)
        span_start = beacon.get("span_lineno_start")
        span_end = beacon.get("span_lineno_end")
        span_text_lines: List[str] = []
        if isinstance(span_start, int) and isinstance(span_end, int):
            span_start = max(1, span_start)
            span_end = min(n, span_end)
            if span_start <= span_end:
                span_text_lines = lines[span_start - 1 : span_end]
                # Trim leading/trailing blank lines inside the span
                while span_text_lines and not span_text_lines[0].strip():
                    span_text_lines.pop(0)
                while span_text_lines and not span_text_lines[-1].strip():
                    span_text_lines.pop()

        if show_span and span_text_lines:
            note_lines.append("")
            note_lines.append("SPAN TEXT:")
            note_lines.extend(span_text_lines)

        span_node = {
            "name": name,
            "note": "\n".join(note_lines),
            "children": [],
        }

        if enclosing is not None:
            children = enclosing.get("children") or []
            _insert_child_in_source_order(children, span_node, attachment_line)
            enclosing["children"] = children
        else:
            _insert_child_in_source_order(outline_nodes, span_node, attachment_line)


# @beacon[
#   id=carto-js-ts@split_name_and_tags,
#   role=carto-js-ts,
#   slice_labels=carto-js-ts,carto-js-ts-beacons,f9-f12-handlers,ra-reconcile,
#   kind=span,
# ]
# Utility: split a Workflowy node name into base text and trailing #tags.
# Used by update_beacon_from_node_* helpers to derive slice_labels from
# name suffixes while keeping the canonical AST/beacon node name clean.
def split_name_and_tags(raw_name: str) -> tuple[str, list[str]]:
    name = (raw_name or "").strip()
    if not name:
        return "", []
    tokens = name.split()
    tags: list[str] = []
    # Walk from the end, collect tokens that look like tags (start with '#').
    while tokens and tokens[-1].startswith("#"):
        tags.insert(0, tokens.pop())
    base = " ".join(tokens).strip()
    return base, tags


# @beacon[
#   id=auto-beacon@normalize_beacon_comment_field_aliases_in_file-9q2m,
#   role=normalize_beacon_comment_field_aliases_in_file,
#   slice_labels=f9-f12-handlers,ra-reconcile,carto-js-ts-beacons,
#   kind=ast,
#   comment=Canonicalize legacy beacon metadata alias comments= to comment= during F12 flows.
# ]
def normalize_beacon_comment_field_aliases_in_file(file_path: str) -> Dict[str, Any]:
    """Normalize legacy beacon key alias `comments=` -> `comment=` inside real beacon metadata blocks only.

    This hygiene pass is used by F12 refresh/update flows so users can type
    either field name and the source is silently canonicalized.

    SAFETY PRINCIPLE
    ----------------
    We must never perform a whole-file `comments=` replacement, because real
    source code can legitimately contain assignments such as:

        comments = EXCLUDED.comments

    Therefore we only rewrite lines that are inside a syntactically recognized
    ``@beacon[...]`` metadata block for the file's language/comment style.
    """
    try:
        with open(file_path, "r", encoding="utf-8") as f:
            original = f.read()
    except Exception as e:  # noqa: BLE001
        return {"success": False, "changed": False, "file_path": file_path, "error": str(e)}

    ext = os.path.splitext(file_path)[1].lower()
    lines = original.splitlines(keepends=True)
    if not lines:
        return {"success": True, "changed": False, "file_path": file_path}

    def _extract_prefixed_body(raw: str, markers: tuple[str, ...]) -> tuple[str, str] | None:
        stripped = raw.lstrip()
        indent_len = len(raw) - len(stripped)
        for marker in markers:
            if stripped.startswith(marker):
                remainder = stripped[len(marker):]
                ws_len = len(remainder) - len(remainder.lstrip())
                prefix_len = indent_len + len(marker) + ws_len
                return raw[:prefix_len], raw[prefix_len:]
        return None

    def _extract_hash_body(raw: str) -> tuple[str, str] | None:
        return _extract_prefixed_body(raw, ("#",))

    def _extract_dashdash_body(raw: str) -> tuple[str, str] | None:
        return _extract_prefixed_body(raw, ("--",))

    def _extract_slashslash_body(raw: str) -> tuple[str, str] | None:
        return _extract_prefixed_body(raw, ("//",))

    def _extract_cblock_body(raw: str) -> tuple[str, str]:
        stripped = raw.lstrip()
        indent_len = len(raw) - len(stripped)
        if stripped.startswith("/*"):
            remainder = stripped[2:]
            ws_len = len(remainder) - len(remainder.lstrip())
            prefix_len = indent_len + 2 + ws_len
            return raw[:prefix_len], raw[prefix_len:]
        if stripped.startswith("*/"):
            remainder = stripped[2:]
            ws_len = len(remainder) - len(remainder.lstrip())
            prefix_len = indent_len + 2 + ws_len
            return raw[:prefix_len], raw[prefix_len:]
        if stripped.startswith("*"):
            remainder = stripped[1:]
            ws_len = len(remainder) - len(remainder.lstrip())
            prefix_len = indent_len + 1 + ws_len
            return raw[:prefix_len], raw[prefix_len:]
        # For multiline /* ... */ beacon blocks, inner lines may be bare text.
        return raw[:indent_len], raw[indent_len:]

    def _extract_plain_body(raw: str) -> tuple[str, str]:
        stripped = raw.lstrip()
        indent_len = len(raw) - len(stripped)
        return raw[:indent_len], raw[indent_len:]

    def _replace_comments_key(raw: str, extractor) -> tuple[str, bool]:
        parts = extractor(raw)
        if parts is None:
            return raw, False
        prefix, body = parts
        new_body, n = re.subn(r"^comments(\s*=)", r"comment\1", body, count=1)
        if n == 0:
            return raw, False
        return prefix + new_body, True

    py_like_exts = {".py", ".sh", ".bash", ".yml", ".yaml"}
    js_like_exts = {".js", ".jsx", ".ts", ".tsx", ".vue"}
    html_comment_exts = {".md", ".markdown", ".vue"}

    mode: str | None = None
    pending_html_comment = False
    changed = False

    for idx, raw in enumerate(lines):
        if mode is None:
            if ext in py_like_exts:
                parts = _extract_hash_body(raw)
                if parts and parts[1].startswith("@beacon["):
                    mode = "hash"
                continue

            if ext == ".sql":
                parts = _extract_dashdash_body(raw)
                if parts and parts[1].startswith("@beacon["):
                    mode = "dashdash"
                continue

            if ext in js_like_exts:
                parts = _extract_slashslash_body(raw)
                if parts and parts[1].startswith("@beacon["):
                    mode = "slashslash"
                    continue
                cblock_parts = _extract_cblock_body(raw)
                if cblock_parts[1].startswith("@beacon["):
                    mode = "cblock"
                    continue

            if ext in html_comment_exts:
                stripped = raw.strip()
                if pending_html_comment:
                    pending_html_comment = False
                    if stripped.startswith("@beacon["):
                        mode = "html_comment"
                    continue
                if stripped.startswith("<!--"):
                    after = stripped[len("<!--"):].lstrip()
                    if after.startswith("@beacon["):
                        mode = "html_comment"
                    else:
                        pending_html_comment = True
                continue

            continue

        if mode == "hash":
            new_raw, did_change = _replace_comments_key(raw, _extract_hash_body)
            lines[idx] = new_raw
            changed = changed or did_change
            parts = _extract_hash_body(new_raw)
            if parts and parts[1].strip().startswith("]"):
                mode = None
            continue

        if mode == "dashdash":
            new_raw, did_change = _replace_comments_key(raw, _extract_dashdash_body)
            lines[idx] = new_raw
            changed = changed or did_change
            parts = _extract_dashdash_body(new_raw)
            if parts and parts[1].strip().startswith("]"):
                mode = None
            continue

        if mode == "slashslash":
            new_raw, did_change = _replace_comments_key(raw, _extract_slashslash_body)
            lines[idx] = new_raw
            changed = changed or did_change
            parts = _extract_slashslash_body(new_raw)
            if parts and parts[1].strip().startswith("]"):
                mode = None
            continue

        if mode == "cblock":
            new_raw, did_change = _replace_comments_key(raw, _extract_cblock_body)
            lines[idx] = new_raw
            changed = changed or did_change
            _prefix, body = _extract_cblock_body(new_raw)
            if body.strip().startswith("]"):
                mode = None
            continue

        if mode == "html_comment":
            new_raw, did_change = _replace_comments_key(raw, _extract_plain_body)
            lines[idx] = new_raw
            changed = changed or did_change
            _prefix, body = _extract_plain_body(new_raw)
            if body.strip().startswith("]"):
                mode = None
            continue

    if not changed:
        return {"success": True, "changed": False, "file_path": file_path}

    normalized = "".join(lines)
    try:
        with open(file_path, "w", encoding="utf-8") as f:
            f.write(normalized)
    except Exception as e:  # noqa: BLE001
        return {"success": False, "changed": False, "file_path": file_path, "error": str(e)}

    return {"success": True, "changed": True, "file_path": file_path}


def _indent_beacon_block(block_lines: list[str], source_lines: list[str], insert_idx: int) -> list[str]:
    """Indent beacon block to match the following non-blank line's indentation.
    
    Args:
        block_lines: The beacon comment block lines (unindented).
        source_lines: The full source file lines array.
        insert_idx: The line index where the beacon will be inserted.
    
    Returns:
        The beacon block with indentation applied.
    """
    # Scan forward from insert_idx to find first non-blank line.
    indent = ""
    for idx in range(insert_idx, len(source_lines)):
        line = source_lines[idx]
        if line.strip():
            # Measure leading whitespace.
            indent = line[:len(line) - len(line.lstrip())]
            break
    # Apply indent to every line in the block.
    return [indent + line for line in block_lines]


def _generate_auto_beacon_hash() -> str:
    """Generate a short random hash for auto-beacon collision resistance.
    
    Returns a 4-character lowercase alphanumeric string.
    """
    return "".join(random.choices(string.ascii_lowercase + string.digits, k=4))


# @beacon[
#   id=carto-js-ts@update_beacon_from_node_python,
#   role=carto-js-ts,
#   slice_labels=carto-js-ts,carto-js-ts-beacons,f9-f12-handlers,ra-reconcile,
#   kind=span,
# ]
# Python: update/create/delete a beacon for a single AST/beacon node
# based on Workflowy name/note fields.
#
# This is the Cartographer-side helper invoked by the MCP server when F12
# is pressed on a Python AST/beacon node. It does not talk to Workflowy
# directly; instead it focuses on:
#   • interpreting Workflowy name/note as desired beacon metadata
#   • computing canonical slice_labels from tags + note
#   • deciding whether to update, create, or delete @beacon[...] blocks
#   • returning a small summary of what should be reflected back into
#     the local cache.
def update_beacon_from_node_python(
    file_path: str,
    name: str,
    note: str,
) -> Dict[str, Any]:
    """Update/create/delete Python @beacon[...] blocks for a single node.

    This helper performs on-disk edits ONLY. It does not touch Workflowy; the
    MCP client is responsible for updating the local /nodes-export cache name
    (and possibly note) to reflect the final state returned here.

    Policy:
    - If note contains BEACON metadata with an id: → update existing block.
    - Else if AST_QUALNAME present and tags present → create a new beacon
      anchored to that AST node, derived from tags.
    - Else if there is a beacon on disk for this AST_QUALNAME/id but the note
      has no BEACON block → delete the beacon.
    """
    base_name, tags = split_name_and_tags(name)
    beacon_id = _extract_beacon_id_from_note(note)
    ast_qualname = _extract_ast_qualname_from_note(note)

    print(
        f"[CARTOGRAPHER] update_beacon_from_node_python start "
        f"(file_path={file_path!r}, base_name={base_name!r}, "
        f"tags={tags}, beacon_id={beacon_id!r}, ast_qualname={ast_qualname!r})",
        file=sys.stderr,
    )

    result: Dict[str, Any] = {
        "language": "python",
        "file_path": file_path,
        "base_name": base_name,
        "tags": tags,
        "beacon_id": beacon_id,
        "ast_qualname": ast_qualname,
        "operation": "noop",
    }

    # Load file lines once.
    try:
        with open(file_path, "r", encoding="utf-8") as f:
            lines = f.read().splitlines()
    except Exception as e:  # noqa: BLE001
        result["error"] = f"failed_to_read_file: {e}"
        return result

    beacons = parse_python_beacon_blocks(lines)

    # Helper: locate beacon block by id and return (start_idx,end_idx,comment_line).
    def _find_beacon_block_by_id(bid: str) -> Optional[tuple[int, int, int]]:
        bid = (bid or "").strip()
        if not bid:
            return None
        for b in beacons:
            if (b.get("id") or "").strip() != bid:
                continue
            cl = b.get("comment_line")
            if not isinstance(cl, int) or cl <= 0:
                continue
            # Walk forward to find the closing ']' line; include all lines that
            # start with '#' and belong to this metadata block.
            #
            # We treat a line as the closing delimiter only when the metadata
            # body is exactly a single ']' after stripping the leading '#' and
            # whitespace. This prevents an incidental ']' inside a comment
            # field from terminating the block prematurely.
            start_idx = cl - 1
            j = cl
            end_idx = start_idx
            while j <= len(lines):
                raw = lines[j - 1]
                stripped = raw.lstrip()
                if stripped.startswith("#"):
                    body = stripped.lstrip("#").lstrip()
                else:
                    body = stripped
                if body == "]":
                    end_idx = j - 1
                    break
                j += 1
            return start_idx, end_idx, cl
        return None

    # Helper: rebuild a beacon block for a given id/role/slice_labels/comment.
    def _build_beacon_block(
        bid: str,
        role: str,
        slice_labels: str,
        kind: str,
        show_span: Optional[bool],
        comment_text: Optional[str],
    ) -> list[str]:
        meta_lines = [
            "# @beacon[",
            f"#   id={bid},",
        ]
        if role:
            meta_lines.append(f"#   role={role},")
        if slice_labels:
            meta_lines.append(f"#   slice_labels={slice_labels},")
        if kind:
            meta_lines.append(f"#   kind={kind},")
        if show_span is not None:
            meta_lines.append(f"#   show_span={'true' if show_span else 'false'},")
        if comment_text:
            meta_lines.append(f"#   comment={comment_text},")
        meta_lines.append("# ]")
        return meta_lines

    # Case 1: beacon_id present in note (update existing or create from metadata).
    if beacon_id:
        # Derive role/comment from note. slice_labels are now driven solely by
        # the Workflowy node name's trailing #tags; the slice_labels line in
        # the BEACON block is treated as display-only.
        role_val: str | None = None
        comment_val: str | None = None
        for line in (note or "").splitlines():
            stripped = line.strip()
            if stripped.startswith("role:"):
                role_val = stripped.split(":", 1)[1].strip()
            elif stripped.startswith("comment:") or stripped.startswith("comments:"):
                comment_val = stripped.split(":", 1)[1].strip()

        show_span_note = _extract_show_span_from_note(note)

        role_display = role_val or (beacon_id.split("@", 1)[0] if "@" in beacon_id else "")

        # Slice labels come **only** from Workflowy tags in the node name.
        extra_label_tokens = [t.lstrip("#") for t in tags]
        slice_labels_canon = (
            _canonicalize_slice_labels(",".join(extra_label_tokens), None)
            if extra_label_tokens
            else ""
        )

        block_span = _find_beacon_block_by_id(beacon_id)
        if block_span is not None:
            # Case 1a: UPDATE existing beacon on disk.
            start_idx, end_idx, _cl = block_span

            # Preserve existing kind (span vs ast) when updating an on-disk beacon.
            existing_kind = "ast"
            existing_show_span: Optional[bool] = None
            for b in beacons:
                if (b.get("id") or "").strip() != (beacon_id or "").strip():
                    continue
                k_val = (b.get("kind") or "").strip().lower()
                if k_val in {"ast", "span"}:
                    existing_kind = k_val
                # Preserve explicit show_span from disk when present.
                if b.get("show_span_explicit"):
                    existing_show_span = bool(b.get("show_span"))
                break

            show_span_to_write: Optional[bool] = (
                show_span_note if show_span_note is not None else existing_show_span
            )

            new_block = _build_beacon_block(
                bid=beacon_id,
                role=role_display or "",
                slice_labels=slice_labels_canon,
                kind=existing_kind,
                show_span=show_span_to_write,
                comment_text=comment_val,
            )
            new_block = _indent_beacon_block(new_block, lines, start_idx)
            new_lines = lines[:start_idx] + new_block + lines[end_idx + 1 :]
            try:
                with open(file_path, "w", encoding="utf-8") as f:
                    f.write("\n".join(new_lines) + "\n")
            except Exception as e:  # noqa: BLE001
                result["error"] = f"failed_to_write_file: {e}"
                return result

            result.update(
                {
                    "operation": "updated_beacon",
                    "role": role_display,
                    "slice_labels": slice_labels_canon,
                    "comment": comment_val,
                }
            )
            return result
        else:
            # Case 1b: CREATE beacon from note metadata (beacon_id in note, not on disk).
            # Use AST_QUALNAME to find insertion point.
            target_line: Optional[int] = None
            if ast_qualname:
                try:
                    outline_nodes = parse_file_outline(file_path)
                except Exception:
                    outline_nodes = []

                if outline_nodes:
                    def _iter_nodes(nodes_list: list[dict[str, Any]]):
                        for n in nodes_list:
                            if isinstance(n, dict):
                                yield n
                                for ch in n.get("children") or []:
                                    if isinstance(ch, dict):
                                        yield from _iter_nodes([ch])

                    for n in _iter_nodes(outline_nodes):
                        if n.get("ast_qualname") == ast_qualname:
                            ln = n.get("orig_lineno_start_unused")
                            if isinstance(ln, int) and ln > 0:
                                target_line = ln
                                break

            if not isinstance(target_line, int) or target_line <= 0 or target_line > len(lines):
                insert_idx = 0
            else:
                insert_idx = target_line - 1

            new_block = _build_beacon_block(
                bid=beacon_id,
                role=role_display or "",
                slice_labels=slice_labels_canon,
                kind="ast",
                show_span=show_span_note,
                comment_text=comment_val,
            )
            new_block = _indent_beacon_block(new_block, lines, insert_idx)
            new_lines = lines[:insert_idx] + new_block + lines[insert_idx:]
            try:
                with open(file_path, "w", encoding="utf-8") as f:
                    f.write("\n".join(new_lines) + "\n")
            except Exception as e:  # noqa: BLE001
                result["error"] = f"failed_to_write_file: {e}"
                return result

            result.update(
                {
                    "operation": "created_beacon",
                    "beacon_id": beacon_id,
                    "role": role_display,
                    "slice_labels": slice_labels_canon,
                    "comment": comment_val,
                }
            )
            return result

    # Helper: delete beacon(s) for this AST_QUALNAME using Cartographer outline.
    #
    # We intentionally fail closed: if we cannot unambiguously map the
    # AST_QUALNAME to exactly one AST node (with a BEACON block in its note),
    # we do not delete anything.
    def _delete_beacon_for_ast_qualname(target_ast_qualname: str) -> Optional[str]:
        try:
            outline_nodes = parse_file_outline(file_path)
        except Exception as e:  # noqa: BLE001
            print(
                "[CARTOGRAPHER] update_beacon_from_node_python delete-abort "
                f"(file_path={file_path!r}, ast_qualname={target_ast_qualname!r}, error={e!r})",
                file=sys.stderr,
            )
            return None

        if not outline_nodes:
            return None

        # Find the unique AST node for this qualname.
        matches: list[dict[str, Any]] = [
            n
            for n in _iter_ast_outline_nodes(outline_nodes)
            if n.get("ast_qualname") == target_ast_qualname
        ]
        if len(matches) != 1:
            # Ambiguous or missing mapping – do nothing.
            print(
                "[CARTOGRAPHER] update_beacon_from_node_python delete-abort "
                f"(file_path={file_path!r}, ast_qualname={target_ast_qualname!r}, "
                f"matches={len(matches)})",
                file=sys.stderr,
            )
            return None

        node = matches[0]
        node_note = node.get("note") or ""
        if "BEACON (" not in node_note:
            return None

        bid = _extract_beacon_id_from_note(node_note)
        if not bid:
            return None

        span = _find_beacon_block_by_id(bid)
        if span is None:
            return None

        start_idx, end_idx, _cl = span
        new_lines = lines[:start_idx] + lines[end_idx + 1 :]
        try:
            with open(file_path, "w", encoding="utf-8") as f:
                f.write("\n".join(new_lines) + "\n")
        except Exception as e:  # noqa: BLE001
            result["error"] = f"failed_to_write_file: {e}"
            return None

        return bid

    # Case 1c: DELETE beacon when note has no BEACON metadata and no tags.
    # This covers the common Python F12 path where F12-per-node originally created
    # a beacon for this AST_QUALNAME and the user later deletes the tags and
    # BEACON block from the Workflowy note (leaving only AST_QUALNAME).
    if ast_qualname and not tags and not beacon_id:
        deleted_id = _delete_beacon_for_ast_qualname(ast_qualname)
        if deleted_id:
            result.update(
                {
                    "operation": "deleted_beacon",
                    "beacon_id": deleted_id,
                    "role": ast_qualname,
                    "slice_labels": "",
                }
            )
            return result

    # Case 2: no beacon_id, but AST_QUALNAME + tags → create a new beacon.
    if ast_qualname and tags:
        # Build a synthetic id with a hash suffix for collision resistance.
        hash_suffix = _generate_auto_beacon_hash()
        simple_id = f"auto-beacon@{ast_qualname}-{hash_suffix}"
        role_display = ast_qualname

        # Slice labels come **only** from Workflowy tags; we do not auto-derive
        # additional labels from role/id/AST_QUALNAME.
        extra_label_tokens = [t.lstrip("#") for t in tags]
        slice_labels_canon = (
            _canonicalize_slice_labels(",".join(extra_label_tokens), None)
            if extra_label_tokens
            else ""
        )

        # Insert above the AST node header line (best-effort): use
        # parse_file_outline to discover the node and its start line.
        try:
            outline_nodes = parse_file_outline(file_path)
        except Exception:
            outline_nodes = []

        target_line: Optional[int] = None
        if outline_nodes:
            # Walk outline to find node with matching AST_QUALNAME.
            def _iter_nodes(nodes_list: list[dict[str, Any]]):
                for n in nodes_list:
                    if isinstance(n, dict):
                        yield n
                        for ch in n.get("children") or []:
                            if isinstance(ch, dict):
                                yield from _iter_nodes([ch])

            for n in _iter_nodes(outline_nodes):
                if n.get("ast_qualname") == ast_qualname:
                    ln = n.get("orig_lineno_start_unused")
                    if isinstance(ln, int) and ln > 0:
                        target_line = ln
                        break

        if not isinstance(target_line, int) or target_line <= 0 or target_line > len(lines):
            # Fallback: prepend at top of file.
            insert_idx = 0
        else:
            insert_idx = target_line - 1

        new_block = _build_beacon_block(
            bid=simple_id,
            role=role_display,
            slice_labels=slice_labels_canon,
            kind="ast",
            show_span=None,
            comment_text=None,
        )
        new_block = _indent_beacon_block(new_block, lines, insert_idx)
        new_lines = lines[:insert_idx] + new_block + lines[insert_idx:]
        try:
            with open(file_path, "w", encoding="utf-8") as f:
                f.write("\n".join(new_lines) + "\n")
        except Exception as e:  # noqa: BLE001
            result["error"] = f"failed_to_write_file: {e}"
            return result

        result.update(
            {
                "operation": "created_beacon",
                "beacon_id": simple_id,
                "role": role_display,
                "slice_labels": slice_labels_canon,
            }
        )
        return result

    # Otherwise, noop for now.
    print(
        "[CARTOGRAPHER] update_beacon_from_node_python noop "
        f"(file_path={file_path!r}, base_name={base_name!r}, "
        f"tags={tags}, beacon_id={beacon_id!r}, ast_qualname={ast_qualname!r})",
        file=sys.stderr,
    )
    return result


# @beacon[
#   id=carto-js-ts@update_beacon_from_node_js_ts,
#   role=carto-js-ts,
#   slice_labels=carto-js-ts,carto-js-ts-beacons,f9-f12-handlers,ra-reconcile,
#   kind=span,
# ]
# JS/TS: update/create/delete a beacon for a single AST/beacon node based
# on Workflowy name/note fields. Mirrors the Python helper but uses
# JS/TS-specific outline + beacon parsing.
def update_beacon_from_node_js_ts(
    file_path: str,
    name: str,
    note: str,
) -> Dict[str, Any]:
    """Update/create/delete JS/TS @beacon[...] blocks for a single node.

    Mirrors the Python helper but uses JS/TS beacons and Tree-sitter outlines.
    """
    base_name, tags = split_name_and_tags(name)
    beacon_id = _extract_beacon_id_from_note(note)
    ast_qualname = _extract_ast_qualname_from_note(note)

    result: Dict[str, Any] = {
        "language": "js_ts",
        "file_path": file_path,
        "base_name": base_name,
        "tags": tags,
        "beacon_id": beacon_id,
        "ast_qualname": ast_qualname,
        "operation": "noop",
    }

    try:
        with open(file_path, "r", encoding="utf-8") as f:
            lines = f.read().splitlines()
    except Exception as e:  # noqa: BLE001
        result["error"] = f"failed_to_read_file: {e}"
        return result

    beacons = parse_js_beacon_blocks(lines)

    def _find_beacon_block_by_id(bid: str) -> Optional[tuple[int, int, int]]:
        bid = (bid or "").strip()
        if not bid:
            return None
        for b in beacons:
            if (b.get("id") or "").strip() != bid:
                continue
            cl = b.get("comment_line")
            if not isinstance(cl, int) or cl <= 0:
                continue
            # Walk forward to find the closing ']' line; allow for leading
            # '//' comment markers. As with Python, we require the metadata
            # body (after stripping comment sugar and whitespace) to be
            # exactly ']'.
            start_idx = cl - 1
            j = cl
            end_idx = start_idx
            while j <= len(lines):
                raw = lines[j - 1]
                stripped = raw.lstrip()
                if stripped.startswith("//"):
                    body = stripped[2:].lstrip()
                else:
                    body = stripped
                if body == "]":
                    end_idx = j - 1
                    break
                j += 1
            return start_idx, end_idx, cl
        return None

    def _build_beacon_block(
        bid: str,
        role: str,
        slice_labels: str,
        kind: str,
        show_span: Optional[bool],
        comment_text: Optional[str],
    ) -> list[str]:
        meta_lines = [
            "// @beacon[",
            f"//   id={bid},",
        ]
        if role:
            meta_lines.append(f"//   role={role},")
        if slice_labels:
            meta_lines.append(f"//   slice_labels={slice_labels},")
        if kind:
            meta_lines.append(f"//   kind={kind},")
        if show_span is not None:
            meta_lines.append(f"//   show_span={'true' if show_span else 'false'},")
        if comment_text:
            meta_lines.append(f"//   comment={comment_text},")
        meta_lines.append("// ]")
        return meta_lines

    # Case 1: beacon_id present in note (update existing or create from metadata).
    if beacon_id:
        role_val: str | None = None
        comment_val: str | None = None
        for line in (note or "").splitlines():
            stripped = line.strip()
            if stripped.startswith("role:"):
                role_val = stripped.split(":", 1)[1].strip()
            elif stripped.startswith("comment:") or stripped.startswith("comments:"):
                comment_val = stripped.split(":", 1)[1].strip()

        show_span_note = _extract_show_span_from_note(note)

        role_display = role_val or (beacon_id.split("@", 1)[0] if "@" in beacon_id else "")

        # Slice labels come **only** from Workflowy tags in the node name.
        extra_label_tokens = [t.lstrip("#") for t in tags]
        slice_labels_canon = (
            _canonicalize_slice_labels(",".join(extra_label_tokens), None)
            if extra_label_tokens
            else ""
        )

        block_span = _find_beacon_block_by_id(beacon_id)
        
        if block_span is not None:
            # Case 1a: UPDATE existing beacon on disk.
            start_idx, end_idx, _cl = block_span

            # Preserve existing kind (span vs ast) when updating an on-disk beacon.
            existing_kind = "ast"
            existing_show_span: Optional[bool] = None
            for b in beacons:
                if (b.get("id") or "").strip() != (beacon_id or "").strip():
                    continue
                k_val = (b.get("kind") or "").strip().lower()
                if k_val in {"ast", "span"}:
                    existing_kind = k_val
                if b.get("show_span_explicit"):
                    existing_show_span = bool(b.get("show_span"))
                break

            show_span_to_write: Optional[bool] = (
                show_span_note if show_span_note is not None else existing_show_span
            )

            new_block = _build_beacon_block(
                bid=beacon_id,
                role=role_display or "",
                slice_labels=slice_labels_canon,
                kind=existing_kind,
                show_span=show_span_to_write,
                comment_text=comment_val,
            )
            new_block = _indent_beacon_block(new_block, lines, start_idx)
            new_lines = lines[:start_idx] + new_block + lines[end_idx + 1 :]
            try:
                with open(file_path, "w", encoding="utf-8") as f:
                    f.write("\n".join(new_lines) + "\n")
            except Exception as e:  # noqa: BLE001
                result["error"] = f"failed_to_write_file: {e}"
                return result

            result.update(
                {
                    "operation": "updated_beacon",
                    "role": role_display,
                    "slice_labels": slice_labels_canon,
                    "comment": comment_val,
                }
            )
            return result
        else:
            # Case 1b: CREATE beacon from note metadata (beacon_id in note, not on disk).
            # Use AST_QUALNAME to find insertion point.
            target_line: Optional[int] = None
            if ast_qualname:
                try:
                    outline_nodes = parse_js_ts_outline(file_path)
                except Exception:
                    outline_nodes = []

                if outline_nodes:
                    def _iter_nodes(nodes_list: list[dict[str, Any]]):
                        for n in nodes_list:
                            if isinstance(n, dict):
                                yield n
                                for ch in n.get("children") or []:
                                    if isinstance(ch, dict):
                                        yield from _iter_nodes([ch])

                    for n in _iter_nodes(outline_nodes):
                        if n.get("ast_qualname") == ast_qualname:
                            ln = n.get("orig_lineno_start_unused")
                            if isinstance(ln, int) and ln > 0:
                                target_line = ln
                                break

            if not isinstance(target_line, int) or target_line <= 0 or target_line > len(lines):
                insert_idx = 0
            else:
                insert_idx = target_line - 1

            new_block = _build_beacon_block(
                bid=beacon_id,
                role=role_display or "",
                slice_labels=slice_labels_canon,
                kind="ast",
                show_span=show_span_note,
                comment_text=comment_val,
            )
            new_block = _indent_beacon_block(new_block, lines, insert_idx)
            new_lines = lines[:insert_idx] + new_block + lines[insert_idx:]
            try:
                with open(file_path, "w", encoding="utf-8") as f:
                    f.write("\n".join(new_lines) + "\n")
            except Exception as e:  # noqa: BLE001
                result["error"] = f"failed_to_write_file: {e}"
                return result

            result.update(
                {
                    "operation": "created_beacon",
                    "beacon_id": beacon_id,
                    "role": role_display,
                    "slice_labels": slice_labels_canon,
                    "comment": comment_val,
                }
            )
            return result

    # Helper: delete beacon(s) for this AST_QUALNAME using JS/TS Cartographer outline.
    #
    # As with Python, we fail closed: ambiguous or missing mappings result in
    # no deletion.
    def _delete_beacon_for_ast_qualname_js_ts(target_ast_qualname: str) -> Optional[str]:
        try:
            outline_nodes = parse_js_ts_outline(file_path)
        except Exception as e:  # noqa: BLE001
            print(
                "[CARTOGRAPHER] update_beacon_from_node_js_ts delete-abort "
                f"(file_path={file_path!r}, ast_qualname={target_ast_qualname!r}, error={e!r})",
                file=sys.stderr,
            )
            return None

        if not outline_nodes:
            return None

        matches: list[dict[str, Any]] = [
            n
            for n in _iter_ast_outline_nodes(outline_nodes)
            if n.get("ast_qualname") == target_ast_qualname
        ]
        if len(matches) != 1:
            print(
                "[CARTOGRAPHER] update_beacon_from_node_js_ts delete-abort "
                f"(file_path={file_path!r}, ast_qualname={target_ast_qualname!r}, "
                f"matches={len(matches)})",
                file=sys.stderr,
            )
            return None

        node = matches[0]
        node_note = node.get("note") or ""
        if "BEACON (" not in node_note:
            return None

        bid = _extract_beacon_id_from_note(node_note)
        if not bid:
            return None

        span = _find_beacon_block_by_id(bid)
        if span is None:
            return None

        start_idx, end_idx, _cl = span
        new_lines = lines[:start_idx] + lines[end_idx + 1 :]
        try:
            with open(file_path, "w", encoding="utf-8") as f:
                f.write("\n".join(new_lines) + "\n")
        except Exception as e:  # noqa: BLE001
            result["error"] = f"failed_to_write_file: {e}"
            return None

        return bid

    # Case 1c: DELETE beacon when note has no BEACON metadata and no tags.
    # This covers the common JS/TS F12 path where F12-per-node originally created
    # a beacon for this AST_QUALNAME and the user later deletes the tags and
    # BEACON block from the Workflowy note (leaving only AST_QUALNAME).
    if ast_qualname and not tags and not beacon_id:
        deleted_id = _delete_beacon_for_ast_qualname_js_ts(ast_qualname)
        if deleted_id:
            result.update(
                {
                    "operation": "deleted_beacon",
                    "beacon_id": deleted_id,
                    "role": ast_qualname,
                    "slice_labels": "",
                }
            )
            return result

    # Case 2: create from AST_QUALNAME + tags.
    if ast_qualname and tags:
        # Build a synthetic id with a hash suffix for collision resistance.
        hash_suffix = _generate_auto_beacon_hash()
        simple_id = f"auto-beacon@{ast_qualname}-{hash_suffix}"
        role_display = ast_qualname

        # Slice labels come **only** from Workflowy tags; we do not auto-derive
        # additional labels from role/id/AST_QUALNAME.
        extra_label_tokens = [t.lstrip("#") for t in tags]
        slice_labels_canon = (
            _canonicalize_slice_labels(",".join(extra_label_tokens), None)
            if extra_label_tokens
            else ""
        )

        target_line: Optional[int] = None
        try:
            outline_nodes = parse_js_ts_outline(file_path)
        except Exception as e:
            outline_nodes = []

        if outline_nodes:
            def _iter_nodes(nodes_list: list[dict[str, Any]]):
                for n in nodes_list:
                    if isinstance(n, dict):
                        yield n
                        for ch in n.get("children") or []:
                            if isinstance(ch, dict):
                                yield from _iter_nodes([ch])

            for n in _iter_nodes(outline_nodes):
                if n.get("ast_qualname") == ast_qualname:
                    ln = n.get("orig_lineno_start_unused")
                    if isinstance(ln, int) and ln > 0:
                        target_line = ln
                        break

        if not isinstance(target_line, int) or target_line <= 0 or target_line > len(lines):
            insert_idx = 0
        else:
            insert_idx = target_line - 1

        new_block = _build_beacon_block(
            bid=simple_id,
            role=role_display,
            slice_labels=slice_labels_canon,
            kind="ast",
            show_span=None,
            comment_text=None,
        )
        new_block = _indent_beacon_block(new_block, lines, insert_idx)
        new_lines = lines[:insert_idx] + new_block + lines[insert_idx:]
        try:
            with open(file_path, "w", encoding="utf-8") as f:
                f.write("\n".join(new_lines) + "\n")
        except Exception as e:  # noqa: BLE001
            result["error"] = f"failed_to_write_file: {e}"
            return result

        result.update(
            {
                "operation": "created_beacon",
                "beacon_id": simple_id,
                "role": role_display,
                "slice_labels": slice_labels_canon,
            }
        )
        return result

    return result


# @beacon[
#   id=auto-beacon@update_beacon_from_node_vue,
#   role=update_beacon_from_node_vue,
#   slice_labels=f9-f12-handlers,ra-reconcile,
#   kind=ast,
# ]
def update_beacon_from_node_vue(
    file_path: str,
    name: str,
    note: str,
) -> Dict[str, Any]:
    """Update/create/delete Vue (.vue) @beacon[...] blocks for a single node.

    MVP behavior:
    - Script blocks: supports AST + SPAN beacons (JS/TS syntax inside <script>).\
      AST anchoring uses AST_QUALNAME with a vue:script{N}: prefix.
    - Template blocks: SPAN beacons only (HTML comment syntax).
    - Style blocks: SPAN beacons only (/* ... */ syntax).

    This helper performs on-disk edits ONLY.
    """
    base_name, tags = split_name_and_tags(name)
    beacon_id = _extract_beacon_id_from_note(note)
    ast_qualname = _extract_ast_qualname_from_note(note)

    result: Dict[str, Any] = {
        "language": "vue",
        "file_path": file_path,
        "base_name": base_name,
        "tags": tags,
        "beacon_id": beacon_id,
        "ast_qualname": ast_qualname,
        "operation": "noop",
    }

    if not _HAVE_TREE_SITTER:
        result["error"] = "tree_sitter_not_available"
        return result

    try:
        with open(file_path, "r", encoding="utf-8") as f:
            source_text = f.read()
        lines = source_text.splitlines()
    except Exception as e:  # noqa: BLE001
        result["error"] = f"failed_to_read_file: {e}"
        return result

    # Extract blocks with basic range metadata.
    source_bytes = source_text.encode("utf-8")
    try:
        parser = Parser(); parser.language = get_language("vue")  # type: ignore[operator]
        tree = parser.parse(source_bytes)
        root = tree.root_node
    except Exception as e:  # noqa: BLE001
        result["error"] = f"failed_to_parse_vue: {e}"
        return result

    blocks: list[dict[str, Any]] = []
    for ch in root.children:
        if ch.type not in {"template_element", "script_element", "style_element"}:
            continue
        start_tag = None
        raw_text = None
        end_tag = None
        for c2 in ch.children:
            if c2.type == "start_tag":
                start_tag = c2
            elif c2.type == "raw_text":
                raw_text = c2
            elif c2.type == "end_tag":
                end_tag = c2
        if start_tag is None:
            continue

        start_tag_text = source_bytes[start_tag.start_byte:start_tag.end_byte].decode("utf-8", errors="ignore")
        start_tag_compact = _vue_compact_start_tag_text(start_tag_text)

        if raw_text is not None:
            content_row0 = int(raw_text.start_point[0])
            content_text = source_bytes[raw_text.start_byte:raw_text.end_byte].decode("utf-8", errors="ignore")
            block_row1 = int(end_tag.end_point[0]) if end_tag is not None else int(raw_text.end_point[0])
        else:
            if end_tag is None:
                continue
            content_row0 = int(start_tag.end_point[0])
            content_text = source_bytes[start_tag.end_byte:end_tag.start_byte].decode("utf-8", errors="ignore")
            block_row1 = int(end_tag.end_point[0])

        blocks.append({
            "type": ch.type,
            "start_tag": start_tag_compact,
            "content_row0": content_row0,
            "raw_text": content_text,
            "block_row0": int(start_tag.start_point[0]),
            "block_row1": block_row1,
        })

    # Determine which block we're targeting.
    # Prefer explicit AST_QUALNAME prefix for scripts.
    target_script_ix: int | None = None
    if isinstance(ast_qualname, str) and ast_qualname.startswith("vue:script"):
        try:
            rest = ast_qualname[len("vue:script") :]
            ix_str = rest.split(":", 1)[0]
            target_script_ix = int(ix_str)
        except Exception:
            target_script_ix = None

    # If we have a note beacon id but no AST_QUALNAME, we don't know which section;
    # we fall back to searching the whole file for the id.

    def _write_lines(new_lines: list[str]) -> bool:
        try:
            with open(file_path, "w", encoding="utf-8") as f:
                f.write("\n".join(new_lines) + "\n")
            return True
        except Exception as e:  # noqa: BLE001
            result["error"] = f"failed_to_write_file: {e}"
            return False

    # ------------------------------
    # Helper: update an existing beacon block by id within a window.
    # ------------------------------
    def _update_block_in_window(
        *,
        window_lo: int,
        window_hi: int,
        comment_style: str,
        bid: str,
        role: str,
        slice_labels: str,
        kind: str,
        show_span: Optional[bool],
        comment_text: Optional[str],
    ) -> bool:
        """Update first matching @beacon[ id=...] block in [window_lo,window_hi] (1-based inclusive)."""

        # Find start line containing '@beacon['
        start_idx: int | None = None
        end_idx: int | None = None
        for i in range(max(1, window_lo), min(len(lines), window_hi) + 1):
            if "@beacon[" not in lines[i - 1]:
                continue
            # scan forward to the ']' terminator line
            j = i
            while j <= min(len(lines), window_hi):
                if "]" in lines[j - 1]:
                    break
                j += 1
            if j > min(len(lines), window_hi):
                continue

            block_text = "\n".join(lines[i - 1 : j])
            if f"id={bid}" not in block_text and f"id: {bid}" not in block_text:
                continue
            start_idx = i - 1
            end_idx = j - 1
            break

        if start_idx is None or end_idx is None:
            return False

        if comment_style == "js_line":
            new_block = [
                "// @beacon[",
                f"//   id={bid},",
            ]
            if role:
                new_block.append(f"//   role={role},")
            if slice_labels:
                new_block.append(f"//   slice_labels={slice_labels},")
            if kind:
                new_block.append(f"//   kind={kind},")
            if show_span is not None:
                new_block.append(f"//   show_span={'true' if show_span else 'false'},")
            if comment_text:
                new_block.append(f"//   comment={comment_text},")
            new_block.append("// ]")
        elif comment_style == "html":
            new_block = [
                "<!--",
                "@beacon[",
                f"  id={bid},",
            ]
            if role:
                new_block.append(f"  role={role},")
            if slice_labels:
                new_block.append(f"  slice_labels={slice_labels},")
            if kind:
                new_block.append(f"  kind={kind},")
            if show_span is not None:
                new_block.append(f"  show_span={'true' if show_span else 'false'},")
            if comment_text:
                new_block.append(f"  comment={comment_text},")
            new_block.append("]")
            new_block.append("-->")
        else:  # css_block
            new_block = [
                "/* @beacon[",
                f"   id={bid},",
            ]
            if role:
                new_block.append(f"   role={role},")
            if slice_labels:
                new_block.append(f"   slice_labels={slice_labels},")
            if kind:
                new_block.append(f"   kind={kind},")
            if show_span is not None:
                new_block.append(f"   show_span={'true' if show_span else 'false'},")
            if comment_text:
                new_block.append(f"   comment={comment_text},")
            new_block.append("] */")

        new_block = _indent_beacon_block(new_block, lines, start_idx)
        new_lines = lines[:start_idx] + new_block + lines[end_idx + 1 :]
        return _write_lines(new_lines)

    # ------------------------------
    # Case 1: Update/create based on explicit beacon_id in note
    # ------------------------------
    if beacon_id:
        role_val: str | None = None
        comment_val: str | None = None
        kind_val: str = "ast"
        for ln in (note or "").splitlines():
            s = ln.strip()
            if s.startswith("role:"):
                role_val = s.split(":", 1)[1].strip()
            elif s.startswith("comment:") or s.startswith("comments:"):
                comment_val = s.split(":", 1)[1].strip()
            elif s.startswith("kind:"):
                kv = s.split(":", 1)[1].strip().lower()
                if kv in {"ast", "span"}:
                    kind_val = kv

        show_span_note = _extract_show_span_from_note(note)

        extra_label_tokens = [t.lstrip("#") for t in tags]
        slice_labels_canon = (
            _canonicalize_slice_labels(",".join(extra_label_tokens), None)
            if extra_label_tokens
            else ""
        )

        role_display = role_val or (beacon_id.split("@", 1)[0] if "@" in beacon_id else "")

        # Try script blocks first (JS line comment). If target_script_ix is known,
        # restrict to that script block; else try all scripts.
        script_blocks = [b for b in blocks if b.get("type") == "script_element"]
        if target_script_ix is not None and 0 <= target_script_ix < len(script_blocks):
            script_blocks = [script_blocks[target_script_ix]]

        for sb in script_blocks:
            lo = int(sb.get("block_row0") or 0) + 1
            hi = int(sb.get("block_row1") or 0) + 1
            if _update_block_in_window(
                window_lo=lo,
                window_hi=hi,
                comment_style="js_line",
                bid=beacon_id,
                role=role_display,
                slice_labels=slice_labels_canon,
                kind=kind_val,
                show_span=show_span_note,
                comment_text=comment_val,
            ):
                # For script blocks, reuse JS/TS cache note semantics.
                result["language"] = "js_ts"
                result.update({
                    "operation": "updated_beacon",
                    "role": role_display,
                    "slice_labels": slice_labels_canon,
                    "comment": comment_val,
                })
                return result

        # Template blocks (HTML comments)
        for tb in [b for b in blocks if b.get("type") == "template_element"]:
            lo = int(tb.get("block_row0") or 0) + 1
            hi = int(tb.get("block_row1") or 0) + 1
            if _update_block_in_window(
                window_lo=lo,
                window_hi=hi,
                comment_style="html",
                bid=beacon_id,
                role=role_display,
                slice_labels=slice_labels_canon,
                kind="span",
                show_span=show_span_note,
                comment_text=comment_val,
            ):
                result.update({
                    "operation": "updated_beacon",
                    "role": role_display,
                    "slice_labels": slice_labels_canon,
                    "comment": comment_val,
                })
                return result

        # Style blocks (CSS block comments)
        for sb in [b for b in blocks if b.get("type") == "style_element"]:
            lo = int(sb.get("block_row0") or 0) + 1
            hi = int(sb.get("block_row1") or 0) + 1
            if _update_block_in_window(
                window_lo=lo,
                window_hi=hi,
                comment_style="css_block",
                bid=beacon_id,
                role=role_display,
                slice_labels=slice_labels_canon,
                kind="span",
                show_span=show_span_note,
                comment_text=comment_val,
            ):
                result.update({
                    "operation": "updated_beacon",
                    "role": role_display,
                    "slice_labels": slice_labels_canon,
                    "comment": comment_val,
                })
                return result

        # If not found, fall back to "create" for scripts when AST_QUALNAME is present.
        if ast_qualname and target_script_ix is not None and target_script_ix < len([b for b in blocks if b.get("type") == "script_element"]):
            # handled by create-from-ast path below
            pass
        else:
            result.update({"operation": "noop", "error": "beacon_id_not_found_on_disk"})
            return result

    # ------------------------------
    # Case 2: Create from AST_QUALNAME + tags (script AST only)
    # ------------------------------
    if ast_qualname and tags:
        if target_script_ix is None:
            # best-effort: default to first script
            target_script_ix = 0

        script_blocks_all = [b for b in blocks if b.get("type") == "script_element"]
        if not script_blocks_all or target_script_ix < 0 or target_script_ix >= len(script_blocks_all):
            result["error"] = "no_script_block_found"
            return result

        sb = script_blocks_all[target_script_ix]
        start_tag_compact = str(sb.get("start_tag") or "").strip().lower()
        lang = "javascript"
        if "lang=\"ts\"" in start_tag_compact or "lang='ts'" in start_tag_compact or "lang=ts" in start_tag_compact:
            lang = "typescript"
        if "lang=\"tsx\"" in start_tag_compact or "lang='tsx'" in start_tag_compact or "lang=tsx" in start_tag_compact:
            lang = "tsx"

        content_row0 = int(sb.get("content_row0") or 0)
        raw_text_str = str(sb.get("raw_text") or "")

        # Ensure our vue prefix exists for matching.
        vue_prefix = f"vue:script{target_script_ix}"

        outline_nodes = _parse_js_ts_outline_from_source(
            source_text=raw_text_str,
            file_path=file_path,
            language_name=lang,
            line_offset0=content_row0,
            vue_qual_prefix=vue_prefix,
        )

        # Find target AST node line
        target_line: Optional[int] = None
        for n in _iter_ast_outline_nodes(outline_nodes):
            if n.get("ast_qualname") == ast_qualname:
                ln = n.get("orig_lineno_start_unused")
                if isinstance(ln, int) and ln > 0:
                    target_line = ln
                    break

        if not isinstance(target_line, int):
            result["error"] = "ast_qualname_not_found_in_script"
            return result

        # Build synthetic id
        hash_suffix = _generate_auto_beacon_hash()
        simple_id = f"auto-beacon@{ast_qualname}-{hash_suffix}"
        role_display = ast_qualname

        extra_label_tokens = [t.lstrip("#") for t in tags]
        slice_labels_canon = (
            _canonicalize_slice_labels(",".join(extra_label_tokens), None)
            if extra_label_tokens
            else ""
        )

        insert_idx = target_line - 1
        new_block = [
            "// @beacon[",
            f"//   id={simple_id},",
        ]
        if role_display:
            new_block.append(f"//   role={role_display},")
        if slice_labels_canon:
            new_block.append(f"//   slice_labels={slice_labels_canon},")
        new_block.append("//   kind=ast,")
        new_block.append("// ]")
        new_block = _indent_beacon_block(new_block, lines, insert_idx)
        new_lines = lines[:insert_idx] + new_block + lines[insert_idx:]

        if not _write_lines(new_lines):
            return result

        # For script blocks, reuse JS/TS cache note semantics.
        result["language"] = "js_ts"
        result.update({
            "operation": "created_beacon",
            "beacon_id": simple_id,
            "role": role_display,
            "slice_labels": slice_labels_canon,
        })
        return result

    # ------------------------------
    # Case 3: Delete existing beacon when AST_QUALNAME present but note has no BEACON metadata and no tags.
    # ------------------------------
    if ast_qualname and not tags and not beacon_id:
        # Use the current Cartographer mapping to find the beacon id, then delete it.
        try:
            outline = parse_vue_outline(file_path)
        except Exception:
            outline = []

        # Find matching script node
        found_id: str | None = None
        def _iter(nodes):
            for n in nodes or []:
                if isinstance(n, dict):
                    yield n
                    for ch in n.get("children") or []:
                        yield from _iter([ch])

        for n in _iter(outline):
            if n.get("ast_qualname") != ast_qualname:
                continue
            nn = str(n.get("note") or "")
            if "BEACON (JS/TS AST)" not in nn:
                continue
            for line in nn.splitlines():
                s = line.strip()
                if s.startswith("id:"):
                    found_id = s.split(":", 1)[1].strip()
                    break
            if found_id:
                break

        if not found_id:
            return result

        # Delete by removing the first matching block containing id=found_id.
        # Best-effort: scan entire file.
        for i in range(1, len(lines) + 1):
            if "@beacon[" not in lines[i - 1]:
                continue
            j = i
            while j <= len(lines):
                if "]" in lines[j - 1]:
                    break
                j += 1
            if j > len(lines):
                continue
            block_text = "\n".join(lines[i - 1 : j])
            if f"id={found_id}" not in block_text:
                continue
            new_lines = lines[: i - 1] + lines[j:]
            if not _write_lines(new_lines):
                return result
            result.update({
                "operation": "deleted_beacon",
                "beacon_id": found_id,
                "role": ast_qualname,
                "slice_labels": "",
            })
            return result

    return result


# @beacon[
#   id=carto-js-ts@update_beacon_from_node_markdown,
#   role=carto-js-ts,
#   slice_labels=carto-js-ts,carto-js-ts-beacons,f9-f12-handlers,ra-reconcile,nexus-md-header-path,
#   kind=span,
# ]
# Markdown: update/create/delete a beacon for a single heading/beacon node
# based on Workflowy name/note fields. Uses MD_PATH to locate the heading
# and mirrors the Python/JS/TS behavior for slice_labels and comments.
def update_beacon_from_node_markdown(
    file_path: str,
    name: str,
    note: str,
) -> Dict[str, Any]:
    """Update/create/delete Markdown beacons for a single heading/beacon node.

    Uses MD_PATH to locate the heading and follows the same name-tag-only
    slice_labels semantics as the Python/JS/TS helpers.
    """
    base_name, tags = split_name_and_tags(name)
    beacon_id = _extract_beacon_id_from_note(note)
    md_path = _extract_md_path_from_note(note)

    result: Dict[str, Any] = {
        "language": "markdown",
        "file_path": file_path,
        "base_name": base_name,
        "tags": tags,
        "beacon_id": beacon_id,
        "md_path": md_path,
        "operation": "noop",
    }

    try:
        with open(file_path, "r", encoding="utf-8") as f:
            lines = f.read().splitlines()
    except Exception as e:  # noqa: BLE001
        result["error"] = f"failed_to_read_file: {e}"
        return result

    beacons = parse_markdown_beacon_blocks(lines)

    def _find_beacon_block_by_id(bid: str) -> Optional[tuple[int, int, int]]:
        bid = (bid or "").strip()
        if not bid:
            return None
        for b in beacons:
            if (b.get("id") or "").strip() != bid:
                continue
            cl = b.get("comment_line")
            if not isinstance(cl, int) or cl <= 0:
                continue
            # For Markdown, comment_line refers to the line containing '@beacon['.
            # We treat the block as everything from the first '<!--' before it
            # through the matching '-->' after it.
            start_idx = cl - 1
            # Walk backward to include the opening '<!--' if present.
            j = cl - 1
            while j >= 1:
                raw = lines[j - 1]
                if "<!--" in raw:
                    start_idx = j - 1
                    break
                if raw.strip():
                    break
                j -= 1
            # Walk forward to include the closing '-->'.
            j = cl
            end_idx = cl - 1
            while j <= len(lines):
                raw = lines[j - 1]
                end_idx = j - 1
                if "-->" in raw:
                    break
                j += 1
            return start_idx, end_idx, cl
        return None

    def _build_beacon_block(
        bid: str,
        role: str,
        slice_labels: str,
        kind: str,
        show_span: Optional[bool],
        comment_text: Optional[str],
    ) -> list[str]:
        meta_lines = [
            "<!--",
            "@beacon[",
            f"  id={bid},",
        ]
        if role:
            meta_lines.append(f"  role={role},")
        if slice_labels:
            meta_lines.append(f"  slice_labels={slice_labels},")
        if kind:
            meta_lines.append(f"  kind={kind},")
        if show_span is not None:
            meta_lines.append(f"  show_span={'true' if show_span else 'false'},")
        if comment_text:
            meta_lines.append(f"  comment={comment_text},")
        meta_lines.append(" ]")
        meta_lines.append("-->")
        return meta_lines

    # Case 1: beacon_id present in note (update existing or create from metadata).
    if beacon_id:
        role_val: str | None = None
        comment_val: str | None = None
        for line in (note or "").splitlines():
            stripped = line.strip()
            if stripped.startswith("role:"):
                role_val = stripped.split(":", 1)[1].strip()
            elif stripped.startswith("comment:") or stripped.startswith("comments:"):
                comment_val = stripped.split(":", 1)[1].strip()

        show_span_note = _extract_show_span_from_note(note)

        role_display = role_val or (beacon_id.split("@", 1)[0] if "@" in beacon_id else "")

        # Slice labels come **only** from Workflowy tags in the node name.
        extra_label_tokens = [t.lstrip("#") for t in tags]
        slice_labels_canon = (
            _canonicalize_slice_labels(",".join(extra_label_tokens), None)
            if extra_label_tokens
            else ""
        )

        block_span = _find_beacon_block_by_id(beacon_id)
        
        if block_span is not None:
            # Case 1a: UPDATE existing beacon on disk.
            start_idx, end_idx, _cl = block_span

            # Preserve existing kind (span vs ast) when updating an on-disk beacon.
            existing_kind = "ast"
            existing_show_span: Optional[bool] = None
            for b in beacons:
                if (b.get("id") or "").strip() != (beacon_id or "").strip():
                    continue
                k_val = (b.get("kind") or "").strip().lower()
                if k_val in {"ast", "span"}:
                    existing_kind = k_val
                if b.get("show_span_explicit"):
                    existing_show_span = bool(b.get("show_span"))
                break

            show_span_to_write: Optional[bool] = (
                show_span_note if show_span_note is not None else existing_show_span
            )

            new_block = _build_beacon_block(
                bid=beacon_id,
                role=role_display or "",
                slice_labels=slice_labels_canon,
                kind=existing_kind,
                show_span=show_span_to_write,
                comment_text=comment_val,
            )
            new_lines = lines[:start_idx] + new_block + lines[end_idx + 1 :]
            try:
                with open(file_path, "w", encoding="utf-8") as f:
                    f.write("\n".join(new_lines) + "\n")
            except Exception as e:  # noqa: BLE001
                result["error"] = f"failed_to_write_file: {e}"
                return result

            result.update(
                {
                    "operation": "updated_beacon",
                    "role": role_display,
                    "slice_labels": slice_labels_canon,
                    "comment": comment_val,
                }
            )
            return result
        else:
            # Case 1b: CREATE beacon from note metadata (beacon_id in note, not on disk).
            # For Markdown, locate the exact heading by MD_PATH and insert the
            # HTML beacon block immediately above it. Fall back to top-of-file
            # only when the heading cannot be resolved unambiguously.
            insert_idx = 0
            if md_path:
                resolved_idx = _find_markdown_heading_insert_idx(lines, md_path)
                if isinstance(resolved_idx, int) and resolved_idx >= 0:
                    insert_idx = resolved_idx

            new_block = _build_beacon_block(
                bid=beacon_id,
                role=role_display or "",
                slice_labels=slice_labels_canon,
                kind="ast",
                show_span=show_span_note,
                comment_text=comment_val,
            )
            new_block = _indent_beacon_block(new_block, lines, insert_idx)
            new_lines = lines[:insert_idx] + new_block + lines[insert_idx:]
            try:
                with open(file_path, "w", encoding="utf-8") as f:
                    f.write("\n".join(new_lines) + "\n")
            except Exception as e:  # noqa: BLE001
                result["error"] = f"failed_to_write_file: {e}"
                return result

            result.update(
                {
                    "operation": "created_beacon",
                    "beacon_id": beacon_id,
                    "role": role_display,
                    "slice_labels": slice_labels_canon,
                    "comment": comment_val,
                }
            )
            return result

    # Helper: delete beacon(s) for this MD_PATH using Cartographer Markdown outline.
    #
    # We intentionally fail closed: if we cannot unambiguously map the MD_PATH
    # to exactly one heading node (with a BEACON block in its note), we do not
    # delete anything.
    def _delete_beacon_for_md_path(md_path_lines: list[str]) -> Optional[str]:
        if not md_path_lines:
            return None

        try:
            outline_nodes = parse_markdown_structure(file_path)
        except Exception as e:  # noqa: BLE001
            print(
                "[CARTOGRAPHER] update_beacon_from_node_markdown delete-abort "
                f"(file_path={file_path!r}, md_path={md_path_lines!r}, error={e!r})",
                file=sys.stderr,
            )
            return None

        if not outline_nodes:
            return None

        def _iter_nodes(nodes_list: list[dict[str, Any]]):
            for n in nodes_list:
                if isinstance(n, dict):
                    yield n
                    for ch in n.get("children") or []:
                        if isinstance(ch, dict):
                            yield from _iter_nodes([ch])

        # Normalize target MD_PATH with header whitener to ignore decoration.
        target = [
            whiten_text_for_header_compare(line)
            for line in md_path_lines
            if isinstance(line, str) and line.strip()
        ]
        if not target:
            return None

        matches: list[dict[str, Any]] = []
        for n in _iter_nodes(outline_nodes):
            node_note = n.get("note") or ""
            node_md_path = _extract_md_path_from_note(node_note)
            if not node_md_path:
                continue
            node_norm = [
                whiten_text_for_header_compare(line)
                for line in node_md_path
                if isinstance(line, str) and line.strip()
            ]
            if node_norm == target:
                matches.append(n)

        if len(matches) != 1:
            print(
                "[CARTOGRAPHER] update_beacon_from_node_markdown delete-abort "
                f"(file_path={file_path!r}, md_path={md_path_lines!r}, matches={len(matches)})",
                file=sys.stderr,
            )
            return None

        node = matches[0]
        node_note = node.get("note") or ""
        if "BEACON (" not in node_note:
            return None

        bid = _extract_beacon_id_from_note(node_note)
        if not bid:
            return None

        # Re-open file after parse_markdown_structure (which may have rewritten it)
        # and compute fresh beacon locations.
        try:
            with open(file_path, "r", encoding="utf-8") as f:
                current_lines = f.read().splitlines()
        except Exception as e:  # noqa: BLE001
            result["error"] = f"failed_to_read_file: {e}"
            return None

        current_beacons = parse_markdown_beacon_blocks(current_lines)

        def _find_block_by_id(local_bid: str) -> Optional[tuple[int, int, int]]:
            local_bid = (local_bid or "").strip()
            if not local_bid:
                return None
            for b in current_beacons:
                if (b.get("id") or "").strip() != local_bid:
                    continue
                cl = b.get("comment_line")
                if not isinstance(cl, int) or cl <= 0:
                    continue
                # For Markdown, comment_line refers to the line containing '@beacon['.
                # We treat the block as everything from the first '<!--' before it
                # through the matching '-->' after it.
                start_idx = cl - 1
                # Walk backward to include the opening '<!--' if present.
                j = cl - 1
                while j >= 1:
                    raw = current_lines[j - 1]
                    if "<!--" in raw:
                        start_idx = j - 1
                        break
                    if raw.strip():
                        break
                    j -= 1
                # Walk forward to include the closing '-->'.
                j = cl
                end_idx = cl - 1
                while j <= len(current_lines):
                    raw = current_lines[j - 1]
                    end_idx = j - 1
                    if "-->" in raw:
                        break
                    j += 1
                return start_idx, end_idx, cl
            return None

        span = _find_block_by_id(bid)
        if span is None:
            return None

        start_idx, end_idx, _cl = span
        new_lines = current_lines[:start_idx] + current_lines[end_idx + 1 :]
        try:
            with open(file_path, "w", encoding="utf-8") as f:
                f.write("\n".join(new_lines) + "\n")
        except Exception as e:  # noqa: BLE001
            result["error"] = f"failed_to_write_file: {e}"
            return None

        return bid

    # Case 1c: DELETE beacon when note has no BEACON metadata and no tags.
    # This covers the common Markdown F12 path where F12-per-node originally created
    # a beacon block for this MD_PATH and the user later deletes the tags and
    # BEACON block from the Workflowy note (leaving only MD_PATH).
    if md_path and not tags and not beacon_id:
        deleted_id = _delete_beacon_for_md_path(md_path)
        if deleted_id:
            result.update(
                {
                    "operation": "deleted_beacon",
                    "beacon_id": deleted_id,
                    "role": (md_path[0] if md_path else "md"),
                    "slice_labels": "",
                }
            )
            return result

    # Case 2: create from MD_PATH + tags.
    if md_path and tags:
        # Build a synthetic id with a random hash suffix. Unlike Python/JS,
        # Markdown beacons do not encode the heading name in the id; MD_PATH
        # is the structural anchor.
        heading = md_path[-1] if md_path else "md"
        hash_suffix = _generate_auto_beacon_hash() + _generate_auto_beacon_hash()
        simple_id = f"auto-beacon@{hash_suffix}"
        role_display = heading

        # Slice labels come **only** from Workflowy tags; we do not auto-derive
        # additional labels from heading text/MD_PATH.
        extra_label_tokens = [t.lstrip("#") for t in tags]
        slice_labels_canon = (
            _canonicalize_slice_labels(",".join(extra_label_tokens), None)
            if extra_label_tokens
            else ""
        )

        # Insert the beacon block directly above the target heading when
        # possible; fall back to top-of-file only when MD_PATH cannot be
        # resolved unambiguously in the current Markdown file.
        insert_idx = 0
        resolved_idx = _find_markdown_heading_insert_idx(lines, md_path)
        if isinstance(resolved_idx, int) and resolved_idx >= 0:
            insert_idx = resolved_idx
        new_block = _build_beacon_block(
            bid=simple_id,
            role=role_display,
            slice_labels=slice_labels_canon,
            kind="ast",
            show_span=None,
            comment_text=None,
        )
        new_block = _indent_beacon_block(new_block, lines, insert_idx)
        new_lines = lines[:insert_idx] + new_block + lines[insert_idx:]
        try:
            with open(file_path, "w", encoding="utf-8") as f:
                f.write("\n".join(new_lines) + "\n")
        except Exception as e:  # noqa: BLE001
            result["error"] = f"failed_to_write_file: {e}"
            return result

        result.update(
            {
                "operation": "created_beacon",
                "beacon_id": simple_id,
                "role": role_display,
                "slice_labels": slice_labels_canon,
            }
        )
        return result

    return result


# @beacon[
#   id=auto-beacon@update_beacon_from_node_sql-eybf,
#   role=update_beacon_from_node_sql,
#   slice_labels=f9-f12-handlers,ra-reconcile,
#   kind=ast,
# ]
def update_beacon_from_node_sql(
    file_path: str,
    name: str,
    note: str,
) -> Dict[str, Any]:
    """Update an existing SQL span beacon's metadata for a single node.

    Currently supports updating role/slice_labels/comment for an existing
    @beacon[...] block identified by id=... in the Workflowy note.
    """
    base_name, tags = split_name_and_tags(name)
    beacon_id = _extract_beacon_id_from_note(note)

    result: Dict[str, Any] = {
        "language": "sql",
        "file_path": file_path,
        "base_name": base_name,
        "tags": tags,
        "beacon_id": beacon_id,
        "operation": "noop",
    }

    if not beacon_id:
        return result

    try:
        with open(file_path, "r", encoding="utf-8") as f:
            lines = f.read().splitlines()
    except Exception as e:  # noqa: BLE001
        result["error"] = f"failed_to_read_file: {e}"
        return result

    # Use robust parser
    beacons = parse_sql_beacon_blocks(lines)

    existing_show_span: Optional[bool] = None
    for b in beacons:
        if (b.get("id") or "").strip() != (beacon_id or "").strip():
            continue
        if b.get("show_span_explicit"):
            existing_show_span = bool(b.get("show_span"))
        break

    # Derive role/comment from note; slice_labels from Workflowy name tags only.
    role_val: str | None = None
    comment_val: str | None = None
    for line in (note or "").splitlines():
        stripped = line.strip()
        if stripped.startswith("role:"):
            role_val = stripped.split(":", 1)[1].strip()
        elif stripped.startswith("comment:") or stripped.startswith("comments:"):
            comment_val = stripped.split(":", 1)[1].strip()

    show_span_note = _extract_show_span_from_note(note)
    show_span_to_write: Optional[bool] = (
        show_span_note if show_span_note is not None else existing_show_span
    )

    role_display = role_val or (beacon_id.split("@", 1)[0] if "@" in beacon_id else "")

    extra_label_tokens = [t.lstrip("#") for t in tags]
    slice_labels_canon = (
        _canonicalize_slice_labels(",".join(extra_label_tokens), None)
        if extra_label_tokens
        else ""
    )

    def _find_beacon_block_by_id(bid: str) -> Optional[tuple[int, int, str]]:
        bid = (bid or "").strip()
        if not bid:
            return None
        for b in beacons:
            if (b.get("id") or "").strip() != bid:
                continue
            cl = b.get("comment_line")
            if not isinstance(cl, int) or cl <= 0:
                continue
            
            # SQL comments start with '--'
            start_idx = cl - 1
            j = cl
            end_idx = start_idx
            existing_kind = (b.get("kind") or "span").strip().lower()

            while j <= len(lines):
                if j > len(lines):
                    break
                raw = lines[j - 1]
                stripped = raw.lstrip()
                # Careful with SQL comments '--'
                if stripped.startswith("--"):
                    body = stripped[2:].lstrip()
                else:
                    body = stripped
                
                if body == "]":
                    end_idx = j - 1
                    break
                j += 1
            
            return start_idx, end_idx, existing_kind
        return None

    span = _find_beacon_block_by_id(beacon_id)
    if span is None:
        return result

    start_idx, end_idx, existing_kind = span

    def _build_beacon_block(
        bid: str,
        role: str,
        slice_labels: str,
        kind: str,
        show_span: Optional[bool],
        comment_text: Optional[str],
    ) -> list[str]:
        meta_lines = [
            "-- @beacon[",
            f"--   id={bid},",
        ]
        if role:
            meta_lines.append(f"--   role={role},")
        if slice_labels:
            meta_lines.append(f"--   slice_labels={slice_labels},")
        if kind:
            meta_lines.append(f"--   kind={kind},")
        if show_span is not None:
            meta_lines.append(f"--   show_span={'true' if show_span else 'false'},")
        if comment_text:
            meta_lines.append(f"--   comment={comment_text},")
        meta_lines.append("-- ]")
        return meta_lines

    new_block = _build_beacon_block(
        bid=beacon_id,
        role=role_display or "",
        slice_labels=slice_labels_canon,
        kind=existing_kind,
        show_span=show_span_to_write,
        comment_text=comment_val,
    )
    new_block = _indent_beacon_block(new_block, lines, start_idx)
    new_lines = lines[:start_idx] + new_block + lines[end_idx + 1 :]

    try:
        with open(file_path, "w", encoding="utf-8") as f:
            f.write("\n".join(new_lines) + "\n")
    except Exception as e:  # noqa: BLE001
        result["error"] = f"failed_to_write_file: {e}"
        return result

    result.update(
        {
            "operation": "updated_beacon",
            "role": role_display,
            "slice_labels": slice_labels_canon,
            "comment": comment_val,
        }
    )
    return result


# @beacon[
#   id=auto-beacon@update_beacon_from_node_shell-vult,
#   role=update_beacon_from_node_shell,
#   slice_labels=f9-f12-handlers,ra-reconcile,
#   kind=ast,
# ]
def update_beacon_from_node_shell(
    file_path: str,
    name: str,
    note: str,
) -> Dict[str, Any]:
    """Update an existing shell span beacon's metadata for a single node."""

    base_name, tags = split_name_and_tags(name)
    beacon_id = _extract_beacon_id_from_note(note)

    result: Dict[str, Any] = {
        "language": "shell",
        "file_path": file_path,
        "base_name": base_name,
        "tags": tags,
        "beacon_id": beacon_id,
        "operation": "noop",
    }

    if not beacon_id:
        return result

    try:
        with open(file_path, "r", encoding="utf-8") as f:
            lines = f.read().splitlines()
    except Exception as e:  # noqa: BLE001
        result["error"] = f"failed_to_read_file: {e}"
        return result

    # Use robust parser instead of manual scan
    beacons = parse_sh_beacon_blocks(lines)

    existing_show_span: Optional[bool] = None
    for b in beacons:
        if (b.get("id") or "").strip() != (beacon_id or "").strip():
            continue
        if b.get("show_span_explicit"):
            existing_show_span = bool(b.get("show_span"))
        break

    def _find_beacon_block_by_id(bid: str) -> Optional[tuple[int, int, str]]:
        bid = (bid or "").strip()
        if not bid:
            return None
        for b in beacons:
            if (b.get("id") or "").strip() != bid:
                continue
            cl = b.get("comment_line")
            if not isinstance(cl, int) or cl <= 0:
                continue
            
            # Find the closing ']' line.
            # Shell comments start with '#'.
            start_idx = cl - 1
            j = cl
            end_idx = start_idx
            existing_kind = (b.get("kind") or "span").strip().lower()
            
            while j <= len(lines):
                if j > len(lines): 
                    break
                raw = lines[j - 1]
                stripped = raw.lstrip()
                if stripped.startswith("#"):
                    body = stripped.lstrip("#").lstrip()
                else:
                    # Should not happen in a valid block, but handle gracefully
                    body = stripped
                
                if body == "]":
                    end_idx = j - 1
                    break
                j += 1
                
            return start_idx, end_idx, existing_kind
        return None

    span = _find_beacon_block_by_id(beacon_id)
    if span is None:
        return result

    start_idx, end_idx, existing_kind = span

    role_val: str | None = None
    comment_val: str | None = None
    for line in (note or "").splitlines():
        stripped = line.strip()
        if stripped.startswith("role:"):
            role_val = stripped.split(":", 1)[1].strip()
        elif stripped.startswith("comment:") or stripped.startswith("comments:"):
            comment_val = stripped.split(":", 1)[1].strip()

    show_span_note = _extract_show_span_from_note(note)
    show_span_to_write: Optional[bool] = (
        show_span_note if show_span_note is not None else existing_show_span
    )

    role_display = role_val or (beacon_id.split("@", 1)[0] if "@" in beacon_id else "")

    extra_label_tokens = [t.lstrip("#") for t in tags]
    slice_labels_canon = (
        _canonicalize_slice_labels(",".join(extra_label_tokens), None)
        if extra_label_tokens
        else ""
    )

    def _build_beacon_block(
        bid: str,
        role: str,
        slice_labels: str,
        kind: str,
        show_span: Optional[bool],
        comment_text: Optional[str],
    ) -> list[str]:
        meta_lines = [
            "# @beacon[",
            f"#   id={bid},",
        ]
        if role:
            meta_lines.append(f"#   role={role},")
        if slice_labels:
            meta_lines.append(f"#   slice_labels={slice_labels},")
        if kind:
            meta_lines.append(f"#   kind={kind},")
        if show_span is not None:
            meta_lines.append(f"#   show_span={'true' if show_span else 'false'},")
        if comment_text:
            meta_lines.append(f"#   comment={comment_text},")
        meta_lines.append("# ]")
        return meta_lines

    new_block = _build_beacon_block(
        bid=beacon_id,
        role=role_display or "",
        slice_labels=slice_labels_canon,
        kind=existing_kind,
        show_span=show_span_to_write,
        comment_text=comment_val,
    )
    new_block = _indent_beacon_block(new_block, lines, start_idx)
    new_lines = lines[:start_idx] + new_block + lines[end_idx + 1 :]

    try:
        with open(file_path, "w", encoding="utf-8") as f:
            f.write("\n".join(new_lines) + "\n")
    except Exception as e:  # noqa: BLE001
        result["error"] = f"failed_to_write_file: {e}"
        return result

    result.update(
        {
            "operation": "updated_beacon",
            "role": role_display,
            "slice_labels": slice_labels_canon,
            "comment": comment_val,
        }
    )
    return result


# @beacon[
#   id=auto-beacon@update_beacon_from_node_yaml-ykv1,
#   role=update_beacon_from_node_yaml,
#   slice_labels=f9-f12-handlers,ra-reconcile,
#   kind=ast,
# ]
def update_beacon_from_node_yaml(
    file_path: str,
    name: str,
    note: str,
) -> Dict[str, Any]:
    """Update an existing YAML span beacon's metadata for a single node."""

    base_name, tags = split_name_and_tags(name)
    beacon_id = _extract_beacon_id_from_note(note)

    result: Dict[str, Any] = {
        "language": "yaml",
        "file_path": file_path,
        "base_name": base_name,
        "tags": tags,
        "beacon_id": beacon_id,
        "operation": "noop",
    }

    if not beacon_id:
        return result

    try:
        with open(file_path, "r", encoding="utf-8") as f:
            lines = f.read().splitlines()
    except Exception as e:  # noqa: BLE001
        result["error"] = f"failed_to_read_file: {e}"
        return result

    # Use robust parser
    beacons = parse_yaml_beacon_blocks(lines)

    existing_show_span: Optional[bool] = None
    for b in beacons:
        if (b.get("id") or "").strip() != (beacon_id or "").strip():
            continue
        if b.get("show_span_explicit"):
            existing_show_span = bool(b.get("show_span"))
        break

    def _find_beacon_block_by_id(bid: str) -> Optional[tuple[int, int, str]]:
        bid = (bid or "").strip()
        if not bid:
            return None
        for b in beacons:
            if (b.get("id") or "").strip() != bid:
                continue
            cl = b.get("comment_line")
            if not isinstance(cl, int) or cl <= 0:
                continue

            # YAML comments start with '#' (same as shell/python)
            start_idx = cl - 1
            j = cl
            end_idx = start_idx
            existing_kind = (b.get("kind") or "span").strip().lower()

            while j <= len(lines):
                if j > len(lines):
                    break
                raw = lines[j - 1]
                stripped = raw.lstrip()
                if stripped.startswith("#"):
                    body = stripped.lstrip("#").lstrip()
                else:
                    body = stripped
                
                if body == "]":
                    end_idx = j - 1
                    break
                j += 1
            
            return start_idx, end_idx, existing_kind
        return None

    span = _find_beacon_block_by_id(beacon_id)
    if span is None:
        return result

    start_idx, end_idx, existing_kind = span

    role_val: str | None = None
    comment_val: str | None = None
    for line in (note or "").splitlines():
        stripped = line.strip()
        if stripped.startswith("role:"):
            role_val = stripped.split(":", 1)[1].strip()
        elif stripped.startswith("comment:") or stripped.startswith("comments:"):
            comment_val = stripped.split(":", 1)[1].strip()

    show_span_note = _extract_show_span_from_note(note)
    show_span_to_write: Optional[bool] = (
        show_span_note if show_span_note is not None else existing_show_span
    )

    role_display = role_val or (beacon_id.split("@", 1)[0] if "@" in beacon_id else "")

    extra_label_tokens = [t.lstrip("#") for t in tags]
    slice_labels_canon = (
        _canonicalize_slice_labels(",".join(extra_label_tokens), None)
        if extra_label_tokens
        else ""
    )

    def _build_beacon_block(
        bid: str,
        role: str,
        slice_labels: str,
        kind: str,
        show_span: Optional[bool],
        comment_text: Optional[str],
    ) -> list[str]:
        meta_lines = [
            "# @beacon[",
            f"#   id={bid},",
        ]
        if role:
            meta_lines.append(f"#   role={role},")
        if slice_labels:
            meta_lines.append(f"#   slice_labels={slice_labels},")
        if kind:
            meta_lines.append(f"#   kind={kind},")
        if show_span is not None:
            meta_lines.append(f"#   show_span={'true' if show_span else 'false'},")
        if comment_text:
            meta_lines.append(f"#   comment={comment_text},")
        meta_lines.append("# ]")
        return meta_lines

    new_block = _build_beacon_block(
        bid=beacon_id,
        role=role_display or "",
        slice_labels=slice_labels_canon,
        kind=existing_kind,
        show_span=show_span_to_write,
        comment_text=comment_val,
    )
    new_block = _indent_beacon_block(new_block, lines, start_idx)
    new_lines = lines[:start_idx] + new_block + lines[end_idx + 1 :]

    try:
        with open(file_path, "w", encoding="utf-8") as f:
            f.write("\n".join(new_lines) + "\n")
    except Exception as e:  # noqa: BLE001
        result["error"] = f"failed_to_write_file: {e}"
        return result

    result.update(
        {
            "operation": "updated_beacon",
            "role": role_display,
            "slice_labels": slice_labels_canon,
            "comment": comment_val,
        }
    )
    return result


# @beacon[
#   id=auto-beacon@reconcile_trees-sbk1,
#   role=reconcile_trees,
#   slice_labels=ra-reconcile,
#   kind=ast,
# ]
def reconcile_trees(source_node: Dict[str, Any], ether_node: Dict[str, Any]) -> None:
    """
    Recursively match source nodes with ether nodes to preserve UUIDs.
    Modifies source_node in-place to add 'id' fields from ether_node.
    """
    # 1. Match self (if not root wrapper)
    if "id" in ether_node:
        source_node["id"] = ether_node["id"]
        
    # 2. Build map of Ether children by Name
    ether_children_map = {}
    if "children" in ether_node:
        for child in ether_node["children"]:
            # We match by Name. 
            # Limitation: If multiple siblings have same name, behavior is undefined (first match).
            # Workflowy allows duplicates, but code structures usually don't have duplicate classes/funcs in same scope.
            ether_children_map[child["name"]] = child
            
    # 3. Iterate Source children and try to match
    if "children" in source_node:
        for source_child in source_node["children"]:
            name = source_child["name"]
            if name in ether_children_map:
                # Match found! Recurse.
                reconcile_trees(source_child, ether_children_map[name])
                # Remove from map to handle duplicates/prevent re-matching? 
                # For now, let's leave it. Standard code shouldn't have dups.

# @beacon[
#   id=auto-beacon@load_existing_map-kat3,
#   role=load_existing_map,
#   slice_labels=f9-f12-handlers,ra-reconcile,
#   kind=ast,
# ]
def load_existing_map(file_path: str) -> Optional[Dict[str, Any]]:
    try:
        with open(file_path, 'r', encoding='utf-8') as f:
            data = json.load(f)
            # Handle NEXUS wrapper or raw node
            if "nodes" in data and isinstance(data["nodes"], list):
                # Wrapper format. Return the first root node if matches context?
                # Actually, usually we map to a single root.
                if len(data["nodes"]) > 0:
                    return data["nodes"][0]
            elif "name" in data:
                # Single node
                return data
            elif isinstance(data, list) and len(data) > 0:
                 return data[0]
    except Exception as e:
        print(f"⚠️ Failed to load existing map: {e}")
    return None


def validate_nonempty_names(node: Dict[str, Any], path: str = "root") -> Optional[str]:
    """Ensure all nodes in a NEXUS tree have non-empty, non-whitespace names.

    This enforces the same ETHER invariant used by the Workflowy MCP: any
    prospective node that will be woven into Workflowy must have a valid name.
    """
    name = node.get("name")
    if not isinstance(name, str) or not name.strip():
        return f"{path} has empty or whitespace-only 'name'"

    children = node.get("children") or []
    for idx, child in enumerate(children):
        child_label = child.get("name") or f"child[{idx}]"
        err = validate_nonempty_names(child, f"{path} -> {child_label}")
        if err:
            return err
    return None


# @beacon-close[
#   id=nmcv1@multilang-update-core,
# ]
# @beacon-close[
#   id=nmcv1@file-core,
# ]
if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="Map source code to NEXUS JSON.")
    parser.add_argument("path", help="Root directory to map")
    parser.add_argument("--parent-id", "-p", help="Target Workflowy Parent ID (for weaving)", default="00000000-0000-0000-0000-000000000000")
    parser.add_argument("--existing-map", "-e", help="Existing NEXUS JSON map (from Scry) for synchronization", default=None)
    parser.add_argument("--include", "-i", nargs="+", help="Whitelist of file extensions (e.g. .py .md .js)")
    parser.add_argument("--exclude", "-x", nargs="+", help="Blacklist of filename patterns (e.g. test_ venv)")
    parser.add_argument(
        "--nexus-tag",
        "-t",
        required=True,
        help="NEXUS tag; enchanted_terrain.json will be written under temp/nexus_runs/<timestamp>__<tag>/"
    )
    
    args = parser.parse_args()
    
    abs_path = os.path.abspath(args.path)
    print(f"🗺️ Mapping codebase at: {abs_path}")
    
    # Normalize extensions
    includes = [ext.lower() if ext.startswith('.') else f'.{ext.lower()}' for ext in args.include] if args.include else None
    
    nexus_tree = map_codebase(abs_path, include_exts=includes, exclude_patterns=args.exclude)

    # Validate newly generated tree: no blank or whitespace-only names
    err = validate_nonempty_names(nexus_tree)
    if err:
        print("❌ Generated codebase map contains invalid node names:")
        print(err)
        raise SystemExit(1)
    
    # Reconciliation Step
    if args.existing_map:
        print(f"🔄 Reconciling with existing map: {args.existing_map}")
        ether_root = load_existing_map(args.existing_map)
        if ether_root:
            # Ensure existing map also respects the non-empty-name invariant
            err_existing = validate_nonempty_names(ether_root)
            if err_existing:
                print("❌ Existing map contains invalid node names:")
                print(err_existing)
                raise SystemExit(1)

            # We assume nexus_tree matches the ether_root in structure (Root -> Children)
            # If names differ (e.g. root name change), we might fail to match top level,
            # but usually we care about children.
            # Use Cartographer-aware reconciliation so beacon/AST/MD_PATH anchors
            # drive ID preservation, with name-based matching as a fallback.
            reconcile_trees_cartographer(nexus_tree, ether_root)
            print("✅ Reconciliation complete (Cartographer-aware). UUIDs preserved.")
        else:
             print("⚠️ Existing map loaded but empty/invalid.")

    # Decide output location (always NEXUS run directory for this tag)
    # TIMESTAMP PREFIX: YYYY-MM-DD_HH-MM-SS__<tag>
    from datetime import datetime
    timestamp = datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
    timestamped_tag = f"{timestamp}__{args.nexus_tag}"
    
    project_root = os.path.dirname(os.path.abspath(__file__))
    nexus_runs_root = os.path.join(project_root, "temp", "nexus_runs")
    tag_dir = os.path.join(nexus_runs_root, timestamped_tag)
    os.makedirs(tag_dir, exist_ok=True)
    output_path = os.path.join(tag_dir, "enchanted_terrain.json")

    # Wrap in NEXUS metadata wrapper (enchanted terrain T2-style header)
    import datetime
    
    wrapper = {
        "export_root_id": args.parent_id,
        "export_root_name": nexus_tree["name"],
        "export_timestamp": datetime.datetime.now().isoformat(),
        "export_root_children_status": "complete",
        "nodes": [nexus_tree],
    }
    
    with open(output_path, 'w', encoding='utf-8') as f:
        json.dump(wrapper, f, indent=2)
        
    print(f"✅ Codebase map generated at: {output_path}")