davinci-resolve-mcp 2.102.0 → 2.103.0

package/CHANGELOG.md

@@ -2,6 +2,71 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v2.103.0
+
+**An unreachable Resolve no longer ends the work.** The interchange authoring that can
+write an importable timeline has been in this repository the whole time, one process
+away, while a connection failure stopped everything. This routes to it.
+
+### Added
+
+- **`timeline author_offline`** — write an importable timeline from a file-path clip plan
+  with no Resolve connection. Served **above** the connection check, because it exists
+  for the case where there is none. Targets in preference order:
+  - **`drt`** (default) — Resolve-native, carries track structure. Stamped at project
+    version 17 (Resolve 21.0); older builds need the advanced server's
+    `drt(action='downgrade')`. Verified map: 18.0.4 -> 11, 19.1.x -> 14, 21.0 -> 17.
+  - **`otio`** — round-trips through this repo's own parser and carries gaps, per-clip
+    speed, and transitions. The target to pick when the plan has retimes.
+  - **`edl`** — CMX3600: video cuts and M2 speed, nothing else.
+- **`timeline offline_fallback_capabilities`** — whether authoring is available here, and
+  why not if it is not.
+- **`offline_alternative` on every not-connected error** — naming what could be produced.
+
+### It is an offer, never a substitute
+
+A caller who asked to build a timeline *in Resolve* has not succeeded because a file was
+written somewhere. The connection error stays an error, the block says outright that
+authoring does not complete what failed, and nothing is authored unless it is asked for.
+A test asserts both halves, because an offer that reads as success is worse than no offer.
+
+### Two silent failures, now named
+
+- `media_tc_origin_assumed` — OTIO source frames are **timecode-absolute**. An event with
+  no media timecode origin imports as an *empty* timeline: the file opens, nothing
+  appears, and no error is raised. Every event that had to assume an origin is named,
+  with the fix (`media_start_tc_frame` per clip).
+- `retimes_flattened` — a `.drt` carries no per-clip speed field, so retimes flatten to
+  100% forward. Every event that lost one is named, with OTIO as the target that keeps it.
+
+### Fixed
+
+`_check()` emitted its own flat `NOT_CONNECTED` error asserting Resolve might not be
+running and pointing every reader at a Studio-only preference — the same three wrong
+claims `_not_connected_error` was written to stop making in v2.63, still being made here
+because two producers of one error had drifted apart. It now delegates, so the message
+distinguishes "not running" from "running but refusing scripting" from "the bridge is
+enabled and silent", and free-edition users stop being sent to check a Studio install.
+
+### Design notes
+
+- **Frame numbers are at the timeline rate and `end_frame` is EXCLUSIVE**, matching
+  `AppendToTimeline`'s half-open range. The two shapes disagreeing would be a one-frame
+  error on every clip — exactly the kind that survives review.
+- **Authoring runs in Node** against `resolve-advanced/server/author-interchange.mjs`
+  rather than a second Python writer. Two writers to keep in agreement means the one that
+  drifts is always the copy nobody runs. Without Node it refuses and says why.
+
+### Validation
+
+- Offline suite: 2959 passed, 1 skipped, 719 subtests, 0 failures.
+- All three targets authored and read back: OTIO parsed as a Timeline document with
+  timecode-absolute source ranges, DRT and EDL written and inspected.
+- Three deliberate mutations (swallowing the media-origin warning, treating `end_frame`
+  as inclusive, and marking the connection error as a success) were each caught.
+- No Resolve behavior changed by the authoring path itself; live import validation of an
+  authored file is **not** included in this release.
+
 ## What's New in v2.102.0
 
 **A rough mix that reports what it achieved, not what it intended.** The pieces were

package/README.md

