3lc-compute-plugin-sdk 0.2.2__py3-none-any.whl

tlc_plugin_sdk/shared/alias_override_ui.py

@@ -0,0 +1,175 @@
+# Copyright 2026 3LC Inc.
+# SPDX-License-Identifier: Apache-2.0
+r"""Shared UI component for URL alias overrides.
+
+Generates the HTML + JS block that plugins embed in their UI fragments.
+This ensures a consistent alias override UI across every plugin that
+consumes existing 3LC tables.
+
+The override section is automatically hidden when all alias paths are
+already local to the compute service (i.e. accessible on disk).
+
+Usage in a plugin's ``get_ui_fragment()``::
+
+    from tlc_plugin_sdk.shared.alias_override_ui import alias_override_ui_script
+    from tlc_plugin_sdk.shared.ui_inject import inject_scripts
+
+    raw = Path("ui.html").read_text()
+    html = inject_scripts(raw, alias_override_ui_script())
+"""
+
+from __future__ import annotations
+
+# fmt: off
+ALIAS_OVERRIDE_UI_JS = (
+    "// \u2500\u2500 Shared URL Alias Override UI \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"
+    "\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n"
+    "function _tlcAliasOverrideHtml(idPrefix) {\n"
+    "  var s = 'margin-top:12px;padding:12px;border:1px solid var(--border)';\n"
+    "  s += ';border-radius:6px;background:var(--bg)';\n"
+    "  var html = '<div class=\"tlc-alias-override\" id=\"' + idPrefix"
+    " + '-alias-override-container\" style=\"' + s + '\">';\n"
+    "  html += '<label style=\"display:flex;align-items:center;gap:6px;"
+    "font-size:12px;font-weight:600;cursor:pointer\">';\n"
+    "  html += '<input type=\"checkbox\" id=\"' + idPrefix"
+    " + '-alias-override-enabled\"> Override URL Aliases';\n"
+    "  html += '</label>';\n"
+    "  html += '<div style=\"margin:4px 0 8px 0;font-size:11px;"
+    "color:var(--text-muted)\">';\n"
+    "  html += 'Redirect alias paths to local storage for faster I/O "
+    "\u2014 ';\n"
+    "  html += 'e.g. use a local SSD copy instead of S3. ';\n"
+    "  html += '<a href=\"https://docs.3lc.ai/3lc/latest/user-guide/"
+    "sharing.html#alias-best-practices\" ';\n"
+    "  html += 'target=\"_blank\" style=\"color:var(--accent)\">"
+    "Learn more</a>';\n"
+    "  html += '</div>';\n"
+    "  html += '<div id=\"' + idPrefix + '-alias-override-fields\""
+    " style=\"display:none\">';\n"
+    "  html += '<div id=\"' + idPrefix + '-alias-override-list\""
+    " style=\"font-size:11px;color:var(--text-muted)\">"
+    "Select a table to see its aliases</div>';\n"
+    "  html += '</div>';\n"
+    "  html += '</div>';\n"
+    "  return html;\n"
+    "}\n"
+    "\n"
+    "function _tlcBindAliasOverrideToggle(idPrefix) {\n"
+    "  var cb = document.getElementById(idPrefix + '-alias-override-enabled');\n"
+    "  var fields = document.getElementById(idPrefix + '-alias-override-fields');\n"
+    "  if (!cb || !fields) return;\n"
+    "  cb.addEventListener('change', function() {\n"
+    "    fields.style.display = cb.checked ? '' : 'none';\n"
+    "  });\n"
+    "}\n"
+    "\n"
+    "function _tlcFetchAndPopulateOverrides(idPrefix, tableUrl, savedOverrides) {\n"
+    "  var list = document.getElementById(idPrefix + '-alias-override-list');\n"
+    "  var container = document.getElementById(idPrefix + '-alias-override-container');\n"
+    "  if (!list) return;\n"
+    "  if (!tableUrl) {\n"
+    "    list.innerHTML = '<span style=\"font-size:11px;color:var(--text-muted)\">"
+    "Select a table to see its aliases</span>';\n"
+    "    if (container) container.style.display = '';\n"
+    "    return;\n"
+    "  }\n"
+    "  list.innerHTML = '<span style=\"font-size:11px;color:var(--text-muted)\">"
+    "Loading aliases...</span>';\n"
+    "  var _aliasPath = '/api/aliases/for-table?url='"
+    " + encodeURIComponent(tableUrl);\n"
+    "  window.PLUGIN_API.computeFetch(_aliasPath)\n"
+    "    .then(function(r) { return r.json(); })\n"
+    "    .then(function(data) {\n"
+    "      var aliases = data.aliases || [];\n"
+    "      if ((data.all_local || aliases.length === 0) && !savedOverrides) {\n"
+    "        if (container) container.style.display = 'none';\n"
+    "        return;\n"
+    "      }\n"
+    "      if (container) container.style.display = '';\n"
+    "      var html = '<div style=\"display:grid;grid-template-columns:auto 1fr 1fr;"
+    "gap:6px 8px;align-items:center\">';\n"
+    "      html += '<div style=\"font-weight:600;font-size:10px\">Token</div>';\n"
+    "      html += '<div style=\"font-weight:600;font-size:10px\">Current Path</div>';\n"
+    "      html += '<div style=\"font-weight:600;font-size:10px\">Override Path</div>';\n"
+    "      for (var i = 0; i < aliases.length; i++) {\n"
+    "        var a = aliases[i];\n"
+    "        html += '<div style=\"font-family:monospace;font-size:11px;"
+    "white-space:nowrap\">&lt;' + a.token + '&gt;</div>';\n"
+    "        html += '<div style=\"font-size:11px;color:var(--text-muted);"
+    "overflow:hidden;text-overflow:ellipsis;white-space:nowrap\""
+    " title=\"' + (a.current_path || '') + '\">' + (a.current_path || '"
+    "<em>unresolved</em>') + '</div>';\n"
+    "        html += '<input type=\"text\" class=\"form-control\" style=\"font-size:11px\"';\n"
+    "        html += ' data-alias-token=\"' + a.token + '\"';\n"
+    "        html += ' data-alias-original=\"' + (a.current_path || '') + '\"';\n"
+    "        html += ' id=\"' + idPrefix + '-alias-override-' + a.token + '\"';\n"
+    "        html += ' placeholder=\"Leave empty to keep current\">';\n"
+    "      }\n"
+    "      html += '</div>';\n"
+    "      list.innerHTML = html;\n"
+    "      if (savedOverrides) _tlcRestoreAliasOverrides(idPrefix, savedOverrides);\n"
+    "    })\n"
+    "    .catch(function(err) {\n"
+    "      list.innerHTML = '<span style=\"color:var(--danger,red);"
+    "font-size:11px\">Failed to load aliases</span>';\n"
+    "      console.error('Alias override fetch error:', err);\n"
+    "    });\n"
+    "}\n"
+    "\n"
+    "function _tlcRestoreAliasOverrides(idPrefix, saved) {\n"
+    "  if (!saved || !saved.overrides || !saved.overrides.length) return;\n"
+    "  var cb = document.getElementById(idPrefix + '-alias-override-enabled');\n"
+    "  var fields = document.getElementById(idPrefix + '-alias-override-fields');\n"
+    "  if (saved.enabled && cb) {\n"
+    "    cb.checked = true;\n"
+    "    if (fields) fields.style.display = '';\n"
+    "  }\n"
+    "  for (var i = 0; i < saved.overrides.length; i++) {\n"
+    "    var ov = saved.overrides[i];\n"
+    "    var input = document.getElementById(\n"
+    "      idPrefix + '-alias-override-' + ov.token);\n"
+    "    if (input && ov.path) input.value = ov.path;\n"
+    "  }\n"
+    "}\n"
+    "\n"
+    "function _tlcGetAliasOverrides(idPrefix) {\n"
+    "  var cb = document.getElementById(idPrefix + '-alias-override-enabled');\n"
+    "  var enabled = cb ? cb.checked : false;\n"
+    "  var overrides = [];\n"
+    "  if (enabled) {\n"
+    "    var inputs = document.querySelectorAll(\n"
+    "      '#' + idPrefix + '-alias-override-list input[data-alias-token]');\n"
+    "    for (var i = 0; i < inputs.length; i++) {\n"
+    "      var val = inputs[i].value.trim();\n"
+    "      if (val) {\n"
+    "        overrides.push({\n"
+    "          token: inputs[i].getAttribute('data-alias-token'),\n"
+    "          path: val\n"
+    "        });\n"
+    "      }\n"
+    "    }\n"
+    "  }\n"
+    "  return {enabled: enabled, overrides: overrides};\n"
+    "}\n"
+)
+# fmt: on
+
+
+def alias_override_ui_script() -> str:
+    """Return the shared alias override UI JavaScript block.
+
+    Include this once in a ``<script>`` tag.  Then call:
+
+    - ``_tlcAliasOverrideHtml(prefix)`` to render HTML
+    - ``_tlcBindAliasOverrideToggle(prefix)`` after inserting the HTML
+    - ``_tlcFetchAndPopulateOverrides(prefix, tableUrl, savedOverrides)``
+    - ``_tlcGetAliasOverrides(prefix)`` at submit time
+
+    The override section is automatically hidden when all alias paths
+    are local to the compute service filesystem.
+
+    Returns:
+        JavaScript source string.
+
+    """
+    return ALIAS_OVERRIDE_UI_JS

