@bbigbang/core 0.1.0

package/dist/web/panels.js

@@ -0,0 +1,904 @@
+import { randomUUID } from 'node:crypto';
+export function insertPanel(db, params) {
+    const id = params.id ?? randomUUID();
+    const now = params.createdAt ?? Date.now();
+    db.prepare(`INSERT INTO panels(
+       id, agent_id, conversation_id, owner_user_id, handle, scope_type, scope_id,
+       component, props_json, actions_json, dataset_source_json, row_count, status, progress_json, result_json, version,
+       created_by_run_id, created_at, updated_at
+     )
+     VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, params.agentId, params.conversationId, params.ownerUserId ?? null, normalizePanelHandle(params.handle), params.scopeType, params.scopeId ?? null, params.component, JSON.stringify(params.props ?? {}), JSON.stringify(params.actions ?? []), params.datasetSource ? JSON.stringify(params.datasetSource) : null, params.rowCount ?? 0, params.status ?? 'idle', params.progress == null ? null : JSON.stringify(params.progress), params.result == null ? null : JSON.stringify(params.result), params.version ?? 1, params.createdByRunId ?? null, now, params.updatedAt ?? now);
+    return id;
+}
+function normalizePanelHandle(handle) {
+    const normalized = handle?.trim() ?? '';
+    return normalized || null;
+}
+export function insertPanelRows(db, rows) {
+    const insert = db.prepare(`INSERT INTO panel_rows(
+       panel_id, row_index, row_id, fields_json, media_json,
+       node_id, cached_asset_ids_json
+     )
+     VALUES(?, ?, ?, ?, ?, ?, ?)`);
+    for (const row of rows) {
+        insert.run(row.panelId, row.rowIndex, row.rowId ?? null, JSON.stringify(row.fields), JSON.stringify(row.media), row.nodeId ?? null, JSON.stringify(row.cachedAssetIds ?? {}));
+    }
+}
+export function getPanelById(db, id) {
+    const row = db.prepare(`SELECT
+       id, agent_id as agentId, conversation_id as conversationId, owner_user_id as ownerUserId,
+       handle,
+       scope_type as scopeType, scope_id as scopeId,
+       component, props_json as propsJson, actions_json as actionsJson,
+       dataset_source_json as datasetSourceJson,
+       row_count as rowCount, status, progress_json as progressJson,
+       result_json as resultJson, version, created_by_run_id as createdByRunId,
+       created_at as createdAt, updated_at as updatedAt, archived_at as archivedAt
+     FROM panels
+     WHERE id = ?
+     LIMIT 1`).get(id);
+    if (!row)
+        return null;
+    const datasetSource = parseNullableJsonObject(row.datasetSourceJson);
+    return {
+        id: row.id,
+        agentId: row.agentId,
+        conversationId: row.conversationId,
+        ownerUserId: row.ownerUserId ?? undefined,
+        handle: row.handle,
+        scopeType: row.scopeType,
+        scopeId: row.scopeId ?? undefined,
+        toolId: row.scopeType === 'tool' ? (row.scopeId ?? undefined) : undefined,
+        component: row.component,
+        props: parseJsonObject(row.propsJson),
+        actions: parseJsonArray(row.actionsJson),
+        rowCount: row.rowCount,
+        rowCountKnown: row.rowCount >= 0,
+        datasetSource: datasetSource ?? undefined,
+        status: normalizePanelStatus(row.status),
+        progress: parseNullableJsonObject(row.progressJson),
+        result: parseNullableJsonObject(row.resultJson),
+        version: row.version,
+        createdByRunId: row.createdByRunId ?? undefined,
+        createdAt: new Date(row.createdAt).toISOString(),
+        updatedAt: new Date(row.updatedAt).toISOString(),
+        archivedAt: row.archivedAt == null ? null : new Date(row.archivedAt).toISOString(),
+    };
+}
+export function getPanelByStableHandle(db, params) {
+    const ownerUserId = params.ownerUserId?.trim() ?? '';
+    const handle = normalizePanelHandle(params.handle);
+    if (!ownerUserId || !handle)
+        return null;
+    const row = db.prepare(`SELECT id
+       FROM panels
+      WHERE owner_user_id = ?
+        AND agent_id = ?
+        AND conversation_id = ?
+        AND handle = ?
+        AND archived_at IS NULL
+      LIMIT 1`).get(ownerUserId, params.agentId, params.conversationId, handle);
+    return row ? getPanelById(db, row.id) : null;
+}
+export function deletePanel(db, id) {
+    const result = db.prepare('DELETE FROM panels WHERE id = ?').run(id);
+    return result.changes > 0;
+}
+export function getPanelState(db, panelId, userId) {
+    const row = db.prepare(`SELECT panel_id as panelId, user_id as userId,
+            state_json as stateJson, updated_at as updatedAt
+     FROM panel_state
+     WHERE panel_id = ? AND user_id = ?
+     LIMIT 1`).get(panelId, userId);
+    if (!row)
+        return null;
+    return {
+        panelId: row.panelId,
+        userId: row.userId,
+        state: parseJsonObject(row.stateJson),
+        updatedAt: new Date(row.updatedAt).toISOString(),
+    };
+}
+export function upsertPanelState(db, panelId, userId, state) {
+    const now = Date.now();
+    db.prepare(`INSERT INTO panel_state(panel_id, user_id, state_json, updated_at)
+     VALUES(?, ?, ?, ?)
+     ON CONFLICT(panel_id, user_id)
+     DO UPDATE SET state_json = excluded.state_json, updated_at = excluded.updated_at`).run(panelId, userId, JSON.stringify(state), now);
+}
+export function listPanelsForConversation(db, conversationId) {
+    const rows = db.prepare(`SELECT
+       id, agent_id as agentId, conversation_id as conversationId, owner_user_id as ownerUserId,
+       handle,
+       scope_type as scopeType, scope_id as scopeId,
+       component, props_json as propsJson, actions_json as actionsJson,
+       dataset_source_json as datasetSourceJson,
+       row_count as rowCount, status, progress_json as progressJson,
+       result_json as resultJson, version, created_by_run_id as createdByRunId,
+       created_at as createdAt, updated_at as updatedAt, archived_at as archivedAt
+     FROM panels
+     WHERE conversation_id = ?
+     ORDER BY created_at DESC`).all(conversationId);
+    return rows.map((row) => ({
+        id: row.id,
+        agentId: row.agentId,
+        conversationId: row.conversationId,
+        ownerUserId: row.ownerUserId ?? undefined,
+        handle: row.handle,
+        scopeType: row.scopeType,
+        scopeId: row.scopeId ?? undefined,
+        toolId: row.scopeType === 'tool' ? (row.scopeId ?? undefined) : undefined,
+        component: row.component,
+        props: parseJsonObject(row.propsJson),
+        actions: parseJsonArray(row.actionsJson),
+        rowCount: row.rowCount,
+        rowCountKnown: row.rowCount >= 0,
+        datasetSource: parseNullableJsonObject(row.datasetSourceJson) ?? undefined,
+        status: normalizePanelStatus(row.status),
+        progress: parseNullableJsonObject(row.progressJson),
+        result: parseNullableJsonObject(row.resultJson),
+        version: row.version,
+        createdByRunId: row.createdByRunId ?? undefined,
+        createdAt: new Date(row.createdAt).toISOString(),
+        updatedAt: new Date(row.updatedAt).toISOString(),
+        archivedAt: row.archivedAt == null ? null : new Date(row.archivedAt).toISOString(),
+    }));
+}
+export function countPanelRows(db, panelId) {
+    const row = db.prepare(`SELECT COUNT(*) as count FROM panel_rows WHERE panel_id = ?`).get(panelId);
+    return row?.count ?? 0;
+}
+function parseJsonObject(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return {};
+    }
+}
+function parseNullableJsonObject(value) {
+    if (!value)
+        return null;
+    try {
+        const parsed = JSON.parse(value);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function normalizePanelStatus(value) {
+    if (value === 'running' || value === 'completed' || value === 'failed' || value === 'idle') {
+        return value;
+    }
+    if (value === 'ready')
+        return 'idle';
+    return 'idle';
+}
+const PANEL_FIELD_PATH_PATTERN = /^[A-Za-z_][A-Za-z0-9_:-]{0,63}(?:\.[A-Za-z_][A-Za-z0-9_:-]{0,63}){0,15}$/;
+export function getPanelFieldValue(fields, fieldPath) {
+    if (Object.prototype.hasOwnProperty.call(fields, fieldPath)) {
+        return fields[fieldPath];
+    }
+    if (!fieldPath.includes('.')) {
+        return fields[fieldPath];
+    }
+    let current = fields;
+    for (const segment of fieldPath.split('.')) {
+        if (!current || typeof current !== 'object' || Array.isArray(current)) {
+            return undefined;
+        }
+        const record = current;
+        if (!Object.prototype.hasOwnProperty.call(record, segment)) {
+            return undefined;
+        }
+        current = record[segment];
+    }
+    return current;
+}
+function quotedJsonPathForField(fieldPath, mode) {
+    if (!PANEL_FIELD_PATH_PATTERN.test(fieldPath)) {
+        throw new Error(`Unsafe panel field path: ${fieldPath}`);
+    }
+    const segments = mode === 'direct' ? [fieldPath] : fieldPath.split('.');
+    return `$${segments.map((segment) => `."${segment}"`).join('')}`;
+}
+function panelFieldJsonExtractExpression(fieldPath) {
+    const directPath = quotedJsonPathForField(fieldPath, 'direct');
+    const nestedPath = quotedJsonPathForField(fieldPath, 'nested');
+    const directExtract = `json_extract(fields_json, '${directPath}')`;
+    if (directPath === nestedPath)
+        return directExtract;
+    return `COALESCE(${directExtract}, json_extract(fields_json, '${nestedPath}'))`;
+}
+function toSqlJsonValue(value) {
+    if (typeof value === 'boolean')
+        return value ? 1 : 0;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string')
+        return value;
+    return null;
+}
+export function listPanelRows(db, panelId, options) {
+    const limit = Math.min(Math.max(1, options.limit), 200);
+    let cursorData = null;
+    if (options.cursor) {
+        try {
+            cursorData = JSON.parse(Buffer.from(options.cursor, 'base64').toString('utf8'));
+        }
+        catch {
+            cursorData = null;
+        }
+    }
+    const conditions = ['panel_id = ?'];
+    const params = [panelId];
+    if (options.filterField && options.filterValue !== undefined) {
+        conditions.push(`${panelFieldJsonExtractExpression(options.filterField)} = ?`);
+        params.push(toSqlJsonValue(options.filterValue));
+    }
+    if (options.sortField && options.sortDirection) {
+        const sortField = options.sortField;
+        const direction = options.sortDirection;
+        const isNumericSort = options.sortFieldType === 'number';
+        const fieldExtract = panelFieldJsonExtractExpression(sortField);
+        const extract = isNumericSort
+            ? `COALESCE(CAST(${fieldExtract} AS REAL), 0)`
+            : fieldExtract;
+        if (cursorData && cursorData.ri !== undefined) {
+            if (direction === 'asc') {
+                conditions.push(`(${extract} > ? OR (${extract} = ? AND row_index > ?))`);
+                const sortValue = toSqlJsonValue(cursorData.sv);
+                params.push(sortValue, sortValue, cursorData.ri);
+            }
+            else {
+                conditions.push(`(${extract} < ? OR (${extract} = ? AND row_index < ?))`);
+                const sortValue = toSqlJsonValue(cursorData.sv);
+                params.push(sortValue, sortValue, cursorData.ri);
+            }
+        }
+        const orderBy = direction === 'asc' ? 'ASC' : 'DESC';
+        const tieBreaker = direction === 'asc' ? 'ASC' : 'DESC';
+        const sql = `SELECT row_index as rowIndex, row_id as rowId, fields_json as fieldsJson, media_json as mediaJson
+      FROM panel_rows
+      WHERE ${conditions.join(' AND ')}
+      ORDER BY ${extract} ${orderBy}, row_index ${tieBreaker}
+      LIMIT ?`;
+        params.push(limit + 1);
+        const rows = db.prepare(sql).all(...params);
+        const hasMore = rows.length > limit;
+        const resultRows = hasMore ? rows.slice(0, limit) : rows;
+        const lastRow = resultRows[resultRows.length - 1];
+        const nextCursor = hasMore && lastRow
+            ? Buffer.from(JSON.stringify({
+                ri: lastRow.rowIndex,
+                sv: getPanelFieldValue(parseJsonObject(lastRow.fieldsJson), sortField),
+            }), 'utf8').toString('base64')
+            : null;
+        return {
+            rows: resultRows.map((r) => ({
+                rowIndex: r.rowIndex,
+                rowId: r.rowId,
+                fields: parseJsonObject(r.fieldsJson),
+                media: parseJsonObject(r.mediaJson),
+            })),
+            nextCursor,
+        };
+    }
+    // Default sort by row_index ASC
+    if (cursorData && cursorData.ri !== undefined) {
+        conditions.push('row_index > ?');
+        params.push(cursorData.ri);
+    }
+    const sql = `SELECT row_index as rowIndex, row_id as rowId, fields_json as fieldsJson, media_json as mediaJson
+    FROM panel_rows
+    WHERE ${conditions.join(' AND ')}
+    ORDER BY row_index ASC
+    LIMIT ?`;
+    params.push(limit + 1);
+    const rows = db.prepare(sql).all(...params);
+    const hasMore = rows.length > limit;
+    const resultRows = hasMore ? rows.slice(0, limit) : rows;
+    const lastRow = resultRows[resultRows.length - 1];
+    const nextCursor = hasMore && lastRow
+        ? Buffer.from(JSON.stringify({ ri: lastRow.rowIndex }), 'utf8').toString('base64')
+        : null;
+    return {
+        rows: resultRows.map((r) => ({
+            rowIndex: r.rowIndex,
+            rowId: r.rowId,
+            fields: parseJsonObject(r.fieldsJson),
+            media: parseJsonObject(r.mediaJson),
+        })),
+        nextCursor,
+    };
+}
+export function aggregatePanelRows(db, panelId, options) {
+    const conditions = ['panel_id = ?'];
+    const params = [panelId];
+    if (options.filterField && options.filterValue !== undefined) {
+        conditions.push(`${panelFieldJsonExtractExpression(options.filterField)} = ?`);
+        params.push(toSqlJsonValue(options.filterValue));
+    }
+    const rows = db.prepare(`SELECT fields_json as fieldsJson
+       FROM panel_rows
+      WHERE ${conditions.join(' AND ')}
+      ORDER BY row_index ASC`).all(...params);
+    return aggregatePanelFieldRecords(rows.map((row) => parseJsonObject(row.fieldsJson)), {
+        op: options.op,
+        field: options.field,
+    });
+}
+export function aggregatePanelFieldRecords(rows, options) {
+    const totalCount = rows.length;
+    if (options.op === 'count' && !options.field) {
+        return {
+            op: options.op,
+            field: null,
+            value: totalCount,
+            count: totalCount,
+            totalCount,
+            hasValue: true,
+        };
+    }
+    const field = options.field ?? null;
+    if (!field) {
+        return {
+            op: options.op,
+            field,
+            value: null,
+            count: 0,
+            totalCount,
+            hasValue: false,
+        };
+    }
+    if (options.op === 'count') {
+        const count = rows.filter((fields) => hasNonEmptyPanelValue(getPanelFieldValue(fields, field))).length;
+        return {
+            op: options.op,
+            field,
+            value: count,
+            count,
+            totalCount,
+            hasValue: true,
+        };
+    }
+    const values = rows
+        .map((fields) => toFinitePanelNumber(getPanelFieldValue(fields, field)))
+        .filter((value) => value !== null);
+    if (values.length === 0) {
+        return {
+            op: options.op,
+            field,
+            value: null,
+            count: 0,
+            totalCount,
+            hasValue: false,
+        };
+    }
+    let value;
+    switch (options.op) {
+        case 'sum':
+            value = values.reduce((total, item) => total + item, 0);
+            break;
+        case 'avg':
+            value = values.reduce((total, item) => total + item, 0) / values.length;
+            break;
+        case 'min':
+            value = Math.min(...values);
+            break;
+        case 'max':
+            value = Math.max(...values);
+            break;
+        default:
+            value = Number.NaN;
+            break;
+    }
+    return {
+        op: options.op,
+        field,
+        value: Number.isFinite(value) ? value : null,
+        count: values.length,
+        totalCount,
+        hasValue: Number.isFinite(value),
+    };
+}
+function hasNonEmptyPanelValue(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value === 'string')
+        return value.trim().length > 0;
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (typeof value === 'object')
+        return Object.keys(value).length > 0;
+    return true;
+}
+function toFinitePanelNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.trim() !== '') {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return null;
+}
+export function validateStateBlob(stateSchema, blob) {
+    const errors = [];
+    if (typeof blob !== 'object' || blob === null || Array.isArray(blob)) {
+        errors.push('State must be an object');
+        return errors;
+    }
+    const schemaObj = stateSchema;
+    if (schemaObj?.type === 'object' && schemaObj.properties) {
+        for (const [key, propSchema] of Object.entries(schemaObj.properties)) {
+            const value = blob[key];
+            if (value === undefined)
+                continue;
+            const expectedType = propSchema.type;
+            if (!expectedType)
+                continue;
+            const actualType = Array.isArray(value) ? 'array' : typeof value;
+            if (actualType !== expectedType) {
+                errors.push(`Property "${key}" must be of type ${expectedType}`);
+            }
+        }
+    }
+    return errors;
+}
+function parseJsonArray(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function getPanelRowByIndex(db, panelId, rowIndex) {
+    const row = db.prepare(`SELECT row_index as rowIndex, row_id as rowId, fields_json as fieldsJson, media_json as mediaJson,
+            node_id as nodeId, cached_asset_ids_json as cachedAssetIdsJson
+     FROM panel_rows
+     WHERE panel_id = ? AND row_index = ?
+     LIMIT 1`).get(panelId, rowIndex);
+    if (!row)
+        return null;
+    return {
+        rowIndex: row.rowIndex,
+        rowId: row.rowId,
+        fields: parseJsonObject(row.fieldsJson),
+        media: parseJsonObject(row.mediaJson),
+        nodeId: row.nodeId,
+        cachedAssetIds: parseJsonObject(row.cachedAssetIdsJson),
+    };
+}
+export function generatePanelRowId(db, panelId, preferredIndex) {
+    const existingRows = db.prepare(`SELECT row_id as rowId FROM panel_rows WHERE panel_id = ? AND row_id IS NOT NULL`).all(panelId);
+    const existing = new Set(existingRows.map((row) => row.rowId));
+    let candidate = `row-${preferredIndex}`;
+    let suffix = 1;
+    while (existing.has(candidate)) {
+        candidate = `row-${preferredIndex}-${suffix}`;
+        suffix += 1;
+    }
+    return candidate;
+}
+export function patchPanel(db, params) {
+    const current = getPanelById(db, params.panelId);
+    if (!current) {
+        return { ok: false, failureClass: 'panel_not_found', details: { panelId: params.panelId } };
+    }
+    if (current.archivedAt) {
+        return { ok: false, failureClass: 'panel_archived', details: { panelId: params.panelId } };
+    }
+    if (params.expectedVersion !== undefined && params.expectedVersion !== current.version) {
+        return {
+            ok: false,
+            failureClass: 'version_conflict',
+            details: {
+                panelId: params.panelId,
+                expectedVersion: params.expectedVersion,
+                currentVersion: current.version,
+                recommendedAction: 'Read the latest panel state/events/rows, merge user changes, then retry with the current version. Do not blindly overwrite saved user state or annotations.',
+            },
+        };
+    }
+    const changed = new Set();
+    const nextProps = params.props !== undefined
+        ? params.props
+        : params.propsPatch
+            ? { ...(current.props ?? {}), ...params.propsPatch }
+            : current.props ?? {};
+    if (params.props !== undefined || params.propsPatch)
+        changed.add('props');
+    const nextActions = params.actions ?? current.actions ?? [];
+    if (params.actions)
+        changed.add('actions');
+    const nextStatus = params.status ?? current.status;
+    if (params.status !== undefined)
+        changed.add('status');
+    const nextProgress = params.progress === undefined ? current.progress ?? null : params.progress;
+    if (params.progress !== undefined)
+        changed.add('progress');
+    const nextResult = params.result === undefined ? current.result ?? null : params.result;
+    if (params.result !== undefined)
+        changed.add('result');
+    const currentRows = listAllPanelRows(db, params.panelId);
+    let nextRows = currentRows;
+    if (params.rows) {
+        const rowPatch = params.rows.replace
+            ? {
+                ok: true,
+                rows: params.rows.replace.map((row, index) => toPanelRowMedia(params.panelId, index, normalizePatchRowId(row.rowId) ?? generatePanelRowId(db, params.panelId, index), row, params.defaultNodeId ?? null)),
+            }
+            : applyRowPatch(db, params.panelId, nextRows, params.rows, params.defaultNodeId ?? null);
+        if (!rowPatch.ok)
+            return rowPatch;
+        nextRows = rowPatch.rows;
+        changed.add('rows');
+    }
+    if (changed.size === 0) {
+        return {
+            ok: false,
+            failureClass: 'empty_patch',
+            details: { panelId: params.panelId, issue: 'At least one patch field is required.' },
+        };
+    }
+    const validation = params.validate?.({
+        panel: current,
+        props: nextProps,
+        actions: nextActions,
+        rows: nextRows,
+        status: nextStatus,
+        progress: nextProgress,
+        result: nextResult,
+    });
+    if (validation && !validation.ok) {
+        return validation;
+    }
+    const now = Date.now();
+    const nextVersion = current.version + 1;
+    let updateChanges = 0;
+    db.transaction(() => {
+        const updateResult = db.prepare(`UPDATE panels
+       SET props_json = ?,
+           actions_json = ?,
+           row_count = ?,
+           status = ?,
+           progress_json = ?,
+           result_json = ?,
+           dataset_source_json = ?,
+           version = ?,
+           updated_at = ?
+       WHERE id = ? AND version = ? AND archived_at IS NULL`).run(JSON.stringify(nextProps), JSON.stringify(nextActions), Number.isInteger(params.rowCount) ? params.rowCount : nextRows.length, nextStatus, nextProgress == null ? null : JSON.stringify(nextProgress), nextResult == null ? null : JSON.stringify(nextResult), params.datasetSource === undefined
+            ? current.datasetSource ? JSON.stringify(current.datasetSource) : null
+            : params.datasetSource ? JSON.stringify(params.datasetSource) : null, nextVersion, now, params.panelId, current.version);
+        updateChanges = updateResult.changes;
+        if (updateChanges === 0)
+            return;
+        if (params.rows) {
+            replacePanelRows(db, params.panelId, nextRows);
+            remapPanelSelectionState(db, params.panelId, currentRows, nextRows, now);
+        }
+    })();
+    if (updateChanges === 0) {
+        const latest = getPanelById(db, params.panelId);
+        if (latest?.archivedAt) {
+            return { ok: false, failureClass: 'panel_archived', details: { panelId: params.panelId } };
+        }
+        return {
+            ok: false,
+            failureClass: 'version_conflict',
+            details: {
+                panelId: params.panelId,
+                expectedVersion: current.version,
+                currentVersion: getPanelById(db, params.panelId)?.version ?? current.version,
+                recommendedAction: 'Read the latest panel state/events/rows, merge user changes, then retry with the current version. Do not blindly overwrite saved user state or annotations.',
+            },
+        };
+    }
+    const panel = getPanelById(db, params.panelId);
+    if (!panel) {
+        return { ok: false, failureClass: 'patch_failed', details: { panelId: params.panelId } };
+    }
+    return { ok: true, panel, changed: Array.from(changed) };
+}
+export function listAllPanelRows(db, panelId) {
+    const rows = db.prepare(`SELECT row_index as rowIndex, row_id as rowId, fields_json as fieldsJson, media_json as mediaJson,
+            node_id as nodeId, cached_asset_ids_json as cachedAssetIdsJson
+     FROM panel_rows
+     WHERE panel_id = ?
+     ORDER BY row_index ASC`).all(panelId);
+    return rows.map((row) => ({
+        rowIndex: row.rowIndex,
+        rowId: row.rowId,
+        fields: parseJsonObject(row.fieldsJson),
+        media: parseJsonObject(row.mediaJson),
+        nodeId: row.nodeId,
+        cachedAssetIds: parseJsonObject(row.cachedAssetIdsJson),
+    }));
+}
+function applyRowPatch(db, panelId, currentRows, patch, defaultNodeId) {
+    let rows = currentRows.map((row) => ({ ...row, fields: { ...row.fields }, media: { ...row.media } }));
+    const byRowId = new Map();
+    for (const row of rows) {
+        if (row.rowId)
+            byRowId.set(row.rowId, row.rowIndex);
+    }
+    const removeIds = Array.from(new Set((patch.removeRowIds ?? []).map((id) => id.trim()).filter(Boolean)));
+    if (removeIds.length) {
+        const missing = removeIds.filter((rowId) => !byRowId.has(rowId));
+        if (missing.length) {
+            return {
+                ok: false,
+                failureClass: 'row_not_found',
+                details: { panelId, rowIds: missing },
+            };
+        }
+        const removeSet = new Set(removeIds);
+        rows = rows.filter((row) => !row.rowId || !removeSet.has(row.rowId));
+        byRowId.clear();
+        rows.forEach((row, index) => {
+            if (row.rowId)
+                byRowId.set(row.rowId, index);
+        });
+    }
+    const appendRows = patch.append ?? [];
+    for (const input of appendRows) {
+        const rowId = normalizePatchRowId(input.rowId)
+            ?? generatePanelRowId(db, panelId, rows.length);
+        if (byRowId.has(rowId)) {
+            return {
+                ok: false,
+                failureClass: 'duplicate_row_id',
+                details: { panelId, rowId, issue: 'append rowId already exists' },
+            };
+        }
+        rows.push(toPanelRowMedia(panelId, rows.length, rowId, input, defaultNodeId));
+        byRowId.set(rowId, rows.length - 1);
+    }
+    const upsertRows = patch.upsert ?? [];
+    for (const input of upsertRows) {
+        const rowId = normalizePatchRowId(input.rowId);
+        if (!rowId) {
+            return {
+                ok: false,
+                failureClass: 'missing_row_id',
+                details: { panelId, issue: 'rows.upsert entries require rowId.' },
+            };
+        }
+        const existingIndex = byRowId.get(rowId);
+        if (existingIndex === undefined) {
+            rows.push(toPanelRowMedia(panelId, rows.length, rowId, input, defaultNodeId));
+            byRowId.set(rowId, rows.length - 1);
+            continue;
+        }
+        const existing = rows[existingIndex];
+        const nextMedia = { ...existing.media, ...(input.media ?? {}) };
+        const nextCachedAssetIds = { ...existing.cachedAssetIds };
+        for (const [slot, media] of Object.entries(input.media ?? {})) {
+            const previous = existing.media[slot];
+            if (!previous || previous.kind !== media.kind || previous.value !== media.value) {
+                delete nextCachedAssetIds[slot];
+            }
+        }
+        rows[existingIndex] = {
+            ...existing,
+            fields: { ...existing.fields, ...input.fields },
+            media: nextMedia,
+            cachedAssetIds: nextCachedAssetIds,
+        };
+    }
+    return {
+        ok: true,
+        rows: rows.map((row, index) => ({ ...row, rowIndex: index })),
+    };
+}
+function normalizePatchRowId(rowId) {
+    if (typeof rowId !== 'string')
+        return null;
+    const trimmed = rowId.trim();
+    return trimmed || null;
+}
+function toPanelRowMedia(panelId, rowIndex, rowId, row, defaultNodeId) {
+    return {
+        rowIndex,
+        rowId,
+        fields: { ...row.fields },
+        media: { ...(row.media ?? {}) },
+        nodeId: defaultNodeId,
+        cachedAssetIds: {},
+    };
+}
+function replacePanelRows(db, panelId, rows) {
+    db.prepare('DELETE FROM panel_rows WHERE panel_id = ?').run(panelId);
+    insertPanelRows(db, rows.map((row, index) => ({
+        panelId,
+        rowIndex: index,
+        rowId: row.rowId,
+        fields: row.fields,
+        media: row.media,
+        nodeId: row.nodeId,
+        cachedAssetIds: row.cachedAssetIds,
+    })));
+}
+function remapPanelSelectionState(db, panelId, oldRows, newRows, now) {
+    const oldIndexToRowId = new Map();
+    for (const row of oldRows) {
+        if (row.rowId)
+            oldIndexToRowId.set(row.rowIndex, row.rowId);
+    }
+    const rowIdToNewIndex = new Map();
+    for (const row of newRows) {
+        if (row.rowId)
+            rowIdToNewIndex.set(row.rowId, row.rowIndex);
+    }
+    const remapSelection = (selection) => {
+        if (!Array.isArray(selection))
+            return [];
+        const out = new Set();
+        for (const value of selection) {
+            if (!Number.isInteger(value) || value < 0)
+                continue;
+            const rowId = oldIndexToRowId.get(value);
+            const nextIndex = rowId ? rowIdToNewIndex.get(rowId) : undefined;
+            if (nextIndex !== undefined)
+                out.add(nextIndex);
+        }
+        return Array.from(out).sort((a, b) => a - b);
+    };
+    const panelStateRows = db.prepare(`SELECT user_id as userId, state_json as stateJson FROM panel_state WHERE panel_id = ?`).all(panelId);
+    const updatePanelState = db.prepare(`UPDATE panel_state SET state_json = ?, updated_at = ? WHERE panel_id = ? AND user_id = ?`);
+    for (const row of panelStateRows) {
+        const state = parseJsonObject(row.stateJson);
+        const nextSelection = remapSelection(state.selection);
+        if (JSON.stringify(state.selection ?? []) === JSON.stringify(nextSelection))
+            continue;
+        updatePanelState.run(JSON.stringify({ ...state, selection: nextSelection }), now, panelId, row.userId);
+    }
+    const shared = db.prepare(`SELECT state_json as stateJson, version FROM panel_shared_state WHERE panel_id = ? LIMIT 1`).get(panelId);
+    if (!shared)
+        return;
+    const sharedState = parseJsonObject(shared.stateJson);
+    const nextSharedSelection = remapSelection(sharedState.selection);
+    if (JSON.stringify(sharedState.selection ?? []) === JSON.stringify(nextSharedSelection))
+        return;
+    db.prepare(`UPDATE panel_shared_state
+     SET state_json = ?, version = ?, updated_at = ?
+     WHERE panel_id = ?`).run(JSON.stringify({ ...sharedState, selection: nextSharedSelection }), shared.version + 1, now, panelId);
+}
+export function updatePanelRowCachedAssetId(db, panelId, rowIndex, slot, assetId) {
+    const row = db.prepare(`SELECT cached_asset_ids_json FROM panel_rows WHERE panel_id = ? AND row_index = ?`).get(panelId, rowIndex);
+    const current = parseJsonObject(row?.cached_asset_ids_json ?? '{}');
+    current[slot] = assetId;
+    db.prepare(`UPDATE panel_rows SET cached_asset_ids_json = ? WHERE panel_id = ? AND row_index = ?`).run(JSON.stringify(current), panelId, rowIndex);
+}
+export function updatePanelRowCachedAssetIdIfCurrent(db, params) {
+    const row = db.prepare(`SELECT pr.row_id as rowId,
+            pr.node_id as nodeId,
+            pr.media_json as mediaJson,
+            pr.cached_asset_ids_json as cachedAssetIdsJson,
+            p.version as panelVersion
+       FROM panel_rows pr
+       JOIN panels p ON p.id = pr.panel_id
+      WHERE pr.panel_id = ? AND pr.row_index = ?
+      LIMIT 1`).get(params.panelId, params.rowIndex);
+    if (!row)
+        return false;
+    if (row.panelVersion !== params.panelVersion)
+        return false;
+    if (row.rowId !== params.rowId)
+        return false;
+    if (row.nodeId !== params.nodeId)
+        return false;
+    const media = parseJsonObject(row.mediaJson);
+    const currentMediaSlot = media[params.slot];
+    if (!currentMediaSlot
+        || currentMediaSlot.kind !== params.mediaSlot.kind
+        || currentMediaSlot.value !== params.mediaSlot.value) {
+        return false;
+    }
+    const current = parseJsonObject(row.cachedAssetIdsJson);
+    if ((current[params.slot] ?? null) !== (params.expectedCachedAssetId ?? null))
+        return false;
+    current[params.slot] = params.assetId;
+    const result = db.prepare(`UPDATE panel_rows SET cached_asset_ids_json = ? WHERE panel_id = ? AND row_index = ?`).run(JSON.stringify(current), params.panelId, params.rowIndex);
+    return result.changes > 0;
+}
+export function normalizePanelSelectionForRowCount(rowCount, selection) {
+    if (!Array.isArray(selection))
+        return [];
+    const selected = new Set();
+    for (const value of selection) {
+        if (typeof value !== 'number' || !Number.isInteger(value) || value < 0)
+            continue;
+        if (Number.isInteger(rowCount) && rowCount != null && rowCount >= 0 && value >= rowCount)
+            continue;
+        selected.add(value);
+    }
+    return Array.from(selected).sort((a, b) => a - b);
+}
+export function normalizePanelStateSelectionForRowCount(rowCount, state) {
+    if (!Object.prototype.hasOwnProperty.call(state, 'selection'))
+        return state;
+    if (!Array.isArray(state.selection))
+        return { ...state, selection: [] };
+    const originalSelection = state.selection;
+    const selection = normalizePanelSelectionForRowCount(rowCount, state.selection);
+    if (selection.length === originalSelection.length
+        && selection.every((rowIndex, index) => rowIndex === originalSelection[index])) {
+        return state;
+    }
+    return { ...state, selection };
+}
+export function applySharedSelectionPatch(db, panelId, patch, updatedByUserId) {
+    const now = Date.now();
+    const current = getSharedPanelState(db, panelId);
+    const currentSelection = patch.baseSelection ?? (current?.state?.selection ?? []);
+    const currentSet = new Set(currentSelection);
+    const toggled = patch.selection ?? [];
+    for (const rowIndex of toggled) {
+        if (currentSet.has(rowIndex)) {
+            currentSet.delete(rowIndex);
+        }
+        else {
+            currentSet.add(rowIndex);
+        }
+    }
+    const newSelection = Array.from(currentSet).sort((a, b) => a - b);
+    const newState = { selection: newSelection };
+    const newVersion = (current?.version ?? 0) + 1;
+    db.prepare(`INSERT INTO panel_shared_state(panel_id, state_json, version, updated_at, updated_by_user_id)
+     VALUES(?, ?, ?, ?, ?)
+     ON CONFLICT(panel_id)
+     DO UPDATE SET
+       state_json = excluded.state_json,
+       version = excluded.version,
+       updated_at = excluded.updated_at,
+       updated_by_user_id = excluded.updated_by_user_id`).run(panelId, JSON.stringify(newState), newVersion, now, updatedByUserId ?? null);
+    return {
+        panelId,
+        state: newState,
+        version: newVersion,
+        updatedAt: new Date(now).toISOString(),
+        ...(updatedByUserId ? { updatedByUserId } : {}),
+    };
+}
+export function getSharedPanelState(db, panelId) {
+    const row = db.prepare(`SELECT panel_id as panelId, state_json as stateJson, version,
+            updated_at as updatedAt, updated_by_user_id as updatedByUserId
+     FROM panel_shared_state
+     WHERE panel_id = ?
+     LIMIT 1`).get(panelId);
+    if (!row)
+        return null;
+    return {
+        panelId: row.panelId,
+        state: parseJsonObject(row.stateJson),
+        version: row.version,
+        updatedAt: new Date(row.updatedAt).toISOString(),
+        ...(row.updatedByUserId ? { updatedByUserId: row.updatedByUserId } : {}),
+    };
+}
+export function upsertSharedPanelState(db, panelId, state, updatedByUserId) {
+    const now = Date.now();
+    db.prepare(`INSERT INTO panel_shared_state(panel_id, state_json, version, updated_at, updated_by_user_id)
+     VALUES(?, ?, ?, ?, ?)
+     ON CONFLICT(panel_id)
+     DO UPDATE SET
+       state_json = excluded.state_json,
+       version = excluded.version,
+       updated_at = excluded.updated_at,
+       updated_by_user_id = excluded.updated_by_user_id`).run(panelId, JSON.stringify(state), 1, now, updatedByUserId ?? null);
+}
+export function loadAttachmentRow(db, id) {
+    const row = db.prepare(`SELECT id, filename, original_filename as originalFilename, mime_type as mimeType,
+            size_bytes as sizeBytes, storage_path as storagePath, kind
+     FROM attachments
+     WHERE id = ?
+     LIMIT 1`).get(id);
+    return row ?? null;
+}