livepilot 1.9.9 → 1.9.12

package/mcp_server/tools/harmony.py

@@ -19,7 +19,10 @@ from . import _theory_engine as theory
 
 def _ensure_list(value: Any) -> list:
     if isinstance(value, str):
-        return json.loads(value)
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Invalid JSON in parameter: {exc}") from exc
     return value
 
 
@@ -168,8 +171,18 @@ def classify_progression(
     if len(chords) < 2:
         return {"error": "Need at least 2 chords to classify"}
 
+    # Normalize dict inputs like {"root": "F#", "quality": "minor"} to strings
+    normalized = []
+    for c in chords:
+        if isinstance(c, dict):
+            root = c.get("root", "")
+            quality = c.get("quality", "major")
+            normalized.append(f"{root} {quality}")
+        else:
+            normalized.append(str(c))
+
     try:
-        parsed = [harmony.parse_chord(c) for c in chords]
+        parsed = [harmony.parse_chord(c) for c in normalized]
     except ValueError as e:
         return {"error": str(e)}
 
@@ -198,7 +211,7 @@ def classify_progression(
         classification = names.get(clean, classification)
 
     return {
-        "chords": chords,
+        "chords": normalized,
         "transforms": transforms,
         "pattern": pattern,
         "classification": classification,

package/mcp_server/tools/midi_io.py

@@ -51,6 +51,22 @@ def _output_dir() -> Path:
     return d
 
 
+def _safe_output_path(directory: Path, filename: str) -> Path:
+    """Join *filename* to *directory* with path-traversal containment.
+
+    Strips directory components (``../../evil.mid`` → ``evil.mid``),
+    resolves the result, and verifies it is still inside *directory*.
+    Raises ``ValueError`` on any escape attempt.
+    """
+    safe_name = Path(filename).name          # strip directory components
+    if not safe_name:
+        raise ValueError(f"Invalid filename: {filename!r}")
+    out = (directory / safe_name).resolve()
+    if not str(out).startswith(str(directory.resolve())):
+        raise ValueError(f"Filename escapes output directory: {filename!r}")
+    return out
+
+
 def _validate_midi_path(file_path: str) -> Path:
     p = Path(file_path)
     if not p.exists():
@@ -112,7 +128,7 @@ def export_clip_midi(
     if not filename.endswith((".mid", ".midi")):
         filename += ".mid"
 
-    out_path = _output_dir() / filename
+    out_path = _safe_output_path(_output_dir(), filename)
 
     midi = MIDIFile(1)
     midi.addTempo(0, 0, tempo)
@@ -185,9 +201,11 @@ def import_midi_to_clip(
                 "clip_index": clip_index,
             })
             slot_has_clip = True
-        except AbletonConnectionError:
-            # Slot is empty — no clip to clear
-            pass
+        except AbletonConnectionError as exc:
+            msg = str(exc)
+            if "NOT_FOUND" not in msg and "STATE_ERROR" not in msg:
+                raise  # propagate INDEX_ERROR, TIMEOUT, connection failures
+            # Slot is empty (NOT_FOUND) or no clip (STATE_ERROR)
 
         if slot_has_clip:
             # Clip exists — clear its notes before importing

package/mcp_server/tools/notes.py

@@ -21,7 +21,10 @@ def _get_ableton(ctx: Context):
 def _ensure_list(value: Any) -> list:
     """Parse JSON strings into lists. MCP clients may serialize list params as strings."""
     if isinstance(value, str):
-        return json.loads(value)
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Invalid JSON in parameter: {exc}") from exc
     return value
 
 

package/mcp_server/tools/perception.py

@@ -34,11 +34,31 @@ _LOSSY_EXTS = {".mp3", ".m4a"}
 _MAX_FILE_SIZE = 500 * 1024 * 1024  # 500 MB
 
 
+def _normalize_audio_path(file_path: str) -> str:
+    """Convert Max-style HFS-ish paths into POSIX paths when possible."""
+    if len(file_path) >= 3 and file_path[1] == ":" and file_path[2] in ("/", "\\"):
+        return file_path
+
+    colon = file_path.find(":")
+    slash = file_path.find("/")
+    if colon <= 0 or (slash != -1 and colon > slash):
+        return file_path
+
+    rest = file_path[colon + 1:]
+    if ":" in rest:
+        rest = rest.replace(":", "/")
+    if not rest.startswith("/"):
+        rest = "/" + rest.lstrip("/\\")
+    return rest
+
+
 def _validate_audio(file_path: str, allow_mp3: bool = False) -> Optional[dict]:
     """Validate that a file exists, has a supported extension, and is < 500 MB.
 
     Returns None if valid, or an error dict if invalid.
     """
+    file_path = _normalize_audio_path(file_path)
+
     if not os.path.exists(file_path):
         return {"error": f"File not found: {file_path}", "code": "INVALID_PARAM"}
 
@@ -84,7 +104,8 @@ def analyze_loudness(
                 array (up to 100 points, mean-pooled).
 
     Returns:
-        On success: dict with integrated_lufs, true_peak_dbtp, rms_dbfs,
+        On success: dict with integrated_lufs, true_peak_dbtp (4x oversampled),
+        sample_peak_dbfs (raw sample peak, kept for backward compat), rms_dbfs,
         crest_factor_db, lra_lu, meets_streaming {spotify, apple, youtube, tidal},
         and optionally short_term_lufs.
         On error: {"error": ..., "code": ...}
@@ -97,6 +118,7 @@ def analyze_loudness(
         return {"error": "detail must be 'summary' or 'full'", "code": "INVALID_PARAM"}
 
     try:
+        file_path = _normalize_audio_path(file_path)
         return compute_loudness(file_path, detail=detail)
     except FileNotFoundError as exc:
         return {"error": str(exc), "code": "INVALID_PARAM"}
@@ -135,6 +157,7 @@ def analyze_spectrum_offline(
         return {"error": "hop_length must be between 1 and n_fft", "code": "INVALID_PARAM"}
 
     try:
+        file_path = _normalize_audio_path(file_path)
         return compute_spectral(file_path, n_fft=n_fft, hop_length=hop_length)
     except FileNotFoundError as exc:
         return {"error": str(exc), "code": "INVALID_PARAM"}
@@ -176,6 +199,8 @@ def compare_to_reference(
         return {"error": f"reference_path: {err['error']}", "code": err["code"]}
 
     try:
+        mix_path = _normalize_audio_path(mix_path)
+        reference_path = _normalize_audio_path(reference_path)
         return _compare(mix_path, reference_path, normalize=normalize)
     except FileNotFoundError as exc:
         return {"error": str(exc), "code": "INVALID_PARAM"}
@@ -207,6 +232,7 @@ def read_audio_metadata(
         return err
 
     try:
+        file_path = _normalize_audio_path(file_path)
         return _read_metadata(file_path)
     except FileNotFoundError as exc:
         return {"error": str(exc), "code": "INVALID_PARAM"}

package/mcp_server/tools/scenes.py

@@ -97,7 +97,10 @@ def set_scene_tempo(ctx: Context, scene_index: int, tempo: float) -> dict:
 
 def _ensure_list(value: Any) -> list:
     if isinstance(value, str):
-        return json.loads(value)
+        try:
+            return json.loads(value)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Invalid JSON in parameter: {exc}") from exc
     return value
 
 

package/mcp_server/tools/theory.py

@@ -48,7 +48,12 @@ def _detect_or_parse_key(notes: list[dict], key_hint: str | None = None) -> dict
 
 def _key_display(key_info: dict) -> str:
     """Format key info as 'C major' string."""
-    return f"{key_info['tonic_name']} {key_info['mode']}"
+    return f"{key_info['tonic_name']} {key_info['mode'].replace('_', ' ')}"
+
+
+def _mode_display(mode: str) -> str:
+    """Format a canonical mode id for user-facing output."""
+    return mode.replace("_", " ")
 
 
 # -- Tool 1: analyze_harmony ------------------------------------------------
@@ -345,8 +350,9 @@ def identify_scale(
 ) -> dict:
     """Identify the scale/mode of a MIDI clip beyond basic major/minor.
 
-    Uses Krumhansl-Schmuckler algorithm with 7 mode profiles (major, minor,
-    dorian, phrygian, lydian, mixolydian, locrian).
+    Uses Krumhansl-Schmuckler-style profiles with 8 mode profiles (major,
+    minor, dorian, phrygian, lydian, mixolydian, locrian, and phrygian
+    dominant / Hijaz).
 
     Returns ranked key matches with confidence scores.
     """
@@ -357,17 +363,19 @@ def identify_scale(
     detected = engine.detect_key(notes, mode_detection=True)
 
     results = [{
-        "key": f"{detected['tonic_name']} {detected['mode']}",
+        "key": f"{detected['tonic_name']} {_mode_display(detected['mode'])}",
         "confidence": detected["confidence"],
-        "mode": detected["mode"],
+        "mode": _mode_display(detected["mode"]),
+        "mode_id": detected["mode"],
         "tonic": detected["tonic_name"],
     }]
 
     for alt in detected.get("alternatives", [])[:7]:
         results.append({
-            "key": f"{alt['tonic_name']} {alt['mode']}",
+            "key": f"{alt['tonic_name']} {_mode_display(alt['mode'])}",
             "confidence": alt["confidence"],
-            "mode": alt["mode"],
+            "mode": _mode_display(alt["mode"]),
+            "mode_id": alt["mode"],
             "tonic": alt["tonic_name"],
         })
 
@@ -661,7 +669,14 @@ def transpose_smart(
 
     source_tonic = source_key["tonic"]
     target_tonic = target["tonic"]
-    semitone_shift = target_tonic - source_tonic
+    # Compute nearest-path semitone shift (never more than ±6)
+    raw_shift = target_tonic - source_tonic
+    if raw_shift > 6:
+        semitone_shift = raw_shift - 12
+    elif raw_shift < -6:
+        semitone_shift = raw_shift + 12
+    else:
+        semitone_shift = raw_shift
 
     if mode == "chromatic":
         transposed = []

package/mcp_server/tools/transport.py

@@ -23,21 +23,31 @@ def get_session_info(ctx: Context) -> dict:
     return _get_ableton(ctx).send_command("get_session_info")
 
 
+def _validate_tempo(tempo: float) -> None:
+    """Validate tempo is within Ableton's accepted range."""
+    if not 20 <= tempo <= 999:
+        raise ValueError("Tempo must be between 20 and 999 BPM")
+
+
+def _validate_time_signature(numerator: int, denominator: int) -> None:
+    """Validate time signature components."""
+    if numerator < 1 or numerator > 99:
+        raise ValueError("Numerator must be between 1 and 99")
+    if denominator not in (1, 2, 4, 8, 16):
+        raise ValueError("Denominator must be 1, 2, 4, 8, or 16")
+
+
 @mcp.tool()
 def set_tempo(ctx: Context, tempo: float) -> dict:
     """Set the song tempo in BPM (20-999)."""
-    if not 20 <= tempo <= 999:
-        raise ValueError("Tempo must be between 20 and 999 BPM")
+    _validate_tempo(tempo)
     return _get_ableton(ctx).send_command("set_tempo", {"tempo": tempo})
 
 
 @mcp.tool()
 def set_time_signature(ctx: Context, numerator: int, denominator: int) -> dict:
     """Set the time signature (e.g., 4/4, 3/4, 6/8)."""
-    if numerator < 1 or numerator > 99:
-        raise ValueError("Numerator must be between 1 and 99")
-    if denominator not in (1, 2, 4, 8, 16):
-        raise ValueError("Denominator must be 1, 2, 4, 8, or 16")
+    _validate_time_signature(numerator, denominator)
     return _get_ableton(ctx).send_command("set_time_signature", {
         "numerator": numerator,
         "denominator": denominator,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livepilot",
-  "version": "1.9.9",
+  "version": "1.9.12",
   "mcpName": "io.github.dreamrec/livepilot",
   "description": "Agentic production system for Ableton Live 12 — 178 tools, 17 domains, device atlas, spectral perception, technique memory, neo-Riemannian harmony, Euclidean rhythm, species counterpoint, MIDI I/O",
   "author": "Pilot Studio",

package/remote_script/LivePilot/__init__.py

@@ -5,7 +5,7 @@ Entry point for the ControlSurface. Ableton calls create_instance(c_instance)
 when this script is selected in Preferences > Link, Tempo & MIDI.
 """
 
-__version__ = "1.9.9"
+__version__ = "1.9.12"
 
 from _Framework.ControlSurface import ControlSurface
 from .server import LivePilotServer

package/remote_script/LivePilot/arrangement.py

@@ -85,29 +85,19 @@ def create_arrangement_clip(song, params):
         first_clip_index = None
 
         while pos < end_pos:
-            # Snapshot clip IDs before duplication to identify the new one
-            old_ids = set(id(c) for c in track.arrangement_clips)
-
             track.duplicate_clip_to_arrangement(source_clip, pos)
 
-            # Find the NEW clip (not in old_ids) at the target position
+            # Find the new clip by position (id()-based detection is unreliable
+            # because CPython can reuse addresses of GC'd LOM wrappers)
             arr_clips = list(track.arrangement_clips)
             new_clip = None
             new_clip_idx = None
             for i, c in enumerate(arr_clips):
-                if id(c) not in old_ids and abs(c.start_time - pos) < 0.01:
+                if abs(c.start_time - pos) < 0.01:
                     new_clip = c
                     new_clip_idx = i
                     break
 
-            # Fallback: if id-based detection fails, match by position
-            if new_clip is None:
-                for i, c in enumerate(arr_clips):
-                    if abs(c.start_time - pos) < 0.01:
-                        new_clip = c
-                        new_clip_idx = i
-                        break
-
             if new_clip is not None:
                 if first_clip_index is None:
                     first_clip_index = new_clip_idx
@@ -158,20 +148,24 @@ def create_arrangement_clip(song, params):
     finally:
         song.end_undo_step()
 
-    # Re-read to get accurate final state
+    # Re-read to get accurate final state — locate by start_time, not stored
+    # index, because the trim pass (remove_notes_extended) can shift indices.
     arr_clips = list(track.arrangement_clips)
-    if first_clip_index is None or first_clip_index >= len(arr_clips):
+    first_clip = None
+    for c in arr_clips:
+        if abs(c.start_time - start_time) < 0.01:
+            first_clip = c
+            break
+    if first_clip is None:
         raise ValueError("Failed to place any clips in arrangement")
-    first_clip = arr_clips[first_clip_index]
 
     return {
         "track_index": track_index,
-        "clip_index": first_clip_index,
         "start_time": start_time,
         "length": length,
         "clip_count": clip_count,
         "source_length": source_length,
-        "name": first_clip.name if first_clip else "",
+        "name": first_clip.name,
     }
 
 
@@ -494,6 +488,10 @@ def set_arrangement_automation(song, params):
             "parameter_type must be 'device', 'volume', 'panning', or 'send'"
         )
 
+    # Clamp values to parameter range
+    p_min = float(parameter.min)
+    p_max = float(parameter.max)
+
     # Try direct envelope access on the arrangement clip
     envelope = clip.automation_envelope(parameter)
     if envelope is None:
@@ -509,7 +507,7 @@ def set_arrangement_automation(song, params):
             points_written = 0
             for pt in points:
                 time = float(pt["time"])
-                value = float(pt["value"])
+                value = max(p_min, min(p_max, float(pt["value"])))
                 duration = float(pt.get("duration", 0.125))
                 envelope.insert_step(time, duration, value)
                 points_written += 1
@@ -523,121 +521,14 @@ def set_arrangement_automation(song, params):
             "method": "direct",
         }
 
-    # Fallback: session-clip-then-duplicate workaround.
-    # Create a temporary session clip, write automation there,
-    # then duplicate to arrangement. Envelopes may survive the copy.
-    arr_start = clip.start_time
-    arr_length = clip.length
-
-    # Find an empty clip slot for the temporary clip
-    slots = list(track.clip_slots)
-    temp_slot_index = None
-    for si, slot in enumerate(slots):
-        if not slot.has_clip:
-            temp_slot_index = si
-            break
-
-    # If all clip slots are full, create a temporary scene to get an empty slot
-    created_temp_scene = False
-    if temp_slot_index is None:
-        song.create_scene(-1)  # append a new scene at the end
-        created_temp_scene = True
-        # Re-read slots — the new scene added one slot per track
-        slots = list(track.clip_slots)
-        temp_slot_index = len(slots) - 1
-
-    song.begin_undo_step()
-    try:
-        # Create temporary session clip
-        slot = slots[temp_slot_index]
-        slot.create_clip(arr_length)
-        temp_clip = slot.clip
-
-        # Write automation to the session clip
-        temp_envelope = temp_clip.automation_envelope(parameter)
-        if temp_envelope is None:
-            try:
-                temp_envelope = temp_clip.create_automation_envelope(parameter)
-            except (AttributeError, RuntimeError):
-                pass
-
-        if temp_envelope is None:
-            # Neither direct nor session clip approach works
-            slot.delete_clip()
-            if created_temp_scene:
-                song.delete_scene(len(list(song.scenes)) - 1)
-            raise ValueError(
-                "Cannot create automation envelope for parameter '%s' "
-                "(neither arrangement nor session clip supports it)"
-                % parameter.name
-            )
-
-        points_written = 0
-        for pt in points:
-            time = float(pt["time"])
-            value = float(pt["value"])
-            duration = float(pt.get("duration", 0.125))
-            temp_envelope.insert_step(time, duration, value)
-            points_written += 1
-
-        # Copy notes from original arrangement clip to the temp session clip
-        # so the replacement clip has the same musical content.
-        try:
-            orig_notes = clip.get_notes_extended(0, 128, 0.0, arr_length + 1.0)
-            import Live
-            note_specs = []
-            for note in orig_notes:
-                kwargs = dict(
-                    pitch=note.pitch,
-                    start_time=note.start_time,
-                    duration=note.duration,
-                    velocity=note.velocity,
-                    mute=note.mute,
-                )
-                # Preserve per-note expression data
-                if hasattr(note, 'probability') and note.probability is not None:
-                    kwargs['probability'] = note.probability
-                if hasattr(note, 'velocity_deviation') and note.velocity_deviation is not None:
-                    kwargs['velocity_deviation'] = note.velocity_deviation
-                if hasattr(note, 'release_velocity') and note.release_velocity is not None:
-                    kwargs['release_velocity'] = note.release_velocity
-                spec = Live.Clip.MidiNoteSpecification(**kwargs)
-                note_specs.append(spec)
-            if note_specs:
-                temp_clip.add_new_notes(tuple(note_specs))
-        except Exception:
-            pass  # Non-MIDI clips or errors — automation-only is still valid
-
-        # Place the session clip (with automation + notes) into arrangement.
-        # Do this BEFORE deleting the original — if placement fails, the
-        # original clip is preserved (no data loss on partial failure).
-        track.duplicate_clip_to_arrangement(temp_clip, arr_start)
-
-        # Placement succeeded — now safe to remove the original clip
-        # to avoid a second overlapping clip at the same position.
-        try:
-            clip.delete_clip()
-        except (AttributeError, RuntimeError):
-            # delete_clip may not exist on arrangement clips in all versions;
-            # in that case we accept the overlap as a known limitation.
-            pass
-
-        # Clean up the temporary session clip
-        slot.delete_clip()
-
-        # Clean up the temporary scene if we created one
-        if created_temp_scene:
-            song.delete_scene(len(list(song.scenes)) - 1)
-    finally:
-        song.end_undo_step()
-
-    return {
-        "track_index": track_index,
-        "clip_index": clip_index,
-        "parameter_name": parameter.name,
-        "points_written": points_written,
-        "method": "session_workaround",
-    }
+    # No fallback — direct envelope creation is the only safe approach.
+    # Session-clip duplication can silently create overlapping clips.
+    raise ValueError(
+        "Cannot create automation envelope for parameter '%s' on this "
+        "arrangement clip. Direct envelope access is not supported for "
+        "this parameter type or Live version."
+        % parameter.name
+    )
 
 
 @register("transpose_arrangement_notes")

package/remote_script/LivePilot/browser.py

@@ -76,13 +76,19 @@ def _navigate_path(browser, path):
     return current
 
 
+_MAX_SEARCH_ITERATIONS = 100000
+
+
 def _search_recursive(item, name_filter, loadable_only, results, depth, max_depth,
-                      max_results=100):
-    """Recursively search browser children."""
+                      max_results=100, _counter=None):
+    """Recursively search browser children with iteration cap."""
+    if _counter is None:
+        _counter = [0]  # mutable counter shared across recursion
     if depth > max_depth or len(results) >= max_results:
         return
     for child in item.children:
-        if len(results) >= max_results:
+        _counter[0] += 1
+        if _counter[0] > _MAX_SEARCH_ITERATIONS or len(results) >= max_results:
             return
         match = True
         if name_filter and name_filter.lower() not in child.name.lower():
@@ -102,7 +108,7 @@ def _search_recursive(item, name_filter, loadable_only, results, depth, max_dept
         if child.is_folder:
             _search_recursive(
                 child, name_filter, loadable_only, results, depth + 1, max_depth,
-                max_results
+                max_results, _counter
             )
             if len(results) >= max_results:
                 return
@@ -125,12 +131,17 @@ def get_browser_tree(song, params):
 
     result = []
     for name, item in categories.items():
-        children = list(item.children)
-        child_names = [c.name for c in children[:20]]
+        # Count lazily without materializing the full children list
+        children_preview = []
+        count = 0
+        for c in item.children:
+            count += 1
+            if len(children_preview) < 20:
+                children_preview.append(c.name)
         result.append({
             "name": name,
-            "children_count": len(children),
-            "children_preview": child_names,
+            "children_count": count,
+            "children_preview": children_preview,
         })
     return {"categories": result}
 

package/remote_script/LivePilot/clip_automation.py

@@ -20,16 +20,17 @@ def get_clip_automation(song, params):
     envelopes = []
 
     # Check mixer parameters: volume, panning, sends
+    # Use the specific parameter_type that set/clear accept (not generic "mixer")
     mixer = track.mixer_device
-    for param_name, param in [
-        ("Volume", mixer.volume),
-        ("Pan", mixer.panning),
+    for param_name, param_type, param in [
+        ("Volume", "volume", mixer.volume),
+        ("Pan", "panning", mixer.panning),
     ]:
         env = clip.automation_envelope(param)
         if env is not None:
             envelopes.append({
                 "parameter_name": param_name,
-                "parameter_type": "mixer",
+                "parameter_type": param_type,
                 "has_envelope": True,
             })
 

package/remote_script/LivePilot/clips.py

@@ -147,12 +147,14 @@ def set_clip_loop(song, params):
     clip_index = int(params["clip_index"])
     clip = get_clip(song, track_index, clip_index)
 
-    if "enabled" in params:
-        clip.looping = bool(params["enabled"])
-    if "start" in params:
-        clip.loop_start = float(params["start"])
+    # Set end before start to avoid Live's loop_start < loop_end clamping.
+    # Expanding the window first ensures the left edge can move freely.
     if "end" in params:
         clip.loop_end = float(params["end"])
+    if "start" in params:
+        clip.loop_start = float(params["start"])
+    if "enabled" in params:
+        clip.looping = bool(params["enabled"])
 
     return {
         "track_index": track_index,
@@ -199,11 +201,17 @@ def set_clip_warp_mode(song, params):
             "3=Re-Pitch, 4=Complex, 6=Complex Pro" % mode
         )
 
-    if "warping" in params:
-        clip.warping = bool(params["warping"])
+    # Enable warping first so warp_mode assignment is accepted by Live,
+    # then disable afterwards if requested.
+    enable_warping = params.get("warping")
+    if enable_warping is not None and bool(enable_warping):
+        clip.warping = True
 
     clip.warp_mode = mode
 
+    if enable_warping is not None and not bool(enable_warping):
+        clip.warping = False
+
     return {
         "track_index": track_index,
         "clip_index": clip_index,

package/remote_script/LivePilot/devices.py

@@ -3,6 +3,7 @@ LivePilot - Device domain handlers (11 commands).
 """
 
 import Live
+from collections import deque
 
 from .router import register
 from .utils import get_track, get_device
@@ -178,6 +179,8 @@ def toggle_device(song, params):
             break
     if on_param is None:
         # Fallback to parameter 0 for devices that don't use "Device On"
+        if not list(device.parameters):
+            raise ValueError("Device '%s' has no parameters to toggle" % device.name)
         on_param = device.parameters[0]
 
     on_param.value = 1.0 if active else 0.0
@@ -399,10 +402,10 @@ def find_and_load_device(song, params):
         This ensures raw 'Operator' is found before 'Hello Operator.adg' buried
         in a user_library subfolder."""
         nonlocal iterations
-        # Queue of (item, depth) tuples
-        queue = [(category, 0)]
+        # Queue of (item, depth) tuples — deque for O(1) popleft
+        queue = deque([(category, 0)])
         while queue:
-            item, depth = queue.pop(0)
+            item, depth = queue.popleft()
             if depth > 8:
                 continue
             try: