inline-core 1.1.1__py3-none-any.whl

inline_core/studio/moodboard.py

@@ -0,0 +1,400 @@
+"""Moodboard persistence — items (assets, text, frames, core nodes, layers, previews, director,
+trim, prompt) and connectors — ported from the Studio ``electron/main/moodboard/store.ts``.
+
+Operates on an open ``sqlite3.Connection``. The frame-creating adders compose with the frames
+domain. Adders that need a fal node def (``add_gen_node``) take the model's kind/params/title from
+the caller (the fal defs live studio-side).
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+import uuid
+from typing import Any
+
+from . import frames as fr
+
+_ITEM_COLUMNS = (
+    "id, project_id, type, asset_id, frame_id, parent_id, data, x, y, width, height, rotation, "
+    "z_index, created_at, updated_at"
+)
+
+_DEFAULT_SIZE = {"image": (320, 180), "video": (360, 203), "audio": (320, 80)}
+
+_DEFAULT_TEXT = {
+    "text": "Text",
+    "fontSize": 18,
+    "bold": False,
+    "italic": False,
+    "underline": False,
+    "color": "#e4e4e7",
+    "align": "left",
+}
+
+
+def _now() -> int:
+    return int(time.time() * 1000)
+
+
+def _uuid() -> str:
+    return str(uuid.uuid4())
+
+
+def _project_id(conn: sqlite3.Connection) -> str:
+    row = conn.execute("SELECT id FROM project LIMIT 1").fetchone()
+    if row is None:
+        raise RuntimeError("No project is open.")
+    return row["id"]
+
+
+def _parse(raw: str | None) -> dict[str, Any]:
+    if not raw:
+        return {}
+    try:
+        parsed = json.loads(raw)
+    except (json.JSONDecodeError, TypeError):
+        return {}
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def _row_to_item(row: sqlite3.Row) -> dict[str, Any]:
+    return {
+        "id": row["id"],
+        "projectId": row["project_id"],
+        "type": row["type"],
+        "assetId": row["asset_id"],
+        "frameId": row["frame_id"],
+        "parentId": row["parent_id"],
+        "data": _parse(row["data"]),
+        "x": row["x"],
+        "y": row["y"],
+        "width": row["width"],
+        "height": row["height"],
+        "rotation": row["rotation"],
+        "zIndex": row["z_index"],
+        "createdAt": row["created_at"],
+        "updatedAt": row["updated_at"],
+    }
+
+
+def _row_to_connector(row: sqlite3.Row) -> dict[str, Any]:
+    return {
+        "id": row["id"],
+        "projectId": row["project_id"],
+        "fromItemId": row["from_item_id"],
+        "toItemId": row["to_item_id"],
+        "label": row["label"],
+        "data": _parse(row["data"]),
+        "createdAt": row["created_at"],
+    }
+
+
+def get_item(conn: sqlite3.Connection, item_id: str) -> dict[str, Any]:
+    row = conn.execute("SELECT * FROM moodboard_items WHERE id = ?", (item_id,)).fetchone()
+    if row is None:
+        raise ValueError("Moodboard item not found.")
+    return _row_to_item(row)
+
+
+def list_items(conn: sqlite3.Connection) -> list[dict[str, Any]]:
+    rows = conn.execute("SELECT * FROM moodboard_items").fetchall()
+    return [_row_to_item(r) for r in rows]
+
+
+def list_board(conn: sqlite3.Connection) -> dict[str, Any]:
+    items = [_row_to_item(r) for r in conn.execute("SELECT * FROM moodboard_items").fetchall()]
+    connectors = [
+        _row_to_connector(r) for r in conn.execute("SELECT * FROM moodboard_connectors").fetchall()
+    ]
+    return {"items": items, "connectors": connectors}
+
+
+def _next_z(conn: sqlite3.Connection) -> int:
+    row = conn.execute("SELECT MAX(z_index) AS z FROM moodboard_items").fetchone()
+    return (row["z"] or 0) + 1
+
+
+def _insert_item(
+    conn: sqlite3.Connection,
+    *,
+    item_type: str,
+    x: float,
+    y: float,
+    width: float,
+    height: float,
+    data: dict[str, Any] | None = None,
+    asset_id: str | None = None,
+    frame_id: str | None = None,
+    z_index: int | None = None,
+) -> dict[str, Any]:
+    now = _now()
+    item = {
+        "id": _uuid(),
+        "project_id": _project_id(conn),
+        "type": item_type,
+        "asset_id": asset_id,
+        "frame_id": frame_id,
+        "parent_id": None,
+        "data": json.dumps(data or {}),
+        "x": x,
+        "y": y,
+        "width": width,
+        "height": height,
+        "rotation": 0,
+        "z_index": z_index if z_index is not None else _next_z(conn),
+        "created_at": now,
+        "updated_at": now,
+    }
+    conn.execute(
+        f"INSERT INTO moodboard_items ({_ITEM_COLUMNS}) VALUES "
+        "(:id, :project_id, :type, :asset_id, :frame_id, :parent_id, :data, :x, :y, :width, "
+        ":height, :rotation, :z_index, :created_at, :updated_at)",
+        item,
+    )
+    return get_item(conn, item["id"])
+
+
+def add_asset(conn: sqlite3.Connection, asset_id: str, x: float, y: float) -> dict[str, Any]:
+    asset = conn.execute("SELECT id, kind FROM assets WHERE id = ?", (asset_id,)).fetchone()
+    if asset is None:
+        raise ValueError("Asset not found.")
+    w, h = _DEFAULT_SIZE.get(asset["kind"], (320, 180))
+    return _insert_item(conn, item_type="asset", x=x, y=y, width=w, height=h, asset_id=asset_id)
+
+
+def add_text(conn: sqlite3.Connection, x: float, y: float) -> dict[str, Any]:
+    return _insert_item(
+        conn, item_type="text", x=x, y=y, width=200, height=60, data={"text": dict(_DEFAULT_TEXT)}
+    )
+
+
+def add_core_node(conn: sqlite3.Connection, core_type: str, x: float, y: float) -> dict[str, Any]:
+    return _insert_item(
+        conn, item_type="core", x=x, y=y, width=200, height=120,
+        data={"core": {"type": core_type, "params": {}}},
+    )
+
+
+def add_frame_item(conn: sqlite3.Connection, frame_id: str, x: float, y: float) -> dict[str, Any]:
+    return _insert_item(conn, item_type="frame", x=x, y=y, width=220, height=200, frame_id=frame_id)
+
+
+def add_frame_from_asset(
+    conn: sqlite3.Connection, asset_id: str, x: float, y: float
+) -> dict[str, Any]:
+    frame = fr.add_from_asset(conn, asset_id)
+    return add_frame_item(conn, frame["id"], x, y)
+
+
+def add_empty_frame(conn: sqlite3.Connection, x: float, y: float) -> dict[str, Any]:
+    frame = fr.create_empty_frame(conn)
+    return add_frame_item(conn, frame["id"], x, y)
+
+
+def add_gen_node(
+    conn: sqlite3.Connection,
+    model_id: str,
+    x: float,
+    y: float,
+    *,
+    kind: str,
+    params: dict[str, Any],
+    title: str,
+) -> dict[str, Any]:
+    frame = fr.create_fal_frame(conn, model_id, kind, params, title)
+    return _insert_item(
+        conn, item_type="frame", x=x, y=y, width=240, height=380, frame_id=frame["id"]
+    )
+
+
+def add_layer(conn: sqlite3.Connection, x: float, y: float) -> dict[str, Any]:
+    return _insert_item(
+        conn, item_type="layer", x=x, y=y, width=420, height=300, data={"name": "Layer"}, z_index=0
+    )
+
+
+def add_preview(conn: sqlite3.Connection, x: float, y: float) -> dict[str, Any]:
+    return _insert_item(conn, item_type="preview", x=x, y=y, width=280, height=220)
+
+
+def add_director(conn: sqlite3.Connection, x: float, y: float) -> dict[str, Any]:
+    return _insert_item(
+        conn, item_type="director", x=x, y=y, width=440, height=400,
+        data={"name": "Director", "director": {"width": 1920, "height": 1080, "fps": 30}},
+    )
+
+
+def add_trim(conn: sqlite3.Connection, x: float, y: float) -> dict[str, Any]:
+    return _insert_item(
+        conn, item_type="trim", x=x, y=y, width=360, height=170,
+        data={"trim": {"inPoint": 0, "outPoint": 0}},
+    )
+
+
+def add_prompt(conn: sqlite3.Connection, x: float, y: float) -> dict[str, Any]:
+    return _insert_item(
+        conn, item_type="prompt", x=x, y=y, width=240, height=120, data={"promptText": ""}
+    )
+
+
+def update_item(conn: sqlite3.Connection, item_id: str, patch: dict[str, Any]) -> dict[str, Any]:
+    get_item(conn, item_id)  # ensure exists
+    sets: list[str] = []
+    params: dict[str, Any] = {"id": item_id, "updated_at": _now()}
+    for key, column in (
+        ("x", "x"), ("y", "y"), ("width", "width"), ("height", "height"),
+        ("rotation", "rotation"), ("zIndex", "z_index"),
+    ):
+        value = patch.get(key)
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            sets.append(f"{column} = :{column}")
+            params[column] = value
+    if "data" in patch:
+        sets.append("data = :data")
+        params["data"] = json.dumps(patch["data"])
+    if "parentId" in patch:
+        sets.append("parent_id = :parent_id")
+        params["parent_id"] = patch["parentId"]
+    sets.append("updated_at = :updated_at")
+    conn.execute(f"UPDATE moodboard_items SET {', '.join(sets)} WHERE id = :id", params)
+    return get_item(conn, item_id)
+
+
+def set_core_node_output(conn: sqlite3.Connection, item_id: str, output: dict[str, Any]) -> None:
+    """Store the latest render a Core media node produced, for display on the node."""
+    try:
+        item = get_item(conn, item_id)
+    except ValueError:
+        return
+    core = (item.get("data") or {}).get("core")
+    if item["type"] != "core" or not core:
+        return
+    update_item(conn, item_id, {"data": {**item["data"], "core": {**core, "output": output}}})
+
+
+def delete_item(conn: sqlite3.Connection, item_id: str) -> None:
+    conn.execute(
+        "DELETE FROM moodboard_connectors WHERE from_item_id = ? OR to_item_id = ?",
+        (item_id, item_id),
+    )
+    conn.execute("DELETE FROM moodboard_items WHERE id = ?", (item_id,))
+
+
+def replace_board(
+    conn: sqlite3.Connection, items: list[dict[str, Any]], connectors: list[dict[str, Any]]
+) -> None:
+    """Replace the whole board (undo/redo restore), preserving ids, in one transaction."""
+    pid = _project_id(conn)
+    conn.execute("DELETE FROM moodboard_connectors WHERE project_id = ?", (pid,))
+    conn.execute("DELETE FROM moodboard_items WHERE project_id = ?", (pid,))
+    for it in items:
+        conn.execute(
+            f"INSERT INTO moodboard_items ({_ITEM_COLUMNS}) VALUES "
+            "(:id, :project_id, :type, :asset_id, :frame_id, :parent_id, :data, :x, :y, :width, "
+            ":height, :rotation, :z_index, :created_at, :updated_at)",
+            {
+                "id": it["id"],
+                "project_id": pid,
+                "type": it["type"],
+                "asset_id": it.get("assetId"),
+                "frame_id": it.get("frameId"),
+                "parent_id": it.get("parentId"),
+                "data": json.dumps(it.get("data") or {}),
+                "x": it["x"],
+                "y": it["y"],
+                "width": it["width"],
+                "height": it["height"],
+                "rotation": it.get("rotation", 0),
+                "z_index": it.get("zIndex", 0),
+                "created_at": it.get("createdAt", _now()),
+                "updated_at": it.get("updatedAt", _now()),
+            },
+        )
+    for c in connectors:
+        conn.execute(
+            "INSERT INTO moodboard_connectors "
+            "(id, project_id, from_item_id, to_item_id, label, data, created_at) "
+            "VALUES (:id, :project_id, :from_item_id, :to_item_id, :label, :data, :created_at)",
+            {
+                "id": c["id"],
+                "project_id": pid,
+                "from_item_id": c["fromItemId"],
+                "to_item_id": c["toItemId"],
+                "label": c.get("label"),
+                "data": json.dumps(c.get("data") or {}),
+                "created_at": c.get("createdAt", _now()),
+            },
+        )
+
+
+def create_connector(
+    conn: sqlite3.Connection,
+    from_item_id: str,
+    to_item_id: str,
+    source_handle: str | None = None,
+    target_handle: str | None = None,
+) -> dict[str, Any]:
+    get_item(conn, from_item_id)
+    get_item(conn, to_item_id)
+    connector = {
+        "id": _uuid(),
+        "projectId": _project_id(conn),
+        "fromItemId": from_item_id,
+        "toItemId": to_item_id,
+        "label": None,
+        "data": {"sourceHandle": source_handle, "targetHandle": target_handle},
+        "createdAt": _now(),
+    }
+    conn.execute(
+        "INSERT INTO moodboard_connectors "
+        "(id, project_id, from_item_id, to_item_id, label, data, created_at) "
+        "VALUES (?, ?, ?, ?, ?, ?, ?)",
+        (
+            connector["id"], connector["projectId"], from_item_id, to_item_id, None,
+            json.dumps(connector["data"]), connector["createdAt"],
+        ),
+    )
+    return connector
+
+
+def delete_connector(conn: sqlite3.Connection, connector_id: str) -> None:
+    conn.execute("DELETE FROM moodboard_connectors WHERE id = ?", (connector_id,))
+
+
+def set_connector_volume(conn: sqlite3.Connection, connector_id: str, volume: float) -> None:
+    row = conn.execute(
+        "SELECT data FROM moodboard_connectors WHERE id = ?", (connector_id,)
+    ).fetchone()
+    data = _parse(row["data"]) if row else {}
+    data["volume"] = min(1.0, max(0.0, volume))
+    conn.execute(
+        "UPDATE moodboard_connectors SET data = ? WHERE id = ?",
+        (json.dumps(data), connector_id),
+    )
+
+
+def prompt_text_for_frame(conn: sqlite3.Connection, frame_id: str) -> str | None:
+    """The text of a Prompt node wired into this frame's canvas node on the 'prompt' handle."""
+    nodes = conn.execute(
+        "SELECT id FROM moodboard_items WHERE frame_id = ? AND type = 'frame'", (frame_id,)
+    ).fetchall()
+    for node in nodes:
+        conns = conn.execute(
+            "SELECT from_item_id, data FROM moodboard_connectors WHERE to_item_id = ?",
+            (node["id"],),
+        ).fetchall()
+        for c in conns:
+            if _parse(c["data"]).get("targetHandle") != "prompt":
+                continue
+            src = conn.execute(
+                "SELECT data FROM moodboard_items WHERE id = ? AND type = 'prompt'",
+                (c["from_item_id"],),
+            ).fetchone()
+            if src is None:
+                continue
+            text = _parse(src["data"]).get("promptText")
+            if isinstance(text, str) and text.strip():
+                return text
+    return None

inline_core/studio/schema.py

@@ -0,0 +1,278 @@
+"""SQLite schema for a project's ``project.db`` — a faithful port of the Studio TypeScript
+``electron/main/db/schema.ts`` (SCHEMA_VERSION 14). The DB is the source of truth for a project;
+"save" is implicit. Bumping ``SCHEMA_VERSION`` + adding a migration is how the schema evolves.
+
+Kept byte-compatible with the Node schema so Core can open existing ``.inlinestudio`` projects: same
+tables, same column names, same ``user_version`` stamping, and the same additive/rename migrations.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+
+SCHEMA_VERSION = 14
+
+SCHEMA_SQL = """
+CREATE TABLE IF NOT EXISTS project (
+  id          TEXT PRIMARY KEY,
+  name        TEXT NOT NULL,
+  created_at  INTEGER NOT NULL,
+  updated_at  INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS sequences (
+  id          TEXT PRIMARY KEY,
+  project_id  TEXT NOT NULL,
+  name        TEXT NOT NULL,
+  position    INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS frames (
+  id                   TEXT PRIMARY KEY,
+  sequence_id          TEXT NOT NULL,
+  name                 TEXT NOT NULL,
+  kind                 TEXT NOT NULL,
+  position             INTEGER NOT NULL,
+  input_asset_id       TEXT,
+  hero_take_id         TEXT,
+  provider             TEXT NOT NULL DEFAULT 'comfy',
+  model_id             TEXT,
+  params               TEXT NOT NULL DEFAULT '{}',
+  workflow_template_id TEXT,
+  comfy_workflow_name  TEXT,
+  comfy_workflow_ready INTEGER NOT NULL DEFAULT 0,
+  created_at           INTEGER NOT NULL,
+  updated_at           INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS takes (
+  id              TEXT PRIMARY KEY,
+  frame_id         TEXT NOT NULL,
+  file_path       TEXT NOT NULL,
+  kind            TEXT NOT NULL,
+  params          TEXT NOT NULL,
+  comfy_prompt_id TEXT,
+  created_at      INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS frame_inputs (
+  id             TEXT PRIMARY KEY,
+  frame_id        TEXT NOT NULL,
+  asset_id       TEXT,
+  source_frame_id TEXT,
+  position       INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS asset_folders (
+  id          TEXT PRIMARY KEY,
+  project_id  TEXT NOT NULL,
+  name        TEXT NOT NULL,
+  parent_id   TEXT,
+  created_at  INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS assets (
+  id           TEXT PRIMARY KEY,
+  project_id   TEXT NOT NULL,
+  folder_id    TEXT,
+  name         TEXT NOT NULL,
+  file_path    TEXT NOT NULL,
+  kind         TEXT NOT NULL,
+  thumb_path   TEXT,
+  preview_path TEXT,
+  created_at   INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS moodboard_items (
+  id          TEXT PRIMARY KEY,
+  project_id  TEXT NOT NULL,
+  type        TEXT NOT NULL DEFAULT 'asset',
+  asset_id    TEXT,
+  frame_id     TEXT,
+  parent_id   TEXT,
+  data        TEXT,
+  x           REAL NOT NULL,
+  y           REAL NOT NULL,
+  width       REAL NOT NULL,
+  height      REAL NOT NULL,
+  rotation    REAL NOT NULL DEFAULT 0,
+  z_index     INTEGER NOT NULL DEFAULT 0,
+  created_at  INTEGER NOT NULL DEFAULT 0,
+  updated_at  INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS moodboard_connectors (
+  id           TEXT PRIMARY KEY,
+  project_id   TEXT NOT NULL,
+  from_item_id TEXT NOT NULL,
+  to_item_id   TEXT NOT NULL,
+  label        TEXT,
+  data         TEXT,
+  created_at   INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS workflow_templates (
+  id          TEXT PRIMARY KEY,
+  project_id  TEXT NOT NULL,
+  name        TEXT NOT NULL,
+  graph       TEXT NOT NULL,
+  params      TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS pending_generation (
+  id           TEXT PRIMARY KEY,
+  frame_id     TEXT NOT NULL,
+  model_id     TEXT NOT NULL,
+  endpoint     TEXT NOT NULL,
+  request_id   TEXT NOT NULL,
+  status_url   TEXT NOT NULL,
+  response_url TEXT NOT NULL,
+  params       TEXT NOT NULL,
+  created_at   INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_frames_sequence ON frames(sequence_id);
+CREATE INDEX IF NOT EXISTS idx_takes_frame ON takes(frame_id);
+CREATE INDEX IF NOT EXISTS idx_frame_inputs_frame ON frame_inputs(frame_id);
+CREATE INDEX IF NOT EXISTS idx_assets_project ON assets(project_id);
+CREATE INDEX IF NOT EXISTS idx_assets_folder ON assets(folder_id);
+CREATE INDEX IF NOT EXISTS idx_asset_folders_parent ON asset_folders(parent_id);
+CREATE INDEX IF NOT EXISTS idx_moodboard_items_project ON moodboard_items(project_id);
+CREATE INDEX IF NOT EXISTS idx_moodboard_connectors_project ON moodboard_connectors(project_id);
+"""
+
+
+def apply_schema(conn: sqlite3.Connection) -> None:
+    """Create tables (idempotent) and stamp the schema version. Mirrors ``applySchema``."""
+    conn.execute("PRAGMA journal_mode = WAL")
+    conn.execute("PRAGMA foreign_keys = ON")
+    from_version = int(conn.execute("PRAGMA user_version").fetchone()[0])
+    # Additive column migrations run before SCHEMA_SQL (its indexes reference new columns).
+    _migrate_columns(conn)
+    conn.executescript(SCHEMA_SQL)
+    _run_data_migrations(conn, from_version)
+    _stamp_version(conn)
+    conn.commit()
+
+
+def _run_data_migrations(conn: sqlite3.Connection, from_version: int) -> None:
+    # v5 -> v6: move each frame's single input_asset_id into the new frame_inputs table. Idempotent.
+    if from_version < 6:
+        conn.execute(
+            """
+            INSERT INTO frame_inputs (id, frame_id, asset_id, position)
+            SELECT lower(hex(randomblob(16))), id, input_asset_id, 0
+            FROM frames
+            WHERE input_asset_id IS NOT NULL
+              AND NOT EXISTS (SELECT 1 FROM frame_inputs si WHERE si.frame_id = frames.id);
+            """
+        )
+
+
+def _migrate_columns(conn: sqlite3.Connection) -> None:
+    """Additive column + rename migrations for pre-existing projects (no-ops on fresh DBs)."""
+    _migrate_renames(conn)  # v7 -> v8: shot -> frame
+
+    _add_column_if_missing(conn, "assets", "folder_id", "TEXT")
+
+    _add_column_if_missing(conn, "moodboard_items", "type", "TEXT NOT NULL DEFAULT 'asset'")
+    _add_column_if_missing(conn, "moodboard_items", "data", "TEXT")
+    _add_column_if_missing(conn, "moodboard_items", "rotation", "REAL NOT NULL DEFAULT 0")
+    _add_column_if_missing(conn, "moodboard_items", "z_index", "INTEGER NOT NULL DEFAULT 0")
+    _add_column_if_missing(conn, "moodboard_items", "created_at", "INTEGER NOT NULL DEFAULT 0")
+    _add_column_if_missing(conn, "moodboard_items", "updated_at", "INTEGER NOT NULL DEFAULT 0")
+
+    _add_column_if_missing(conn, "frames", "input_asset_id", "TEXT")
+    _add_column_if_missing(conn, "frames", "comfy_workflow_name", "TEXT")
+
+    _add_column_if_missing(conn, "moodboard_items", "frame_id", "TEXT")
+    _add_column_if_missing(conn, "moodboard_items", "parent_id", "TEXT")
+    _add_column_if_missing(conn, "frame_inputs", "source_frame_id", "TEXT")
+
+    _relax_frame_inputs_asset_id(conn)  # v8 -> v9: asset_id must be nullable
+
+    _add_column_if_missing(conn, "assets", "preview_path", "TEXT")
+    _add_column_if_missing(conn, "frames", "comfy_workflow_ready", "INTEGER NOT NULL DEFAULT 0")
+
+    # v12 -> v13: fal provider + model id + params.
+    _add_column_if_missing(conn, "frames", "provider", "TEXT NOT NULL DEFAULT 'comfy'")
+    _add_column_if_missing(conn, "frames", "model_id", "TEXT")
+    _add_column_if_missing(conn, "frames", "params", "TEXT NOT NULL DEFAULT '{}'")
+
+
+def _relax_frame_inputs_asset_id(conn: sqlite3.Connection) -> None:
+    """Rebuild frame_inputs to drop a legacy NOT NULL on asset_id. Idempotent."""
+    if not _table_exists(conn, "frame_inputs"):
+        return
+    cols = conn.execute("PRAGMA table_info(frame_inputs)").fetchall()
+    asset = next((c for c in cols if c[1] == "asset_id"), None)
+    if asset is None or asset[3] == 0:  # c[3] = notnull flag
+        return
+    conn.executescript(
+        """
+        CREATE TABLE frame_inputs_new (
+          id              TEXT PRIMARY KEY,
+          frame_id        TEXT NOT NULL,
+          asset_id        TEXT,
+          source_frame_id TEXT,
+          position        INTEGER NOT NULL
+        );
+        INSERT INTO frame_inputs_new (id, frame_id, asset_id, source_frame_id, position)
+          SELECT id, frame_id, asset_id, source_frame_id, position FROM frame_inputs;
+        DROP TABLE frame_inputs;
+        ALTER TABLE frame_inputs_new RENAME TO frame_inputs;
+        """
+    )
+
+
+def _migrate_renames(conn: sqlite3.Connection) -> None:
+    """v7 -> v8: the "shot" domain was renamed to "frame". Guarded, so a no-op on fresh DBs."""
+    if _table_exists(conn, "shots") and not _table_exists(conn, "frames"):
+        conn.execute("ALTER TABLE shots RENAME TO frames")
+    if _table_exists(conn, "shot_inputs") and not _table_exists(conn, "frame_inputs"):
+        conn.execute("ALTER TABLE shot_inputs RENAME TO frame_inputs")
+    _rename_column_if_exists(conn, "frame_inputs", "shot_id", "frame_id")
+    _rename_column_if_exists(conn, "frame_inputs", "source_shot_id", "source_frame_id")
+    _rename_column_if_exists(conn, "takes", "shot_id", "frame_id")
+    _rename_column_if_exists(conn, "moodboard_items", "shot_id", "frame_id")
+    if _table_exists(conn, "moodboard_items"):
+        conn.execute("UPDATE moodboard_items SET type='frame' WHERE type='shot'")
+    conn.executescript(
+        "DROP INDEX IF EXISTS idx_shots_sequence;"
+        "DROP INDEX IF EXISTS idx_takes_shot;"
+        "DROP INDEX IF EXISTS idx_shot_inputs_shot;"
+    )
+
+
+def _table_exists(conn: sqlite3.Connection, table: str) -> bool:
+    row = conn.execute(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name=?", (table,)
+    ).fetchone()
+    return row is not None
+
+
+def _column_names(conn: sqlite3.Connection, table: str) -> set[str]:
+    return {c[1] for c in conn.execute(f"PRAGMA table_info({table})").fetchall()}
+
+
+def _rename_column_if_exists(conn: sqlite3.Connection, table: str, old: str, new: str) -> None:
+    if not _table_exists(conn, table):
+        return
+    cols = _column_names(conn, table)
+    if old in cols and new not in cols:
+        conn.execute(f"ALTER TABLE {table} RENAME COLUMN {old} TO {new}")
+
+
+def _add_column_if_missing(
+    conn: sqlite3.Connection, table: str, column: str, definition: str
+) -> None:
+    if not _table_exists(conn, table):
+        return
+    if column not in _column_names(conn, table):
+        conn.execute(f"ALTER TABLE {table} ADD COLUMN {column} {definition}")
+
+
+def _stamp_version(conn: sqlite3.Connection) -> None:
+    current = int(conn.execute("PRAGMA user_version").fetchone()[0])
+    if current < SCHEMA_VERSION:
+        conn.execute(f"PRAGMA user_version = {SCHEMA_VERSION}")