tlc_plugin_sdk/shared/alias_ui.py

@@ -0,0 +1,198 @@
+# Copyright 2026 3LC Inc.
+# SPDX-License-Identifier: Apache-2.0
+r"""Shared UI component for URL alias settings.
+
+Generates the HTML + JS block that plugins embed in their UI fragments.
+This ensures a consistent alias UI across every plugin that creates
+3LC tables.
+
+Usage in a plugin's ``get_ui_fragment()``::
+
+    from tlc_plugin_sdk.shared.alias_ui import alias_ui_script
+    from tlc_plugin_sdk.shared.ui_inject import inject_scripts
+
+    raw = Path("ui.html").read_text()
+    html = inject_scripts(raw, alias_ui_script())
+"""
+
+from __future__ import annotations
+
+# The JS helper functions are defined once and shared by all plugins.
+# Each plugin calls _tlcAliasSettingsHtml(idPrefix, projectValue, folderValue)
+# to render the alias section, and _tlcGetAliasValues(idPrefix) to read values.
+
+# fmt: off
+ALIAS_UI_JS = (
+    "// ── Shared URL Alias UI ─────────────────────────────────\n"
+    "(function(){var st=document.createElement('style');st.textContent="
+    "'.tlc-tip{position:relative}'"
+    "+'.tlc-tip .tlc-tip-text{display:none;position:absolute;bottom:calc(100% + 8px);"
+    "left:50%;transform:translateX(-50%);width:260px;padding:8px 10px;"
+    "background:var(--bg-card,#1a2332);color:var(--text-muted,#94a3b8);"
+    "font-size:11px;font-weight:400;line-height:1.5;border-radius:6px;"
+    "border:1px solid var(--border,#2a3a4a);box-shadow:0 4px 12px rgba(0,0,0,.3);"
+    "z-index:1000;pointer-events:none;white-space:normal}'"
+    "+'.tlc-tip:hover .tlc-tip-text{display:block}';"
+    "document.head.appendChild(st)})();\n"
+    "\n"
+    "function _tlcDefaultAliasToken(projectName) {\n"
+    "  var token = projectName.toUpperCase()"
+    ".replace(/[^A-Z0-9]/g, '_').replace(/_+/g, '_').replace(/^_|_$/g, '');\n"
+    "  if (!token || !/^[A-Z]/.test(token)) token = 'PROJECT_' + token;\n"
+    "  return token;\n"
+    "}\n"
+    "\n"
+    "function _tlcAliasSettingsHtml(idPrefix, projectValue, folderValue) {\n"
+    "  var token = projectValue ? _tlcDefaultAliasToken(projectValue) : '';\n"
+    "  var s = 'margin-top:12px;padding:10px 12px;border:1px solid var(--border)';\n"
+    "  s += ';border-radius:6px;background:var(--bg)';\n"
+    "  var html = '<div class=\"tlc-alias-settings\" style=\"' + s + '\">';\n"
+    "  html += '<div style=\"display:flex;align-items:center;gap:6px\">';\n"
+    "  html += '<label style=\"display:flex;align-items:center;gap:6px;"
+    "font-size:12px;font-weight:600;cursor:pointer;flex:1\">';\n"
+    "  html += '<input type=\"checkbox\" id=\"' + idPrefix"
+    " + '-alias-enabled\" checked> Register URL Alias';\n"
+    "  html += '<span class=\"tlc-tip\" style=\"display:inline-flex;align-items:center;"
+    "justify-content:center;width:15px;height:15px;border-radius:50%;"
+    "background:var(--border);color:var(--text-muted);font-size:10px;"
+    "font-weight:700;cursor:help;flex-shrink:0;position:relative\">"
+    "?<span class=\"tlc-tip-text\">URL aliases make image paths portable "
+    "across machines. Instead of hardcoding absolute paths, the table "
+    "stores &lt;ALIAS&gt;/images \\u2014 so the same table works on any "
+    "machine where the alias is configured. Recommended for all new "
+    "tables.</span></span>';\n"
+    "  html += '</label>';\n"
+    "  html += '<button type=\"button\" id=\"' + idPrefix + '-alias-toggle\" "
+    "style=\"background:none;border:none;color:var(--text-muted);cursor:pointer;"
+    "font-size:10px;padding:2px 6px\" "
+    "onclick=\"var f=document.getElementById(\\'' + idPrefix + '-alias-fields\\');"
+    "var open=f.style.display!==\\'none\\';f.style.display=open?\\'none\\':\\'\\';"
+    "this.textContent=open?\\'Details ▸\\':\\'Details ▾\\'\">Details ▸</button>';\n"
+    "  html += '</div>';\n"
+    "  html += '<div id=\"' + idPrefix + '-alias-fields\" style=\"display:none;"
+    "margin-top:8px\">';\n"
+    "  html += '<div style=\"display:grid;"
+    "grid-template-columns:1fr 1fr;gap:8px\">';\n"
+    "  html += '<div class=\"form-group\" style=\"margin-bottom:0\">';\n"
+    "  html += '<label class=\"form-label\" style=\"font-size:11px\">"
+    "Alias Token</label>';\n"
+    "  html += '<input type=\"text\" id=\"' + idPrefix + '-alias-token\"';\n"
+    "  html += ' class=\"form-control\" style=\"font-size:11px\"';\n"
+    "  html += ' value=\"' + (token || '') + '\"';\n"
+    "  html += ' placeholder=\"PROJECT_NAME\">';\n"
+    "  html += '<div style=\"font-size:10px;color:var(--text-muted);"
+    "margin-top:2px\">';\n"
+    "  html += 'Must be UPPER_SNAKE_CASE (A-Z, 0-9, _)</div>';\n"
+    "  html += '</div>';\n"
+    "  html += '<div class=\"form-group\" style=\"margin-bottom:0\">';\n"
+    "  html += '<label class=\"form-label\" style=\"font-size:11px\">"
+    "Alias Folder</label>';\n"
+    "  html += '<input type=\"text\" id=\"' + idPrefix + '-alias-folder\"';\n"
+    "  html += ' class=\"form-control\" style=\"font-size:11px\"';\n"
+    "  html += ' value=\"' + (folderValue || '') + '\"';\n"
+    "  html += ' placeholder=\"Auto-detected from input\">';\n"
+    "  html += '<div style=\"font-size:10px;color:var(--text-muted);"
+    "margin-top:2px\">';\n"
+    "  html += 'Folder that the alias points to</div>';\n"
+    "  html += '</div>';\n"
+    "  html += '</div>';\n"
+    "  html += '</div>';\n"
+    "  html += '</div>';\n"
+    "  return html;\n"
+    "}\n"
+    "\n"
+    "function _tlcBindAliasToggle(idPrefix) {\n"
+    "  var cb = document.getElementById(idPrefix + '-alias-enabled');\n"
+    "  var fields = document.getElementById(idPrefix + '-alias-fields');\n"
+    "  if (!cb || !fields) return;\n"
+    "  cb.addEventListener('change', function() {\n"
+    "    fields.style.display = cb.checked ? '' : 'none';\n"
+    "    document.getElementById(idPrefix + '-alias-toggle')"
+    ".style.display = cb.checked ? '' : 'none';\n"
+    "  });\n"
+    "}\n"
+    "\n"
+    "function _tlcBindAliasAutoUpdate("
+    "idPrefix, projectInputId, folderInputId) {\n"
+    "  var projInput = document.getElementById(projectInputId);\n"
+    "  var tokenInput = document.getElementById("
+    "idPrefix + '-alias-token');\n"
+    "  var folderInput = folderInputId"
+    " ? document.getElementById(folderInputId) : null;\n"
+    "  var aliasFolderInput = document.getElementById("
+    "idPrefix + '-alias-folder');\n"
+    "  if (projInput && tokenInput) {\n"
+    "    projInput.addEventListener('input', function() {\n"
+    "      if (!tokenInput.dataset.userEdited)\n"
+    "        tokenInput.value = _tlcDefaultAliasToken(projInput.value);\n"
+    "    });\n"
+    "    tokenInput.addEventListener('input', function() {\n"
+    "      tokenInput.dataset.userEdited = '1';\n"
+    "    });\n"
+    "  }\n"
+    "  if (folderInput && aliasFolderInput) {\n"
+    "    folderInput.addEventListener('input', function() {\n"
+    "      if (!aliasFolderInput.dataset.userEdited)\n"
+    "        aliasFolderInput.value = folderInput.value;\n"
+    "    });\n"
+    "    aliasFolderInput.addEventListener('input', function() {\n"
+    "      aliasFolderInput.dataset.userEdited = '1';\n"
+    "    });\n"
+    "  }\n"
+    "}\n"
+    "\n"
+    "function _tlcSyncAliasFromForm("
+    "idPrefix, projectInputId, folderInputId) {\n"
+    "  var projEl = document.getElementById(projectInputId);\n"
+    "  var tokenEl = document.getElementById(idPrefix + '-alias-token');\n"
+    "  var folderEl = folderInputId"
+    " ? document.getElementById(folderInputId) : null;\n"
+    "  var aliasFolderEl = document.getElementById("
+    "idPrefix + '-alias-folder');\n"
+    "  if (projEl && tokenEl && !tokenEl.dataset.userEdited) {\n"
+    "    tokenEl.value = projEl.value"
+    " ? _tlcDefaultAliasToken(projEl.value) : '';\n"
+    "  }\n"
+    "  if (folderEl && aliasFolderEl"
+    " && !aliasFolderEl.dataset.userEdited) {\n"
+    "    aliasFolderEl.value = folderEl.value || '';\n"
+    "  }\n"
+    "}\n"
+    "\n"
+    "function _tlcSetAliasRoot(idPrefix, rootPath) {\n"
+    "  var el = document.getElementById(idPrefix + '-alias-folder');\n"
+    "  if (el && rootPath) {\n"
+    "    el.value = rootPath;\n"
+    "    el.dataset.userEdited = '1';\n"
+    "  }\n"
+    "}\n"
+    "\n"
+    "function _tlcGetAliasValues(idPrefix) {\n"
+    "  var cb = document.getElementById(idPrefix + '-alias-enabled');\n"
+    "  return {\n"
+    "    alias_enabled: cb ? cb.checked : true,\n"
+    "    alias_token: (document.getElementById(\n"
+    "      idPrefix + '-alias-token') || {}).value || '',\n"
+    "    alias_folder: (document.getElementById(\n"
+    "      idPrefix + '-alias-folder') || {}).value || '',\n"
+    "  };\n"
+    "}\n"
+)
+# fmt: on
+
+
+def alias_ui_script() -> str:
+    """Return the shared alias UI JavaScript block.
+
+    Include this once in a ``<script>`` tag.  Then call:
+
+    - ``_tlcAliasSettingsHtml(prefix, project, folder)`` to render HTML
+    - ``_tlcBindAliasToggle(prefix)`` after inserting the HTML
+    - ``_tlcBindAliasAutoUpdate(prefix, projectInputId, folderInputId)``
+    - ``_tlcGetAliasValues(prefix)`` at submit time
+
+    Returns:
+        JavaScript source string.
+
+    """
+    return ALIAS_UI_JS