@@ -2,7 +2,7 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-2.102.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.103.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-36%20(353%20full)-blue.svg)](#server-modes)

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-2.102.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-2.103.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
 [![Tools](https://img.shields.io/badge/MCP%20Tools-36%20(353%20full)-blue.svg)](#服务器模式)
@@ -12,7 +12,7 @@
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-> 本翻译对应 v2.102.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v2.103.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 

package/docs/SKILL.md

@@ -552,6 +552,13 @@ Key actions:
   `load_user_preferences_preset`
 - `quit` — terminates Resolve (destructive; confirm with user first)
 
+**Offline timeline authoring on `timeline`** — served above the connection check:
+`author_offline` writes an importable `.drt` / `.otio` / `.edl` from a clip plan when
+Resolve is unreachable, and `offline_fallback_capabilities` reports whether it can. Every
+not-connected error carries an `offline_alternative` block naming it. Authoring a file
+does not complete a failed live operation — the timeline is not in a project until it is
+imported. See `docs/kernels/timeline-conform-interchange-kernel.md`.
+
 **Offline audio and image QC on `media_analysis`** — no Resolve connection required:
 `measure_loudness`, `mix_plan` / `mix_plan_capabilities` (dialogue-anchored rough mix
 with dialogue-following ducking, rendered and re-measured), and `assess_grade` /

package/docs/kernels/timeline-conform-interchange-kernel.md

@@ -67,6 +67,45 @@ Supported aliases include `aaf`, `drt`, `edl`, `edl_cdl`, `edl_sdl`,
 - Synthetic-only unlink, missing-media detection, relink candidate planning,
   and safe relink all worked through generated media.
 
+## When Resolve is unreachable
+
+An unreachable Resolve used to end the work. It no longer has to: `timeline` serves two
+actions **above** the connection check, and every not-connected error carries an
+`offline_alternative` block naming them.
+
+- `author_offline(clips[], output_path, target?, name?, fps?, start_timecode?,
+  resolution?)` — write an importable timeline from a file-path clip plan.
+  Targets, in preference order:
+  - **`drt`** (default) — Resolve-native, carries track structure. Stamped at project
+    version 17 (Resolve 21.0); older builds need the advanced server's
+    `drt(action='downgrade')`. Verified map: 18.0.4 → 11, 19.1.x → 14, 21.0 → 17.
+  - **`otio`** — round-trips through this repo's own parser and carries gaps, per-clip
+    speed, and transitions. The target to pick when the plan has retimes.
+  - **`edl`** — CMX3600: video cuts and M2 speed, nothing else.
+- `offline_fallback_capabilities()` — whether authoring is available here, and why not
+  if it is not.
+
+Frame numbers are at the timeline rate and `end_frame` is **EXCLUSIVE**, matching
+`AppendToTimeline`'s half-open range.
+
+**It is an offer, not a substitute.** A caller who asked to build a timeline *in Resolve*
+has not succeeded because a file was written. The connection error stays an error, the
+block says outright that authoring does not complete what failed, and nothing is authored
+unless someone asks for it.
+
+Two warnings the result can carry, both for failures that are otherwise silent:
+
+- `media_tc_origin_assumed` — OTIO source frames are **timecode-absolute**. An event with
+  no media timecode origin imports as an *empty* timeline: the file opens, nothing
+  appears, no error is raised. Pass `media_start_tc_frame` (or an absolute
+  `src_tc_frame`) per clip. Every event that had to assume is named.
+- `retimes_flattened` — a `.drt` has no per-clip speed field, so retimes flatten to 100%
+  forward. Every event that lost one is named; author OTIO to keep them.
+
+Authoring runs in Node against `resolve-advanced/server/author-interchange.mjs` rather
+than a second Python writer — two writers to keep in agreement means the one that drifts
+is always the copy nobody runs. Without Node it refuses and says so.
+
 ## Boundaries
 
 - Interchange formats are not semantically equivalent. DRT is the strongest

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "2.102.0"
+VERSION = "2.103.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.102.0",
+  "version": "2.103.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.102.0"
+VERSION = "2.103.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 353-tool granular server instead
 """
 
-VERSION = "2.102.0"
+VERSION = "2.103.0"
 
 import base64
 import os
@@ -970,7 +970,7 @@ def _not_connected_error():
     running = resolve_is_running()
     bridge_on = _bridge_requested()
     if bridge_on:
-        return _err(
+        return _with_offline_alternative(_err(
             "The in-app bridge is enabled but not answering.",
             code="BRIDGE_UNAVAILABLE", category="not_connected",
             # `not_connected` defaults to retryable because auto-launch may
@@ -986,9 +986,9 @@ def _not_connected_error():
                         "run `launchctl setenv PYTHON3HOME \"$(python3 -c 'import sys; "
                         "print(sys.prefix)')\"` (launchctl, not export) and restart Resolve.",
             state={"resolve_running": running, "bridge_enabled": True},
-        )
+        ))
     if running:
-        return _err(
+        return _with_offline_alternative(_err(
             "DaVinci Resolve is running but is not answering the scripting API.",
             code="SCRIPTING_UNAVAILABLE", category="not_connected",
             # Not retryable: a preference has to change, or the bridge has to be
@@ -1006,13 +1006,33 @@ def _not_connected_error():
             # responses, and the in-app bridge is not an option for the former.
             state={"resolve_running": True, "bridge_enabled": False,
                    "headless": _resolve_runtime.is_headless()},
-        )
-    return _err(
+        ))
+    return _with_offline_alternative(_err(
         "DaVinci Resolve is not running and could not be started.",
         code="RESOLVE_NOT_RUNNING", category="not_connected",
         remediation="Start DaVinci Resolve and open a project, then retry.",
         state={"resolve_running": bool(running), "bridge_enabled": False},
-    )
+    ))
+
+
+def _with_offline_alternative(error: Dict[str, Any]) -> Dict[str, Any]:
+    """Attach the offline-authoring offer to a not-connected error.
+
+    An offer, not a substitute: the error stays an error, and the block says outright
+    that authoring a file does not complete the operation that just failed. Rerouting
+    silently would turn "your project now has this timeline" into a claim that is false
+    in the only sense that matters.
+    """
+    try:
+        from src.utils import offline_fallback as _offline_mod
+
+        alternative = _offline_mod.offline_alternative()
+        if alternative.get("available"):
+            error.setdefault("error", {})["offline_alternative"] = alternative
+    except Exception:
+        # A connection error must survive anything wrong with the fallback path.
+        pass
+    return error
 
 
 def _destructive_versioning_provider() -> Optional[Tuple[Any, Any, str, Optional[str]]]:
@@ -2489,11 +2509,12 @@ def _check():
         )
     resolve = get_resolve()
     if resolve is None:
-        return None, None, _err(
-            "Not connected to DaVinci Resolve. Is Resolve running?",
-            code="NOT_CONNECTED", category="not_connected", retryable=True,
-            remediation="Open DaVinci Resolve Studio and set Preferences > General > 'External scripting using' to Local.",
-        )
+        # Delegate rather than assert. This branch used to claim Resolve might not be
+        # running and point every reader at a Studio-only preference — the same three
+        # wrong claims `_not_connected_error` was written to stop making, still being
+        # made here because two producers of the same error drifted apart. It also
+        # carries the offline-authoring offer, which this branch never had.
+        return None, None, _not_connected_error()
     pm = resolve.GetProjectManager()
     if pm is None:
         return None, None, _err(
@@ -22875,6 +22896,8 @@ def edit_engine(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[st
 
 
 _TIMELINE_ACTIONS = [
+    # Offline authoring — served without a Resolve connection, above the _check() gate.
+    "author_offline", "offline_fallback_capabilities",
     "list", "get_current", "set_current", "get_name", "set_name", "get_start_frame",
     "get_end_frame", "get_start_timecode", "set_start_timecode", "get_track_count",
     "add_track", "delete_track", "get_track_sub_type", "set_track_enable",
@@ -23131,6 +23154,38 @@ def timeline(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str,
     # action_help is pull-on-demand metadata; no Resolve connection needed.
     if action == "action_help":
         return _action_help("timeline", p)
+    if action in {"author_offline", "offline_fallback_capabilities"}:
+        # Deliberately above the connection check: these exist FOR the case where there
+        # is no connection. Authoring writes a file the user imports; it does not make
+        # a failed live operation succeed, and the response says so.
+        from src.utils import offline_fallback as _offline_mod
+
+        if action == "offline_fallback_capabilities":
+            return _ok(**_offline_mod.capabilities())
+        err, _clean = _validate_params(p, {
+            "output_path": {"type": str, "required": True, "non_empty": True},
+        })
+        if err:
+            return _err(err)
+        try:
+            return _ok(**_offline_mod.author(
+                p.get("clips") or [],
+                str(p["output_path"]),
+                target=str(p.get("target") or _offline_mod.DEFAULT_TARGET),
+                name=str(p.get("name") or "Offline Conform"),
+                fps=float(p.get("fps") or _offline_mod.DEFAULT_FPS),
+                start_timecode=str(p.get("start_timecode") or "01:00:00:00"),
+                resolution=str(p.get("resolution") or "1920x1080"),
+            ))
+        except _offline_mod.OfflineFallbackError as exc:
+            return _err(str(exc), code="OFFLINE_AUTHORING_REFUSED",
+                        category="invalid_input", retryable=False,
+                        remediation=(
+                            "Supply clips=[{path, start_frame, end_frame}] with frame "
+                            "numbers at the timeline rate; end_frame is EXCLUSIVE. Add "
+                            "media_start_tc_frame per clip so source frames are "
+                            "timecode-absolute, or the import can produce an empty timeline."
+                        ))
     pm, proj, err = _check()
     if err:
         return err

package/src/utils/offline_fallback.py

@@ -0,0 +1,307 @@
+"""When Resolve cannot be reached, produce something importable instead of stopping.
+
+An unreachable Resolve currently ends the work. The error explaining *why* is a good
+one — it reads the situation and names the fix that applies — but the timeline the caller
+wanted still does not exist, and the interchange authoring that could produce it has been
+sitting in this repository the whole time, one process away.
+
+This routes to it. A clip plan the live path would have built in the app becomes an
+OTIO, EDL, or DRT file the user imports in one action.
+
+## It is an offer, never a substitute
+
+A caller who asked to build a timeline *in Resolve* has not succeeded because a file was
+written somewhere. The connection error stays an error and gains an `offline_alternative`
+block naming what could be produced; authoring only happens when someone asks for it.
+Silently rerouting would turn "your project now has this timeline" into a claim that is
+false in the only sense that matters.
+
+## Target order: DRT, then OTIO, then EDL
+
+DRT is Resolve-native and carries track structure. OTIO round-trips through this repo's
+own parser and carries gaps, per-clip speed, and transitions. EDL is CMX3600 — video
+cuts and M2 speed, nothing else — and is the fallback when the other two are refused.
+
+## Two traps that have already cost time once
+
+- **OTIO source frames are timecode-absolute.** An event with no media timecode origin
+  imports as an *empty* timeline: the file opens, nothing appears, and no error is
+  raised. Every event that had to assume an origin comes back as a warning naming the
+  clip, rather than being discovered later as a silent no-op.
+- **A `.drt` carries no per-clip speed.** Retimes flatten to 100% forward. Events that
+  lost one are named; OTIO is the target that keeps them.
+
+## Authoring runs in Node, deliberately
+
+`resolve-advanced/server/author-interchange.mjs` already writes all three formats and is
+covered by that server's own suite. A second implementation in Python would be two
+writers to keep in agreement, and the one that drifts is always the copy nobody runs. If
+Node is unavailable, this says so and refuses — it does not fall back to a half-format.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from typing import Any, Dict, List, Optional, Sequence
+
+REPO_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+BRIDGE_SCRIPT = os.path.join(REPO_ROOT, "scripts", "author_interchange.mjs")
+AUTHORING_MODULE = os.path.join(
+    REPO_ROOT, "resolve-advanced", "server", "author-interchange.mjs"
+)
+
+TARGETS = ("drt", "otio", "edl")
+DEFAULT_TARGET = "drt"
+DEFAULT_FPS = 24.0
+
+#: `drt.downgrade`'s verified map, quoted so the response can say which Resolve a file
+#: targets instead of leaving the caller to find out on import.
+DRT_PROJECT_VERSIONS = {"18.0.4": 11, "19.1": 14, "21.0": 17}
+
+
+class OfflineFallbackError(Exception):
+    """Bad plan, missing tool, or a target that cannot carry the plan honestly."""
+
+
+def capabilities() -> Dict[str, Any]:
+    node = shutil.which("node")
+    return {
+        "available": bool(node) and os.path.isfile(BRIDGE_SCRIPT) and os.path.isfile(AUTHORING_MODULE),
+        "node_path": node,
+        "bridge_script": BRIDGE_SCRIPT if os.path.isfile(BRIDGE_SCRIPT) else None,
+        "authoring_module": AUTHORING_MODULE if os.path.isfile(AUTHORING_MODULE) else None,
+        "targets": list(TARGETS),
+        "default_target": DEFAULT_TARGET,
+        "drt_project_versions": DRT_PROJECT_VERSIONS,
+        "note": (
+            "Writes an importable timeline when Resolve is unreachable. It does not make "
+            "a failed live operation succeed — the timeline exists as a file, not in a "
+            "project, until someone imports it."
+        ),
+    }
+
+
+def _require() -> None:
+    report = capabilities()
+    if report["available"]:
+        return
+    missing = []
+    if not report["node_path"]:
+        missing.append("node is not on PATH")
+    if not report["bridge_script"]:
+        missing.append(f"{BRIDGE_SCRIPT} is missing")
+    if not report["authoring_module"]:
+        missing.append("the resolve-advanced authoring module is missing from this install")
+    raise OfflineFallbackError(
+        "offline interchange authoring is unavailable: " + "; ".join(missing)
+    )
+
+
+# ── plan → events ────────────────────────────────────────────────────────────
+
+
+def _number(value: Any, field: str, clip_index: int) -> Optional[float]:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        raise OfflineFallbackError(f"clip {clip_index}: '{field}' is not a number ({value!r})")
+
+
+def plan_to_events(
+    clips: Sequence[Dict[str, Any]], *, fps: float = DEFAULT_FPS
+) -> List[Dict[str, Any]]:
+    """Turn a file-path clip plan into the normalized event list the writers take.
+
+    Everything is in FRAMES at the timeline rate. `end_frame` is EXCLUSIVE, matching
+    `AppendToTimeline`'s half-open range — the two shapes disagreeing would be a
+    one-frame error on every clip, which is exactly the kind that survives review.
+
+    Clips without `record_frame` are laid end to end per track, in the order given.
+    """
+    if not clips:
+        raise OfflineFallbackError("supply at least one clip")
+
+    cursor: Dict[str, float] = {"V": 0.0, "A": 0.0}
+    events: List[Dict[str, Any]] = []
+    for index, clip in enumerate(clips):
+        if not isinstance(clip, dict) or not clip.get("path"):
+            raise OfflineFallbackError(f"clip {index}: needs a 'path'")
+        path = str(clip["path"])
+        media_type = str(clip.get("media_type") or clip.get("mediaType") or "video").lower()
+        track = "A" if media_type.startswith("audio") else "V"
+
+        start = _number(clip.get("start_frame", clip.get("startFrame", 0)), "start_frame", index) or 0.0
+        end = _number(clip.get("end_frame", clip.get("endFrame")), "end_frame", index)
+        duration = _number(clip.get("duration_frames", clip.get("durationFrames")), "duration_frames", index)
+        if end is None and duration is None:
+            raise OfflineFallbackError(
+                f"clip {index}: supply end_frame (exclusive) or duration_frames"
+            )
+        if end is None:
+            end = start + float(duration)
+        length = float(end) - float(start)
+        if length <= 0:
+            raise OfflineFallbackError(
+                f"clip {index}: end_frame ({end}) must be greater than start_frame ({start}); "
+                "end_frame is exclusive"
+            )
+
+        record = _number(clip.get("record_frame", clip.get("recordFrame")), "record_frame", index)
+        if record is None:
+            record = cursor[track]
+        cursor[track] = float(record) + length
+
+        event: Dict[str, Any] = {
+            "source": path,
+            "track": track,
+            "recIn": int(round(float(record))),
+            "recOut": int(round(float(record) + length)),
+            "srcIn": int(round(float(start))),
+            "srcOut": int(round(float(end))),
+            "fps": float(clip.get("fps") or fps),
+        }
+        origin = clip.get("media_start_tc_frame", clip.get("mediaStartTcFrame"))
+        if origin is not None:
+            event["mediaStartTcFrame"] = int(round(float(origin)))
+        absolute = clip.get("src_tc_frame", clip.get("srcTcFrame"))
+        if absolute is not None:
+            event["srcTcFrame"] = int(round(float(absolute)))
+        if clip.get("speed") is not None:
+            event["speed"] = float(clip["speed"])
+        if clip.get("reverse"):
+            event["reverse"] = True
+        if clip.get("name"):
+            event["name"] = str(clip["name"])
+        events.append(event)
+    return events
+
+
+# ── authoring ────────────────────────────────────────────────────────────────
+
+
+def author(
+    clips: Sequence[Dict[str, Any]],
+    output_path: str,
+    *,
+    target: str = DEFAULT_TARGET,
+    name: str = "Offline Conform",
+    fps: float = DEFAULT_FPS,
+    start_timecode: str = "01:00:00:00",
+    resolution: str = "1920x1080",
+) -> Dict[str, Any]:
+    """Author an importable timeline file from a clip plan."""
+    normalized = str(target or DEFAULT_TARGET).lower()
+    if normalized not in TARGETS:
+        raise OfflineFallbackError(
+            f"unknown target '{target}'. Valid targets: {', '.join(TARGETS)}"
+        )
+    _require()
+    events = plan_to_events(clips, fps=fps)
+
+    request = {
+        "events": events,
+        "target": normalized,
+        "outputPath": os.path.abspath(output_path),
+        "opts": {
+            "name": name,
+            "fps": float(fps),
+            "startTimecode": start_timecode,
+            "resolution": resolution,
+        },
+    }
+    process = subprocess.run(
+        [shutil.which("node"), BRIDGE_SCRIPT],
+        input=json.dumps(request).encode("utf-8"),
+        capture_output=True,
+        check=False,
+        timeout=120,
+    )
+    raw = process.stdout.decode("utf-8", "replace").strip()
+    try:
+        result = json.loads(raw) if raw else {}
+    except json.JSONDecodeError:
+        raise OfflineFallbackError(
+            f"the authoring bridge produced no usable output "
+            f"(exit {process.returncode}): {raw[:300] or process.stderr.decode('utf-8', 'replace')[-300:]}"
+        )
+    if not result.get("ok"):
+        raise OfflineFallbackError(result.get("error") or "authoring failed")
+
+    return {
+        "target": result["target"],
+        "output_path": result["outputPath"],
+        "bytes": result["bytes"],
+        "event_count": result["eventCount"],
+        "warnings": result.get("warnings", []),
+        "import_with": _import_instruction(result["target"]),
+        "resolve_version": _version_note(result["target"]),
+        "note": (
+            "The timeline exists as a file. It is not in any project until it is "
+            "imported."
+        ),
+    }
+
+
+def _import_instruction(target: str) -> str:
+    return {
+        "drt": "Resolve: right-click a Media Pool bin > Timelines > Import > Timeline, "
+               "or File > Import > Timeline.",
+        "otio": "Resolve: File > Import > Timeline, and pick the .otio.",
+        "edl": "Resolve: right-click a bin > Timelines > Import > Pre-conformed EDL. "
+               "Media must already be in the Media Pool for it to link.",
+    }[target]
+
+
+def _version_note(target: str) -> Dict[str, Any]:
+    if target != "drt":
+        return {
+            "targets": "any Resolve that reads this format",
+            "note": "No project-version gate applies to OTIO or EDL.",
+        }
+    return {
+        "targets": "Resolve 21.0 (project version 17)",
+        "older_builds": (
+            "An older Resolve refuses a newer project version. Use the advanced server's "
+            "`drt(action='downgrade')` to stamp it down — verified map: 18.0.4 -> 11, "
+            "19.1.x -> 14, 21.0 -> 17."
+        ),
+        "project_versions": DRT_PROJECT_VERSIONS,
+    }
+
+
+# ── the offer attached to a connection failure ───────────────────────────────
+
+
+def offline_alternative(*, action: Optional[str] = None) -> Dict[str, Any]:
+    """The block a not-connected error carries. Describes an option; performs nothing."""
+    report = capabilities()
+    if not report["available"]:
+        return {
+            "available": False,
+            "reason": (
+                "Offline interchange authoring needs Node and the bundled authoring "
+                "module; one of them is missing from this install."
+            ),
+        }
+    return {
+        "available": True,
+        "what": (
+            "Resolve is unreachable, but a timeline can still be written as a file you "
+            "import in one action."
+        ),
+        "call": (
+            "timeline(action='author_offline', params={'clips': [{'path': ..., "
+            "'start_frame': ..., 'end_frame': ...}], 'output_path': ..., 'target': 'drt'})"
+        ),
+        "targets": list(TARGETS),
+        "does_not": (
+            "This does not complete the operation that just failed"
+            + (f" ({action})" if action else "")
+            + ". Nothing is added to a Resolve project until the file is imported."
+        ),
+    }