tlc_plugin_sdk/shared/aliases.py

@@ -0,0 +1,227 @@
+# Copyright 2026 3LC Inc.
+# SPDX-License-Identifier: Apache-2.0
+"""Shared URL alias utilities for plugins.
+
+Two concerns:
+
+1. **Registration** — when creating a new table, register a persistent project
+   alias so image paths use a portable ``<TOKEN>`` prefix.
+2. **Override** — when consuming an existing table, temporarily override an
+   alias so ``<TOKEN>`` resolves to a fast local path (e.g. SSD) instead of
+   the default (e.g. S3).  Overrides are session-scoped and never persisted.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def _sanitize_token(name: str) -> str:
+    """Convert a project name to a valid alias token.
+
+    Alias tokens must match ``[A-Z][A-Z0-9_]*``.  We upper-case the input,
+    replace non-alphanumeric characters with underscores, collapse runs of
+    underscores, and ensure it starts with a letter.
+    """
+    token = re.sub(r"[^A-Z0-9]", "_", name.upper())
+    token = re.sub(r"_+", "_", token).strip("_")
+    if not token or not token[0].isalpha():
+        token = "PROJECT_" + token
+    return token
+
+
+def default_alias_token(project_name: str) -> str:
+    """Generate a default alias token from a project name.
+
+    Args:
+        project_name: Human-readable project name (e.g. "My COCO Dataset").
+
+    Returns:
+        A valid alias token like ``MY_COCO_DATASET``.
+
+    """
+    return _sanitize_token(project_name)
+
+
+def register_alias(
+    project_name: str,
+    image_folder: str,
+    alias_token: str | None = None,
+) -> dict[str, Any]:
+    """Register a project URL alias for an image folder.
+
+    Args:
+        project_name: The 3LC project that owns the alias.
+        image_folder: Absolute path to the image root folder.
+        alias_token: Override token name.  If *None*, one is derived from
+            *project_name* via :func:`default_alias_token`.
+
+    Returns:
+        Dict with ``token`` and ``path`` that were registered, or ``error``
+        on failure.
+
+    """
+    import tlc
+
+    token = alias_token or default_alias_token(project_name)
+    # Expand ~ before persisting — an alias stored with a literal tilde would
+    # poison every future table that resolves through it.
+    path = os.path.expanduser(image_folder.strip())
+
+    try:
+        # Track whether a session alias for this token already existed, so the
+        # caller knows whether it created one and should clean it up afterwards.
+        # Aliases are a single flat namespace in 3.x, so the public alias
+        # snapshot is the thing to compare against.
+        existed = f"<{token}>" in tlc.url.get_registered_url_aliases()
+
+        # 1. Persist the alias in the project config.
+        tlc.helpers.ProjectHelper.register_project_url_alias(
+            token=token,
+            path=path,
+            project_name=project_name,
+        )
+        # 2. Also register as a session alias so it is active for the current
+        #    process when the SDK encodes image paths.
+        tlc.url.register_url_alias(token=token, path=path, force=True)
+        logger.info("Registered alias <%s> → %s for project %r", token, path, project_name)
+        return {"token": token, "path": path, "primary_created": not existed}
+    except Exception:
+        logger.exception("Failed to register alias <%s> → %s", token, path)
+        return {"error": f"Failed to register alias <{token}> → {path}"}
+
+
+# ---------------------------------------------------------------------------
+# Alias override (for plugins that consume existing tables)
+# ---------------------------------------------------------------------------
+
+_ALIAS_TOKEN_RE = re.compile(r"<([A-Z][A-Z0-9_]*)>")
+
+
+def get_table_aliases(table_url: str) -> list[dict[str, str]]:
+    """Discover which URL aliases a table uses.
+
+    Loads the table, reads image-path columns from the first row, and
+    returns every alias token that appears together with its current
+    resolved path.
+
+    Args:
+        table_url: 3LC table URL.
+
+    Returns:
+        List of ``{"token": "MY_DATA", "current_path": "/data/images", "is_local": true}``.
+
+    """
+    import tlc
+
+    table = tlc.Table.from_url(table_url)
+    all_aliases = tlc.url.get_registered_url_aliases()  # {"<TOKEN>": "/path", ...}
+
+    # Collect alias tokens referenced by the table
+    found_tokens: set[str] = set()
+
+    # Check input_url (creation source, often has alias)
+    input_url = str(getattr(table, "input_url", "")) or ""
+    for m in _ALIAS_TOKEN_RE.finditer(input_url):
+        found_tokens.add(m.group(1))
+
+    # Check a sample row from URL columns.
+    from tlc_plugin_sdk.shared.url_utils import get_url_column_names
+
+    url_col_names = get_url_column_names(table)
+
+    if url_col_names and len(table) > 0:
+        try:
+            row = table[0]
+            for col in url_col_names:
+                val = str(row.get(col, ""))
+                for m in _ALIAS_TOKEN_RE.finditer(val):
+                    found_tokens.add(m.group(1))
+        except Exception:
+            logger.debug("Could not scan first row for alias tokens", exc_info=True)
+
+    # Also scan the table URL itself
+    for m in _ALIAS_TOKEN_RE.finditer(str(table.url)):
+        found_tokens.add(m.group(1))
+
+    # Build result with current resolved paths
+    result: list[dict[str, Any]] = []
+    for token in sorted(found_tokens):
+        key = f"<{token}>"
+        path = all_aliases.get(key, "")
+        if not path:
+            # Try get_alias_path as fallback
+            path = tlc.url.get_alias_path(token) or ""
+        result.append({
+            "token": token,
+            "current_path": path,
+            "is_local": bool(path) and os.path.isdir(path),
+        })
+
+    return result
+
+
+def apply_alias_overrides(overrides: list[dict[str, str]]) -> list[dict[str, str]]:
+    """Temporarily override alias paths for the current session.
+
+    Uses ``tlc.url.register_url_alias`` (session-only, not persisted) so that
+    ``<TOKEN>`` resolves to a different path during processing.
+
+    Args:
+        overrides: List of ``{"token": "TOKEN", "path": "/local/fast/path"}``.
+            Entries with empty *path* are skipped.
+
+    Returns:
+        List of ``{"token": "TOKEN", "original_path": "/original/path"}``
+        needed by :func:`restore_aliases` to undo the overrides.
+
+    """
+    import tlc
+
+    originals: list[dict[str, str]] = []
+    for entry in overrides:
+        token = entry.get("token", "").strip()
+        new_path = entry.get("path", "").strip()
+        if not token or not new_path:
+            continue
+
+        # Save original path before overriding
+        original = tlc.url.get_alias_path(token) or ""
+        if new_path == original:
+            continue  # No change needed
+
+        try:
+            tlc.url.register_url_alias(token=token, path=new_path, force=True)
+            originals.append({"token": token, "original_path": original})
+            logger.info("Override alias <%s>: %s → %s", token, original, new_path)
+        except Exception:
+            logger.exception("Failed to override alias <%s>", token)
+
+    return originals
+
+
+def restore_aliases(originals: list[dict[str, str]]) -> None:
+    """Restore aliases to their original paths after an override.
+
+    Args:
+        originals: List returned by :func:`apply_alias_overrides`.
+
+    """
+    import tlc
+
+    for entry in originals:
+        token = entry.get("token", "")
+        original_path = entry.get("original_path", "")
+        try:
+            if original_path:
+                tlc.url.register_url_alias(token=token, path=original_path, force=True)
+            else:
+                tlc.url.unregister_url_alias(token=token)
+            logger.info("Restored alias <%s> → %s", token, original_path or "(unregistered)")
+        except Exception:
+            logger.exception("Failed to restore alias <%s>", token)