Skip to content

Build your personal knowledge base with Trilium Notes

65.9 KB
Raw Blame
import { type AttachmentRow, attachmentRoleTraits, type AttributeRow, type BranchRow, CANVAS_ATTACHMENT_MIME, CONTENT_EMBED_KIND_ATTRIBUTE, dayjs, getDrawingPictureTitle, isEmbeddedAttachmentRole, isImageAttachmentRole, type NoteRow, NOTE_TYPE_IMAGE_ATTACHMENTS, type NoteType, parseMindMapNoteLink } from "@triliumnext/commons";
import { t } from "i18next";
import { parse as parseHtml } from "node-html-parser";

import becca from "../becca/becca.js";
import BAttachment from "../becca/entities/battachment.js";
import BAttribute from "../becca/entities/battribute.js";
import BBranch from "../becca/entities/bbranch.js";
import BNote from "../becca/entities/bnote.js";
import { ValidationError } from "../errors.js";
import { getLog } from "../services/log.js";
import protectedSessionService from "../services/protected_session.js";
import blobService from "./blob.js";
import * as cls from "./context.js";
import entityChangesService from "./entity_changes.js";
import eventService from "./events.js";
import imageService from "./image.js";
import { downloadImages, storeLinkPreviewPictures } from "./image_download.js";
import noteTypesService from "./note_types.js";
import optionService from "./options.js";
import revisionService from "./revisions.js";
import { evaluateTemplateSafe } from "./safe_template.js";
import { sanitizeHtml } from "./sanitizer.js";
import { getSql } from "./sql/index.js";
import type TaskContext from "./task_context.js";
import { decodeBase64, decodeUtf8, encodeBase64 } from "./utils/binary.js";
import date_utils from "./utils/date.js";
import { isValidEntityId, newEntityId, replaceAll, toMap, unescapeHtml } from "./utils/index.js";
import ws from "./ws.js";

interface FoundLink {
    name: "imageLink" | "internalLink" | "includeNoteLink" | "relationMapLink";
    value: string;
}

interface Attachment {
    attachmentId?: string;
    title: string;
}

export interface NoteParams {
    /** Forces a specific noteId: 4 to 128 letters, digits or underscores. */
    noteId?: string;
    branchId?: string;
    parentNoteId: string;
    templateNoteId?: string;
    title: string;
    content: string | Uint8Array;
    /** text, code, file, image, search, book, relationMap, canvas, webView */
    type: NoteType;
    /** default value is derived from default mimes for type */
    mime?: string;
    /** default is false */
    isProtected?: boolean;
    /** default is false */
    isExpanded?: boolean;
    /** default is empty string */
    prefix?: string;
    /** default is the last existing notePosition in a parent + 10 */
    notePosition?: number;
    dateCreated?: string;
    utcDateCreated?: string;
    /**
     * Set internally when the client requested no `type` and it was derived from the parent note instead.
     * In that case a `child:template` of a different type is still applied (and converts the note), whereas
     * an explicitly chosen type wins over such a template (#3015).
     */
    isTypeDefaulted?: boolean;
    ignoreForbiddenParents?: boolean;
    target?: "into";
    /** Attributes to be set on the note. These are set atomically on note creation, so entity changes are not sent for attributes defined here. */
    attributes?: Omit<AttributeRow, "noteId" | "attributeId">[];
}

function getNewNotePosition(parentNote: BNote) {
    // An import that preserves its source order suspends newNotesOnTop for the content it creates, so an
    // inherited `#newNotesOnTop` on the import target doesn't reverse the imported tree (see
    // {@link cls.setImportOrderPreserved}).
    if (!cls.isImportOrderPreserved() && parentNote.isLabelTruthy("newNotesOnTop")) {
        const minNotePos = parentNote
            .getChildBranches()
            .filter((branch) => branch?.noteId !== "_hidden") // has "always last" note position
            .reduce((min, note) => Math.min(min, note?.notePosition || 0), 0);

        return minNotePos - 10;
    }
    const maxNotePos = parentNote
        .getChildBranches()
        .filter((branch) => branch?.noteId !== "_hidden") // has "always last" note position
        .reduce((max, note) => Math.max(max, note?.notePosition || 0), 0);

    return maxNotePos + 10;
}

function triggerNoteTitleChanged(note: BNote) {
    eventService.emit(eventService.NOTE_TITLE_CHANGED, note);
}

function deriveMime(type: string, mime?: string) {
    if (!type) {
        throw new Error(`Note type is a required param`);
    }

    if (mime) {
        return mime;
    }

    return noteTypesService.getDefaultMimeForNoteType(type);
}

function copyChildAttributes(parentNote: BNote, childNote: BNote, isTypeDefaulted = false) {
    // A template *owned* at this point was chosen by the user explicitly in the menu, and suppresses
    // the `child:template` defaults (#3628). Deliberately read once, before the loop, and owned-only
    // so an inherited `~template` on the parent doesn't count as a choice.
    const hasUserChosenTemplate = childNote.hasOwnedRelation("template");

    for (const attr of parentNote.getAttributes()) {
        if (attr.name.startsWith("child:")) {
            const name = attr.name.substring(6);

            if (attr.type === "relation" && name === "template") {
                if (hasUserChosenTemplate) {
                    continue;
                }

                const templateNote = becca.getNote(attr.value);
                if (!isTypeDefaulted && templateNote && templateNote.type !== childNote.type) {
                    // the explicitly chosen note type wins over the default template, which would otherwise
                    // convert the note and fill it with content of a different type (#3015)
                    continue;
                }
            }

            new BAttribute({
                noteId: childNote.noteId,
                type: attr.type,
                name,
                value: attr.value,
                position: attr.position,
                isInheritable: attr.isInheritable
            }).save();
        }
    }
}

function copyAttachments(origNote: BNote, newNote: BNote) {
    for (const attachment of origNote.getAttachments()) {
        if (isImageAttachmentRole(attachment.role)) {
            // Handled separately, see `checkImageAttachments`.
            continue;
        }

        const newAttachment = new BAttachment({
            ...attachment,
            attachmentId: undefined,
            ownerId: newNote.noteId
        });

        newAttachment.save();
    }
}

function getNewNoteTitle(parentNote: BNote) {
    return evaluateTitleTemplate(
        parentNote.getLabelValue("titleTemplate"),
        parentNote,
        `titleTemplate of note '${parentNote.noteId}'`
    );
}

/**
 * Returns the default title that the first of the note's templates carrying a
 * `#template:titleTemplate` gives it, or `null` when none does.
 */
function getTemplateNoteTitle(note: BNote, parentNote: BNote) {
    for (const relation of note.getOwnedRelations("template")) {
        const templateNote = relation.targetNote;
        const titleTemplate = templateNote ? getTemplateTitleTemplate(templateNote) : null;

        if (templateNote && titleTemplate !== null) {
            return evaluateTitleTemplate(
                titleTemplate,
                parentNote,
                `template:titleTemplate of note '${templateNote.noteId}'`
            );
        }
    }

    return null;
}

/**
 * Reads the template's own `#template:titleTemplate`, or one inherited from its ancestors in the tree.
 * A value lent through `~template` is skipped, so a note created from a template and later marked
 * `#template` does not adopt the original template's title, as with `~template:newNoteDefaultParent`.
 */
function getTemplateTitleTemplate(templateNote: BNote) {
    const sourceNoteIds = new Set([ templateNote.noteId, ...templateNote.getAncestorNoteIds() ]);

    return templateNote.getLabels("template:titleTemplate")
        .find((label) => sourceNoteIds.has(label.noteId))?.value ?? null;
}

function evaluateTitleTemplate(titleTemplate: string | null, parentNote: BNote, source: string) {
    let title = t("notes.new-note");

    if (titleTemplate !== null) {
        const now = dayjs(date_utils.localNowDateTime() || new Date());

        // "officially" injected values:
        // - now
        // - parentNote
        title = evaluateTemplateSafe(
            titleTemplate,
            { now, parentNote },
            title,
            source
        );
    }

    // this isn't in theory a good place to sanitize title, but this will catch a lot of XSS attempts.
    // title is supposed to contain text only (not HTML) and be printed text only, but given the number of usages,
    // it's difficult to guarantee correct handling in all cases
    title = sanitizeHtml(title);

    return title;
}

interface GetValidateParams {
    parentNoteId: string;
    type: string;
    ignoreForbiddenParents?: boolean;
}

function getAndValidateParent(params: GetValidateParams) {
    const parentNote = becca.notes[params.parentNoteId];

    if (!parentNote) {
        throw new ValidationError(`Parent note '${params.parentNoteId}' was not found.`);
    }

    if (parentNote.type === "launcher" && parentNote.noteId !== "_lbBookmarks") {
        throw new ValidationError(`Creating child notes into launcher notes is not allowed.`);
    }

    if (["_lbAvailableLaunchers", "_lbVisibleLaunchers"].includes(params.parentNoteId) && params.type !== "launcher") {
        throw new ValidationError(`Only 'launcher' notes can be created in parent '${params.parentNoteId}'`);
    }

    if (!params.ignoreForbiddenParents) {
        if (["_lbRoot", "_hidden"].includes(parentNote.noteId)
                || parentNote.noteId.startsWith("_lbTpl")
                || parentNote.noteId.startsWith("_help")
                || parentNote.isOptions()) {
            throw new ValidationError(`Creating child notes into '${parentNote.noteId}' is not allowed.`);
        }
    }

    return parentNote;
}

function createNewNote(params: NoteParams): {
    note: BNote;
    branch: BBranch;
} {
    const parentNote = getAndValidateParent(params);

    const isTitleDefaulted = params.title === null || params.title === undefined;
    if (isTitleDefaulted) {
        params.title = getNewNoteTitle(parentNote);
    }

    if (params.content === null || params.content === undefined) {
        throw new Error(`Note content must be set`);
    }

    let error;
    if ((error = date_utils.validateLocalDateTime(params.dateCreated))) {
        throw new Error(error);
    }

    if ((error = date_utils.validateUtcDateTime(params.utcDateCreated))) {
        throw new Error(error);
    }

    const forcedNoteId: unknown = params.noteId;
    if (
        forcedNoteId !== undefined && forcedNoteId !== null && forcedNoteId !== ""
        && (typeof forcedNoteId !== "string" || !isValidEntityId(forcedNoteId))
    ) {
        throw new ValidationError(`Note ID '${forcedNoteId}' is not valid. `
            + "Only letters, digits and underscores are allowed, with a length of 4 to 128.");
    }

    if (typeof forcedNoteId === "string" && forcedNoteId && becca.notes[forcedNoteId]) {
        throw new ValidationError(`Note '${forcedNoteId}' already exists.`);
    }

    // When creating from a template, inherit the template's type and mime if not explicitly provided.
    // This ensures binary types (PDF, images, etc.) get the correct mime from the start.
    if (params.templateNoteId) {
        const templateNote = becca.getNote(params.templateNoteId);
        if (templateNote) {
            if (!params.mime) {
                params.mime = templateNote.mime;
            }
        }
    }

    return getSql().transactional(() => {
        let note, branch, isEntityEventsDisabled;

        try {
            isEntityEventsDisabled = cls.isEntityEventsDisabled();

            if (!isEntityEventsDisabled) {
                // it doesn't make sense to run note creation events on a partially constructed note, so
                // defer them until note creation is completed
                cls.disableEntityEvents();
            }

            note = new BNote({
                noteId: params.noteId, // optionally can force specific noteId
                title: params.title,
                isProtected: !!params.isProtected,
                type: params.type,
                mime: deriveMime(params.type, params.mime),
                dateCreated: params.dateCreated,
                utcDateCreated: params.utcDateCreated
            }).save();

            // Create attributes atomically.
            for (const attribute of params.attributes || []) {
                new BAttribute({
                    ...attribute,
                    noteId: note.noteId
                }).save();
            }

            note.setContent(params.content);

            branch = new BBranch({
                noteId: note.noteId,
                parentNoteId: params.parentNoteId,
                notePosition: params.notePosition !== undefined ? params.notePosition : getNewNotePosition(parentNote),
                prefix: params.prefix || "",
                isExpanded: !!params.isExpanded
            }).save();
        } finally {
            if (!isEntityEventsDisabled) {
                // re-enable entity events only if they were previously enabled
                // (they can be disabled in case of import)
                cls.enableEntityEvents();
            }
        }

        if (params.templateNoteId) {
            const templateNote = becca.getNote(params.templateNoteId);
            if (!templateNote) {
                throw new Error(`Template note '${params.templateNoteId}' does not exist.`);
            }

            // for binary content types (PDF, images, etc.), copy the template's content directly
            // since the event handler in handlers.ts only handles string content
            if (!templateNote.hasStringContent()) {
                const templateContent = templateNote.getContent();
                if (templateContent) {
                    note.setContent(templateContent);
                }
            }

            note.addRelation("template", params.templateNoteId);
            copyAttachments(templateNote, note);

            // no special handling for ~inherit since it doesn't matter if it's assigned with the note creation or later
        }

        copyChildAttributes(parentNote, note, params.isTypeDefaulted);

        // Read once the templates are applied, so both a chosen template and a `child:template` count.
        const templateTitle = isTitleDefaulted ? getTemplateNoteTitle(note, parentNote) : null;
        if (templateTitle !== null) {
            note.title = templateTitle;
            note.save();
        }

        eventService.emit(eventService.ENTITY_CREATED, { entityName: "notes", entity: note });
        eventService.emit(eventService.ENTITY_CHANGED, { entityName: "notes", entity: note });
        triggerNoteTitleChanged(note);
        // blobs entity doesn't use "created" event
        eventService.emit(eventService.ENTITY_CHANGED, { entityName: "blobs", entity: note });
        eventService.emit(eventService.ENTITY_CREATED, { entityName: "branches", entity: branch });
        eventService.emit(eventService.ENTITY_CHANGED, { entityName: "branches", entity: branch });
        eventService.emit(eventService.CHILD_NOTE_CREATED, { childNote: note, parentNote });

        if (!isEntityEventsDisabled) {
            // Skip per-note logging during bulk operations (e.g. import), where it would otherwise
            // emit one line per created note and flood the log on large imports.
            getLog().info(`Created new note '${note.noteId}', branch '${branch.branchId}' of type '${note.type}', mime '${note.mime}'`);
        }

        return {
            note,
            branch
        };
    });
}

function createNewNoteWithTarget(target: "into" | "after" | "before", targetBranchId: string | undefined, rawParams: Omit<NoteParams, "type"> & { type?: NoteType }) {
    if (!rawParams.type) {
        const parentNote = becca.notes[rawParams.parentNoteId];

        // code note type can be inherited, otherwise "text" is the default
        rawParams.type = parentNote.type === "code" ? "code" : "text";
        rawParams.mime = parentNote.type === "code" ? parentNote.mime : "text/html";
        // the type is not an explicit user choice, so a child:template of another type may still convert the note
        rawParams.isTypeDefaulted = true;
    }

    const params = rawParams as NoteParams;

    if (target === "into") {
        return createNewNote(params);
    } else if (target === "after" && targetBranchId) {
        const afterBranch = becca.branches[targetBranchId];

        // not updating utcDateModified to avoid having to sync whole rows
        getSql().execute("UPDATE branches SET notePosition = notePosition + 10 WHERE parentNoteId = ? AND notePosition > ? AND isDeleted = 0", [params.parentNoteId, afterBranch.notePosition]);

        params.notePosition = afterBranch.notePosition + 10;

        const retObject = createNewNote(params);

        entityChangesService.putNoteReorderingEntityChange(params.parentNoteId);

        return retObject;
    } else if (target === "before" && targetBranchId) {
        const beforeBranch = becca.branches[targetBranchId];

        // not updating utcDateModified to avoid having to sync whole rows
        getSql().execute("UPDATE branches SET notePosition = notePosition - 10 WHERE parentNoteId = ? AND notePosition < ? AND isDeleted = 0", [params.parentNoteId, beforeBranch.notePosition]);

        params.notePosition = beforeBranch.notePosition - 10;

        const retObject = createNewNote(params);

        entityChangesService.putNoteReorderingEntityChange(params.parentNoteId);

        return retObject;
    }
    throw new Error(`Unknown target '${target}'`);
}

function protectNoteRecursively(note: BNote, protect: boolean, includingSubTree: boolean, taskContext: TaskContext<"protectNotes">) {
    if (note.isVirtual) {
        // Virtual notes (e.g. the in-app help) are read-only, application-owned and never
        // persisted — (un)protecting them is meaningless. Their children are virtual too,
        // so the whole subtree is skipped.
        return;
    }

    protectNote(note, protect);

    taskContext.increaseProgressCount();

    if (includingSubTree) {
        for (const child of note.getChildNotes()) {
            protectNoteRecursively(child, protect, includingSubTree, taskContext);
        }
    }
}

function protectNote(note: BNote, protect: boolean) {
    if (!protectedSessionService.isProtectedSessionAvailable()) {
        throw new Error(`Cannot (un)protect note '${note.noteId}' with protect flag '${protect}' without active protected session`);
    }

    const log = getLog();
    try {
        if (protect !== note.isProtected) {
            const content = note.getContent();
            const extractedText = readExtractedText(note.blobId, note.isProtected);

            note.isProtected = protect;
            note.setContent(content, { forceSave: true });

            writeExtractedText(note.blobId, extractedText, protect);
        }

        revisionService.protectRevisions(note);

        for (const attachment of note.getAttachments()) {
            if (protect !== attachment.isProtected) {
                try {
                    const content = attachment.getContent();
                    const extractedText = readExtractedText(attachment.blobId, attachment.isProtected);

                    attachment.isProtected = protect;
                    attachment.setContent(content, { forceSave: true });

                    writeExtractedText(attachment.blobId, extractedText, protect);
                } catch (e) {
                    log.error(`Could not un/protect attachment '${attachment.attachmentId}'`);

                    throw e;
                }
            }
        }
    } catch (e) {
        log.error(`Could not un/protect note '${note.noteId}'`);

        throw e;
    }
}

/**
 * The text OCR pulled out of a file, read off the blob holding it.
 *
 * (Un)protecting re-saves content that has not changed a byte, but a blob's identity takes its
 * protection into account, so the re-save lands on a different row — one with no extracted text on it.
 * The text describes the same file either way, so it is read here while the old state still says how
 * it is stored, and put back by {@link writeExtractedText} once the new state does.
 */
function readExtractedText(blobId: string | undefined, isProtected: boolean | undefined): string {
    if (!blobId) {
        return "";
    }

    const row = getSql().getRowOrNull<{ textRepresentation: string | null }>(
        /*sql*/`SELECT textRepresentation FROM blobs WHERE blobId = ?`,
        [blobId]
    );

    return blobService.decryptTextRepresentation(row?.textRepresentation, !!isProtected);
}

/** Puts {@link readExtractedText}'s text back, on the blob the re-save produced and in its terms. */
function writeExtractedText(blobId: string | undefined, extractedText: string, isProtected: boolean) {
    if (!blobId || !extractedText) {
        return;
    }

    getSql().execute(
        /*sql*/`UPDATE blobs SET textRepresentation = ? WHERE blobId = ?`,
        [blobService.encryptTextRepresentation(extractedText, isProtected), blobId]
    );

    entityChangesService.putBlobEntityChange(blobId);
}

export function checkImageAttachments(note: BNote, content: string) {
    // Canvas references images by the Excalidraw fileId stored as the attachment *title* in its
    // scene JSON, so orphans are detected by title; every other type references them by attachmentId
    // embedded in the content (an image URL or attachment link), and by title from the scenes of
    // the canvas drawings it embeds.
    const isCanvas = note.type === "canvas";
    const foundAttachmentIds = new Set<string>();
    /**
     * Of those, the ones the content refers to as a link preview's own pictures rather than as a
     * picture of its own. A copy of one of these is still a preview's, so it keeps its role; a copy
     * reached any other way was put there by hand and takes the role that says so.
     */
    const previewPictureIds = new Set<string>();

    if (!isCanvas) {
        let match;

        // Spreadsheet and mind map content is JSON storing images as bare
        // `api/attachments/{id}/image/...` URLs (no `src="..."` wrapper), so they scan with the same
        // loose pattern as Markdown.
        const patterns: { pattern: RegExp, previewPicture?: boolean }[] = (note.isMarkdown() || note.type === "spreadsheet" || note.type === "mindMap")
            ? [
                // ![...](api/attachments/{id}/image/...) or similar markdown image syntax
                { pattern: /api\/attachments\/([a-zA-Z0-9_]+)\/image/g },
                // [...](#root/{noteId}?viewMode=attachments&attachmentId={id})
                { pattern: /attachmentId=([a-zA-Z0-9_]+)/g }
            ]
            : [
                // <img src="api/attachments/{id}/image/...">
                { pattern: /src="[^"]*api\/attachments\/([a-zA-Z0-9_]+)\/image/g },
                // Link previews reference both of their pictures from data attributes rather than
                // from an <img>: the card image, and the favicon that an inline mention carries on
                // its own. <section class="link-embed" data-image="api/attachments/{id}/image/..."
                // data-favicon="api/attachments/{id}/image/...">
                { pattern: /data-(?:image|favicon)="[^"]*api\/attachments\/([a-zA-Z0-9_]+)\/image/g, previewPicture: true },
                // <a href="...attachmentId={id}">
                { pattern: /href="[^"]+attachmentId=([a-zA-Z0-9_]+)/g },
                // <figure class="include-note" data-attachment-id="{id}">
                { pattern: /data-attachment-id="([a-zA-Z0-9_]+)"/g }
            ];

        for (const { pattern, previewPicture } of patterns) {
            while ((match = pattern.exec(content))) {
                foundAttachmentIds.add(match[1]);

                if (previewPicture) {
                    previewPictureIds.add(match[1]);
                }
            }
        }
    }

    const attachments = note.getAttachments();
    const existingAttachmentIds = new Set(attachments.map((att) => att.attachmentId));
    // The attachments of other notes that the content refers to, which this note takes copies of.
    const unknownAttachments = isCanvas ? [] : becca.getAttachments(Array.from(foundAttachmentIds)
        .filter((foundAttId) => !existingAttachmentIds.has(foundAttId)));
    const foundFileIds = isCanvas
        ? collectCanvasImageFileIds(content)
        : collectDrawingImageTitles([ ...attachments, ...unknownAttachments ], foundAttachmentIds);

    for (const attachment of attachments) {
        // Only attachments that live in the note content are auto-scheduled for erasure when nothing
        // refers to them any more; the rest are managed explicitly by their owners and must not be
        // cleaned up here. Which is which is a property of the role — see `AttachmentRoleTraits`.
        if (!isEmbeddedAttachmentRole(attachment.role)) {
            continue;
        }

        // The spreadsheet preview thumbnail is never referenced from the content — it is the note's
        // rendered image, looked up by title by the image endpoint — so leave it alone (otherwise it
        // would be scheduled for erasure on every save).
        if (note.type === "spreadsheet" && attachment.title === NOTE_TYPE_IMAGE_ATTACHMENTS.spreadsheet) {
            continue;
        }

        // Likewise for the mind map SVG export preview, which the map JSON never references.
        if (note.type === "mindMap" && attachment.title === NOTE_TYPE_IMAGE_ATTACHMENTS.mindMap) {
            continue;
        }

        // Likewise for the canvas SVG export preview, which the scene JSON never references.
        if (isCanvas && attachment.title === NOTE_TYPE_IMAGE_ATTACHMENTS.canvas) {
            continue;
        }

        const attachmentInContent = foundFileIds.has(attachment.title)
            || (!!attachment.attachmentId && foundAttachmentIds.has(attachment.attachmentId));

        if (attachment.utcDateScheduledForErasureSince && attachmentInContent) {
            attachment.utcDateScheduledForErasureSince = null;
            attachment.save();
        } else if (!attachment.utcDateScheduledForErasureSince && !attachmentInContent) {
            attachment.utcDateScheduledForErasureSince = date_utils.utcNowDateTime();
            attachment.save();
        }
    }

    // Canvas references images by title, not by attachmentId, so the foreign-attachment copy step
    // (which keys off attachmentIds found in the content) does not apply.
    if (isCanvas) {
        return { forceFrontendReload: false, content };
    }

    for (const unknownAttachment of unknownAttachments) {
        // A role says who made the attachment and why, so the copy's role is decided by how this note
        // refers to it. Still a link preview's picture here — the whole preview having been pasted —
        // and it stays the preview's. Reached any other way it is a picture or a file someone placed,
        // and carrying the app's role over would leave the copy deduplicated against this note's own
        // previews, denied the OCR and compression a picture is offered, and filed out of sight. A
        // role we know nothing about is left alone: there is nothing better to say about it.
        const copiedRole = previewPictureIds.has(unknownAttachment.attachmentId ?? "")
            ? unknownAttachment.role
            : attachmentRoleTraits(unknownAttachment.role)?.copiedAs ?? unknownAttachment.role;

        // the attachment belongs to a different note (was copy-pasted). Attachments can be linked only from the note
        // which owns it, so either find an existing attachment having the same content or make a copy.
        // Matched on the role the copy would take, not the one it came with, or a picture this note
        // already holds would never be recognised and every save would copy the bytes again.
        let localAttachment = note.getAttachments().find((att) => att.role === copiedRole && att.blobId === unknownAttachment.blobId);

        if (localAttachment) {
            if (localAttachment.utcDateScheduledForErasureSince) {
                // the attachment is for sure linked now, so reset the scheduled deletion
                localAttachment.utcDateScheduledForErasureSince = null;
                localAttachment.save();
            }

            getLog().info(
                `Found equivalent attachment '${localAttachment.attachmentId}' of note '${note.noteId}' for the linked foreign attachment '${unknownAttachment.attachmentId}' of note '${unknownAttachment.ownerId}'`
            );
        } else {
            localAttachment = unknownAttachment.copy();
            localAttachment.ownerId = note.noteId;
            localAttachment.role = copiedRole;
            localAttachment.setContent(unknownAttachment.getContent(), { forceSave: true });

            ws.sendMessageToAllClients({ type: "toast", message: `Attachment '${localAttachment.title}' has been copied to note '${note.title}'.` });
            getLog().info(`Copied attachment '${unknownAttachment.attachmentId}' of note '${unknownAttachment.ownerId}' to new '${localAttachment.attachmentId}' of note '${note.noteId}'`);
        }

        copyDrawingImages(note, unknownAttachment, localAttachment);

        // Replace image links — every one of them. A string first argument to replace() rewrites
        // only the first match, which was survivable while each reference had an attachment of its
        // own, but a deduplicated role (a link preview's favicon, one per site rather than one per
        // link) is referenced as many times as the note links that site. Leaving the rest pointing
        // at the foreign attachment made them resolve to another note's picture until a later save
        // happened to fix one more, each one announcing itself with a toast.
        content = replaceAll(content, `api/attachments/${unknownAttachment.attachmentId}/image`, `api/attachments/${localAttachment.attachmentId}/image`);
        // replace reference links
        content = content.replace(
            new RegExp(`href="[^"]+attachmentId=${unknownAttachment.attachmentId}[^"]*"`, "g"),
            `href="#root/${localAttachment.ownerId}?viewMode=attachments&amp;attachmentId=${localAttachment.attachmentId}"`
        );
        // replace embeds
        content = replaceAll(
            content,
            `data-attachment-id="${unknownAttachment.attachmentId}"`,
            `data-attachment-id="${localAttachment.attachmentId}"`
        );
    }

    return {
        forceFrontendReload: unknownAttachments.length > 0,
        content
    };
}

/**
 * Collects the Excalidraw `fileId`s referenced by a canvas note's scene JSON. Canvas images are
 * stored as attachments titled with these fileIds, so the set identifies which image attachments are
 * still in use (the persisted scene contains only non-deleted elements). Returns an empty set for
 * malformed content rather than throwing, so a save is never blocked.
 */
export function collectCanvasImageFileIds(content: string): Set<string> {
    const fileIds = new Set<string>();

    try {
        const parsed = JSON.parse(content) as { elements?: { fileId?: string }[] };
        const elements = Array.isArray(parsed?.elements) ? parsed.elements : [];
        for (const element of elements) {
            if (element?.fileId) {
                fileIds.add(element.fileId);
            }
        }
    } catch {
        // Malformed content (e.g. note type just changed) — treat as referencing nothing.
    }

    return fileIds;
}

/**
 * The titles of the image attachments that the canvas drawings among `attachments` in the content
 * keep: the images they show, titled with their file IDs, and the picture of each drawing.
 */
function collectDrawingImageTitles(attachments: BAttachment[], foundAttachmentIds: Set<string>) {
    const titles = new Set<string>();
    for (const attachment of attachments) {
        const { attachmentId } = attachment;
        if (attachment.mime !== CANVAS_ATTACHMENT_MIME || !attachmentId
            || !foundAttachmentIds.has(attachmentId)) {
            continue;
        }

        titles.add(getDrawingPictureTitle(attachmentId));
        for (const fileId of collectCanvasImageFileIds(decodeUtf8(attachment.getContent()))) {
            titles.add(fileId);
        }
    }
    return titles;
}

/**
 * Copies to `note` the images that the canvas drawing of another note shows, which its owner keeps
 * titled with their file IDs, unless `note` has attachments of those titles already. The picture of
 * the drawing becomes the picture of `copiedDrawing`, its copy in `note`.
 */
function copyDrawingImages(note: BNote, drawing: BAttachment, copiedDrawing: BAttachment) {
    const owner = becca.getNote(drawing.ownerId);
    if (drawing.mime !== CANVAS_ATTACHMENT_MIME || !owner) {
        return;
    }

    const fileIds = collectCanvasImageFileIds(decodeUtf8(drawing.getContent()));
    const pictureTitle = getDrawingPictureTitle(drawing.attachmentId ?? "");
    for (const image of owner.getAttachments()) {
        const title = image.title === pictureTitle && copiedDrawing.attachmentId
            ? getDrawingPictureTitle(copiedDrawing.attachmentId)
            : fileIds.has(image.title) && image.title;
        if (!title || note.getAttachmentByTitle(title)) {
            continue;
        }

        const copy = image.copy();
        copy.ownerId = note.noteId;
        copy.title = title;
        copy.setContent(image.getContent(), { forceSave: true });
    }
}

/**
 * The content of `entity` for a copy outside its note, such as a download: a canvas drawing gets
 * the images that it refers to by file ID inline, from the image attachments of its owner.
 * The output depends only on the stored entities, so an unchanged drawing yields the same bytes.
 */
function getPortableContent(entity: BNote | BAttachment) {
    const content = entity.getContent();
    const owner = entity instanceof BAttachment && entity.mime === CANVAS_ATTACHMENT_MIME
        ? becca.getNote(entity.ownerId)
        : null;
    if (!owner) {
        return content;
    }

    const json = decodeUtf8(content);
    let scene: { files?: Record<string, unknown> } | null = null;
    try {
        scene = JSON.parse(json);
    } catch {
        // Malformed content goes out as it is stored.
    }
    if (!scene || typeof scene !== "object") {
        return content;
    }

    const files = { ...scene.files };
    const fileIds = collectCanvasImageFileIds(json);
    for (const image of owner.getAttachments()) {
        if (!fileIds.has(image.title) || files[image.title]) {
            continue;
        }

        files[image.title] = {
            id: image.title,
            mimeType: image.mime,
            dataURL: `data:${image.mime};base64,${encodeBase64(image.getContent())}`,
            created: dayjs(image.getUtcDateChanged()).valueOf()
        };
    }
    return JSON.stringify({ ...scene, files });
}

function findImageLinks(content: string, foundLinks: FoundLink[]) {
    const re = /src="[^"]*api\/images\/([a-zA-Z0-9_]+)\//g;
    let match;

    while ((match = re.exec(content))) {
        foundLinks.push({
            name: "imageLink",
            value: match[1]
        });
    }

    // removing absolute references to server to keep it working between instances,
    // we also omit / at the beginning to keep the paths relative
    return content.replace(/src="[^"]*\/api\/images\//g, 'src="api/images/');
}

/**
 * Extracts bookmark IDs from CKEditor bookmark anchors (`<a id="..."></a>` without href).
 * Bookmarks are stored as labels on the note so they can be looked up without parsing content.
 */
export function findBookmarks(content: string): string[] {
    const re = /<a\s+id="([^"]+)"[^>]*>(<\/a>)?/g;
    const bookmarks: string[] = [];
    let match;

    while ((match = re.exec(content))) {
        // Skip anchors that also have an href (those are regular links, not bookmarks)
        if (match[0].includes("href=")) {
            continue;
        }

        const id = match[1];
        if (!bookmarks.includes(id)) {
            bookmarks.push(id);
        }
    }

    return bookmarks;
}

function saveBookmarks(note: BNote, content: string) {
    const foundBookmarks = findBookmarks(content);
    const existingBookmarks = note.getOwnedLabels("internalBookmark");

    for (const bookmarkId of foundBookmarks) {
        const existing = existingBookmarks.find((l) => l.value === bookmarkId);

        if (!existing) {
            new BAttribute({
                noteId: note.noteId,
                type: "label",
                name: "internalBookmark",
                value: bookmarkId
            }).save();
        }
    }

    // Remove bookmarks that are no longer in the content
    const unusedBookmarks = existingBookmarks.filter((l) => !foundBookmarks.includes(l.value));
    for (const unused of unusedBookmarks) {
        unused.markAsDeleted();
    }
}

function findInternalLinks(content: string, foundLinks: FoundLink[]) {
    const re = /href="[^"]*#root[a-zA-Z0-9_\/]*\/([a-zA-Z0-9_]+)\/?(?:\?[^"]*)?"/g;
    let match;

    while ((match = re.exec(content))) {
        foundLinks.push({
            name: "internalLink",
            value: match[1]
        });
    }

    // removing absolute references to server to keep it working between instances
    return content.replace(/href="[^"]*#root/g, 'href="#root');
}

function findMarkdownImageLinks(content: string, foundLinks: FoundLink[]) {
    const re = /api\/images\/([a-zA-Z0-9_]+)\//g;
    let match;

    while ((match = re.exec(content))) {
        foundLinks.push({
            name: "imageLink",
            value: match[1]
        });
    }
}

function findMarkdownInternalLinks(content: string, foundLinks: FoundLink[]) {
    // [text](#root/.../noteId) or [text](#root/.../noteId?query)
    const hashRootRe = /#root[a-zA-Z0-9_/]*\/([a-zA-Z0-9_]+)/g;
    let match;

    while ((match = hashRootRe.exec(content))) {
        foundLinks.push({
            name: "internalLink",
            value: match[1]
        });
    }

    // [[noteId]] wiki-links
    const wikiLinkRe = /\[\[([a-zA-Z0-9_]+)\]\]/g;

    while ((match = wikiLinkRe.exec(content))) {
        foundLinks.push({
            name: "internalLink",
            value: match[1]
        });
    }
}

/**
 * Extract internal-link note IDs from an llmChat note's JSON content.
 *
 * Two sources are scanned:
 * 1. `[[noteId]]` wiki-links inside assistant text blocks
 * 2. `noteId` / `parentNoteId` fields in tool-call inputs
 */
export function findLlmChatLinks(content: string, foundLinks: FoundLink[]) {
    let parsed: { messages?: unknown[] };
    try {
        parsed = JSON.parse(content);
    } catch {
        return;
    }

    if (!Array.isArray(parsed.messages)) {
        return;
    }

    const wikiLinkRe = /\[\[([a-zA-Z0-9_]+)\]\]/g;

    for (const msg of parsed.messages) {
        if (typeof msg !== "object" || msg === null) continue;
        const { role, content: msgContent } = msg as Record<string, unknown>;

        if (role !== "assistant" || !Array.isArray(msgContent)) continue;

        for (const block of msgContent) {
            if (typeof block !== "object" || block === null) continue;
            const b = block as Record<string, unknown>;

            if (b.type === "text" && typeof b.content === "string") {
                let match;
                while ((match = wikiLinkRe.exec(b.content))) {
                    foundLinks.push({ name: "internalLink", value: match[1] });
                }
            } else if (b.type === "tool_call") {
                const toolCall = b.toolCall as Record<string, unknown> | undefined;
                if (!toolCall || typeof toolCall !== "object") continue;

                const input = toolCall.input as Record<string, unknown> | undefined;
                if (input && typeof input === "object") {
                    if (typeof input.noteId === "string" && input.noteId) {
                        foundLinks.push({ name: "internalLink", value: input.noteId });
                    }
                    if (typeof input.parentNoteId === "string" && input.parentNoteId) {
                        foundLinks.push({ name: "internalLink", value: input.parentNoteId });
                    }
                }
            }
        }
    }
}

function findIncludeNoteLinks(content: string, foundLinks: FoundLink[]) {
    // Includes saved before captions existed are `<section>` elements.
    const re = /<(?:figure|section) class="include-note[^>]+data-note-id="([a-zA-Z0-9_]+)"[^>]*>/g;
    let match;

    while ((match = re.exec(content))) {
        foundLinks.push({
            name: "includeNoteLink",
            value: match[1]
        });
    }

    // Embeds of other kinds, with the attributes in any order.
    const embedRe = new RegExp(`<section[^>]*\\s${CONTENT_EMBED_KIND_ATTRIBUTE}="[^>]*>`, "g");
    while ((match = embedRe.exec(content))) {
        const noteId = /\sdata-note-id="([a-zA-Z0-9_]+)"/.exec(match[0])?.[1];
        if (noteId) {
            foundLinks.push({ name: "includeNoteLink", value: noteId });
        }
    }

    return content;
}

function findRelationMapLinks(content: string, foundLinks: FoundLink[]) {
    try {
        const obj = JSON.parse(content);

        for (const note of obj.notes) {
            foundLinks.push({
                name: "relationMapLink",
                value: note.noteId
            });
        }
    } catch (e: any) {
        getLog().error(`Could not scan for relation map links: ${e.message}`);
    }
}

/**
 * Collects the notes a mind map's nodes link to.
 *
 * A node carries one link of its own, and what makes it a link to a note is
 * {@link parseMindMapNoteLink}'s to say; anything else is an address outside Trilium. The whole map
 * is walked rather than only its nodes, so that a link stays found wherever Mind Elixir comes to
 * keep one.
 */
export function findMindMapLinks(content: string, foundLinks: FoundLink[]) {
    try {
        collectMindMapLinks(JSON.parse(content), foundLinks);
    } catch (e: any) {
        getLog().error(`Could not scan for mind map links: ${e.message}`);
    }
}

function collectMindMapLinks(value: unknown, foundLinks: FoundLink[]) {
    if (Array.isArray(value)) {
        for (const item of value) {
            collectMindMapLinks(item, foundLinks);
        }
        return;
    }

    if (!value || typeof value !== "object") {
        return;
    }

    const record = value as Record<string, unknown>;
    const noteId = parseMindMapNoteLink(record.hyperLink)?.noteId;
    if (noteId) {
        foundLinks.push({
            name: "internalLink",
            value: noteId
        });
    }

    for (const key of Object.keys(record)) {
        collectMindMapLinks(record[key], foundLinks);
    }
}

/**
 * Derives a plain-text attachment title from the inner HTML of an inline
 * attachment's link label: strips tags, decodes HTML entities, collapses
 * whitespace and trims.
 */
export function prepareTitle(html: string): string {
    // `.text` strips tags and decodes HTML entities (via `he`); we then collapse
    // whitespace and trim, matching the former `html2plaintext` behavior.
    return parseHtml(html).text.replace(/\s+/g, " ").trim();
}

function saveAttachments(note: BNote, content: string) {
    const inlineAttachmentRe = /<a[^>]*?\shref=['"]data:([^;'">]+);base64,([^'">]+)['"][^>]*>(.*?)<\/a>/gim;
    let attachmentMatch;

    while ((attachmentMatch = inlineAttachmentRe.exec(content))) {
        const mime = attachmentMatch[1].toLowerCase();

        const base64data = attachmentMatch[2];
        const buffer = decodeBase64(base64data);

        const title = prepareTitle(attachmentMatch[3]);

        const attachment = note.saveAttachment({
            role: "file",
            mime,
            title,
            content: buffer
        });

        content = `${content.substring(0, attachmentMatch.index)}<a class="reference-link" href="#root/${note.noteId}?viewMode=attachments&attachmentId=${attachment.attachmentId}">${title}</a>${content.substring(attachmentMatch.index + attachmentMatch[0].length)}`;
    }

    // removing absolute references to server to keep it working between instances,
    // we also omit / at the beginning to keep the paths relative
    content = content.replace(/src="[^"]*\/api\/attachments\//g, 'src="api/attachments/');

    content = stripStaleSrcset(content);

    return content;
}

/**
 * When an image is pasted from the web its `src` is localized to a Trilium
 * attachment, but the copied HTML often still carries the original `srcset`
 * (and its companion `sizes`) pointing at external URLs. Browsers prefer
 * `srcset` over `src`, so once those external URLs disappear the image breaks
 * even though the local attachment is intact. Drop `srcset`/`sizes` from any
 * `<img>` already backed by a local attachment so the valid `src` is used.
 * Images whose `src` is still external keep their `srcset` — there it is the
 * legitimate (and only) source.
 */
function stripStaleSrcset(content: string): string {
    return content.replace(/<img\b[^>]*>/gi, (imgTag) => {
        // Match quotes as balanced pairs (and allow optional whitespace around `=`) so a value
        // containing the opposite quote character doesn't truncate the match and corrupt the tag.
        if (!/\ssrc\s*=\s*(?:"api\/attachments\/[^"]+"|'api\/attachments\/[^']+')/i.test(imgTag)) {
            return imgTag;
        }

        return imgTag.replace(/\s(?:srcset|sizes)\s*=\s*(?:"[^"]*"|'[^']*')/gi, "");
    });
}


export function saveLinks(note: BNote, content: string | Uint8Array) {
    if ((note.type !== "text" && note.type !== "relationMap" && note.type !== "llmChat" && note.type !== "spreadsheet" && note.type !== "canvas" && note.type !== "mindMap" && !note.isMarkdown()) || (note.isProtected && !protectedSessionService.isProtectedSessionAvailable())) {
        return {
            forceFrontendReload: false,
            content
        };
    }

    const foundLinks: FoundLink[] = [];
    let forceFrontendReload = false;

    if (note.type === "text" && typeof content === "string") {
        content = downloadImages(note.noteId, content);
        content = saveAttachments(note, content);

        content = findImageLinks(content, foundLinks);
        content = findInternalLinks(content, foundLinks);
        content = findIncludeNoteLinks(content, foundLinks);
        saveBookmarks(note, content);

        ({ forceFrontendReload, content } = checkImageAttachments(note, content));
    } else if (note.isMarkdown() && typeof content === "string") {
        findMarkdownImageLinks(content, foundLinks);
        findMarkdownInternalLinks(content, foundLinks);
        ({ forceFrontendReload, content } = checkImageAttachments(note, content));
    } else if (note.type === "spreadsheet" && typeof content === "string") {
        // Spreadsheet images are stored as attachments referenced from the workbook JSON; scan for
        // orphans (inserted-then-removed images) so they get scheduled for erasure. There are no
        // Trilium internal links to extract from spreadsheet content.
        ({ forceFrontendReload, content } = checkImageAttachments(note, content));
    } else if (note.type === "canvas" && typeof content === "string") {
        // Canvas images are stored as attachments titled with the Excalidraw fileId referenced from
        // the scene JSON; scan for orphans (inserted-then-removed images) so they get scheduled for
        // erasure. There are no Trilium internal links to extract from canvas content.
        ({ forceFrontendReload, content } = checkImageAttachments(note, content));
    } else if (note.type === "mindMap" && typeof content === "string") {
        findMindMapLinks(content, foundLinks);
        // Mind map node images are stored as attachments referenced by URL from the map JSON; scan
        // for orphans (inserted-then-removed images) so they get scheduled for erasure.
        ({ forceFrontendReload, content } = checkImageAttachments(note, content));
    } else if (note.type === "relationMap" && typeof content === "string") {
        findRelationMapLinks(content, foundLinks);
    } else if (note.type === "llmChat" && typeof content === "string") {
        findLlmChatLinks(content, foundLinks);
    } else {
        throw new Error(`Unrecognized type '${note.type}'`);
    }

    const existingLinks = note.getRelations().filter((rel) => ["internalLink", "imageLink", "relationMapLink", "includeNoteLink"].includes(rel.name));

    for (const foundLink of foundLinks) {
        const targetNote = becca.notes[foundLink.value];
        if (!targetNote) {
            continue;
        }

        const existingLink = existingLinks.find((existingLink) => existingLink.value === foundLink.value && existingLink.name === foundLink.name);

        if (!existingLink) {
            const newLink = new BAttribute({
                noteId: note.noteId,
                type: "relation",
                name: foundLink.name,
                value: foundLink.value
            }).save();

            existingLinks.push(newLink);
        }
        // else the link exists, so we don't need to do anything
    }

    // marking links as deleted if they are not present on the page anymore
    const unusedLinks = existingLinks.filter((existingLink) => !foundLinks.some((foundLink) => existingLink.value === foundLink.value && existingLink.name === foundLink.name));

    for (const unusedLink of unusedLinks) {
        unusedLink.markAsDeleted();
    }

    return { forceFrontendReload, content };
}

function saveRevisionIfNeeded(note: BNote) {
    // files and images are versioned separately
    if (note.type === "file" || note.type === "image" || note.isLabelTruthy("disableVersioning")) {
        return;
    }

    const now = new Date();
    const revisionSnapshotTimeInterval = parseInt(optionService.getOption("revisionSnapshotTimeInterval"));

    const revisionCutoff = date_utils.utcDateTimeStr(new Date(now.getTime() - revisionSnapshotTimeInterval * 1000));

    const existingRevisionId = getSql().getValue("SELECT revisionId FROM revisions WHERE noteId = ? AND utcDateCreated >= ?", [note.noteId, revisionCutoff]);

    const msSinceDateCreated = now.getTime() - date_utils.parseDateTime(note.utcDateCreated).getTime();

    if (!existingRevisionId && msSinceDateCreated >= revisionSnapshotTimeInterval * 1000) {
        note.saveRevision();
    }
}

function updateNoteData(noteId: string, content: string, attachments: AttachmentRow[] = []) {
    const note = becca.getNote(noteId);

    if (!note || !note.isContentAvailable()) {
        throw new Error(`Note '${noteId}' is not available for change!`);
    }

    // Revisions, attachments and link attributes are database rows, which a virtual note has none
    // of; its provider stores the content alone.
    if (note.isVirtual) {
        note.setContent(content);
        return;
    }

    saveRevisionIfNeeded(note);

    // Saved before the links, so that `checkImageAttachments()` reads the drawings of this save.
    if (attachments?.length > 0) {
        const existingAttachmentsByTitle = toMap(note.getAttachments(), "title");

        for (const { attachmentId, role, mime, title, position, content, encoding } of attachments) {
            // An attachment deleted since the client read it, or one of another note, is not saved.
            if (attachmentId && becca.getAttachment(attachmentId)?.ownerId !== noteId) {
                getLog().info(
                    `Skipped attachment '${attachmentId}', which note '${noteId}' does not own.`
                );
                continue;
            }

            const decodedContent = encoding === "base64" && typeof content === "string"
                ? decodeBase64(content) : content;

            const existingAttachment = existingAttachmentsByTitle.get(title);
            if (attachmentId || !existingAttachment) {
                note.saveAttachment({ attachmentId, role, mime, title, content: decodedContent, position });
            } else {
                existingAttachment.role = role;
                existingAttachment.mime = mime;
                existingAttachment.position = position;
                if (decodedContent) {
                    existingAttachment.setContent(decodedContent, { forceSave: true });
                }
            }
        }
    }

    const { forceFrontendReload, content: newContent } = saveLinks(note, content);

    note.setContent(newContent, { forceFrontendReload });
}

export interface UndeleteNoteOptions {
    /**
     * When the note's original parent no longer survives (it is itself deleted, or has been erased),
     * reattach the note under this note instead — typically the inbox / default new-note location.
     * Without it, such a note cannot be restored at all.
     */
    fallbackParentNoteId?: string;
}

export interface UndeleteNoteResult {
    /** Whether the note (and its deleted subtree) was actually restored. */
    undeleted: boolean;
    /** True when the original location was gone and the note was reattached under the fallback parent. */
    restoredToFallbackParent: boolean;
}

/**
 * Attempts to restore a soft-deleted note (and the deleted subtree below it, sharing its deleteId).
 *
 * Normally the note is reattached to whichever of its original parents is still alive. If none is —
 * because the parent was itself deleted or already erased — the note is an orphan: it can only be
 * restored by giving it a new home, via {@link UndeleteNoteOptions.fallbackParentNoteId}.
 */
function undeleteNote(
    noteId: string,
    taskContext: TaskContext<"undeleteNotes">,
    opts: UndeleteNoteOptions = {}
): UndeleteNoteResult {
    const failed: UndeleteNoteResult = { undeleted: false, restoredToFallbackParent: false };

    // Use getRowOrNull: the note may have been erased (e.g. by the erasure scheduler or another client)
    // between the caller observing it and this call, in which case its row no longer exists.
    const noteRow = getSql().getRowOrNull<NoteRow>("SELECT * FROM notes WHERE noteId = ?", [noteId]);

    if (!noteRow) {
        getLog().info(`Note '${noteId}' no longer exists (has been erased) and thus cannot be undeleted.`);
        return failed;
    }

    if (!noteRow.isDeleted || !noteRow.deleteId) {
        getLog().error(`Note '${noteId}' is not deleted and thus cannot be undeleted.`);
        return failed;
    }

    const deleteId = noteRow.deleteId;
    const undeletedParentBranchIds = getUndeletedParentBranchIds(noteId, deleteId);

    if (undeletedParentBranchIds.length > 0) {
        for (const parentBranchId of undeletedParentBranchIds) {
            undeleteBranch(parentBranchId, deleteId, taskContext);
        }

        return { undeleted: true, restoredToFallbackParent: false };
    }

    // The note is an orphan: none of its original parents survive.
    if (!opts.fallbackParentNoteId) {
        return failed;
    }

    const fallbackParent = becca.getNote(opts.fallbackParentNoteId);

    if (!fallbackParent) {
        getLog().error(`Fallback parent '${opts.fallbackParentNoteId}' for undeleting note '${noteId}' was not found.`);
        return failed;
    }

    // A fresh branch gives the orphan a new home. Constructing it also materialises the note's becca
    // skeleton (see BBranch.childNote), which restoreNoteAndDescendants then fills in from the row.
    new BBranch({
        noteId,
        parentNoteId: fallbackParent.noteId,
        prefix: null
    } as BranchRow).save();

    taskContext.increaseProgressCount();

    restoreNoteAndDescendants(noteRow, deleteId, taskContext);

    return { undeleted: true, restoredToFallbackParent: true };
}

function undeleteBranch(branchId: string, deleteId: string, taskContext: TaskContext<"undeleteNotes">) {
    const sql = getSql();
    const branchRow = sql.getRow<BranchRow>("SELECT * FROM branches WHERE branchId = ?", [branchId]);

    if (!branchRow.isDeleted) {
        return;
    }

    const noteRow = sql.getRow<NoteRow>("SELECT * FROM notes WHERE noteId = ?", [branchRow.noteId]);

    if (noteRow.isDeleted && noteRow.deleteId !== deleteId) {
        return;
    }

    new BBranch(branchRow).save();

    taskContext.increaseProgressCount();

    if (noteRow.isDeleted && noteRow.deleteId === deleteId) {
        restoreNoteAndDescendants(noteRow, deleteId, taskContext);
    }
}

/**
 * Restores a deleted note's row, attributes and attachments, then recurses into the branches of the
 * subtree deleted alongside it. The note's becca skeleton must already exist — it is created as a
 * side effect of saving a branch that points at it (see BBranch.childNote).
 */
function restoreNoteAndDescendants(noteRow: NoteRow, deleteId: string, taskContext: TaskContext<"undeleteNotes">) {
    const sql = getSql();
    const noteEntity = becca.getNote(noteRow.noteId);

    if (!noteEntity) {
        throw new Error("Unable to find the just restored note.");
    }

    noteEntity.updateFromRow(noteRow);
    noteEntity.save();

    const attributeRows = sql.getRows<AttributeRow>(
        `
            SELECT * FROM attributes
            WHERE isDeleted = 1
            AND deleteId = ?
            AND (noteId = ?
                        OR (type = 'relation' AND value = ?))`,
        [deleteId, noteRow.noteId, noteRow.noteId]
    );

    for (const attributeRow of attributeRows) {
        // relation might point to a note which hasn't been undeleted yet and would thus throw up
        new BAttribute(attributeRow).save({ skipValidation: true });
    }

    const attachmentRows = sql.getRows<AttachmentRow>(
        `
        SELECT * FROM attachments
        WHERE isDeleted = 1
        AND deleteId = ?
        AND ownerId = ?`,
        [deleteId, noteRow.noteId]
    );

    for (const attachmentRow of attachmentRows) {
        new BAttachment(attachmentRow).save();
    }

    const childBranchIds = sql.getColumn<string>(
        `
        SELECT branches.branchId
        FROM branches
        WHERE branches.isDeleted = 1
        AND branches.deleteId = ?
        AND branches.parentNoteId = ?`,
        [deleteId, noteRow.noteId]
    );

    for (const childBranchId of childBranchIds) {
        undeleteBranch(childBranchId, deleteId, taskContext);
    }
}

/**
 * @returns return deleted branchIds of an undeleted parent note
 */
function getUndeletedParentBranchIds(noteId: string, deleteId: string) {
    return getSql().getColumn<string>(
        `
                    SELECT branches.branchId
                    FROM branches
                    JOIN notes AS parentNote ON parentNote.noteId = branches.parentNoteId
                    WHERE branches.noteId = ?
                    AND branches.isDeleted = 1
                    AND branches.deleteId = ?
                    AND parentNote.isDeleted = 0`,
        [noteId, deleteId]
    );
}

/** The note types `saveLinks()` reads links out of, minus the ones whose content holds none. */
const SCANNED_ON_IMPORT: NoteType[] = ["text", "relationMap", "mindMap", "llmChat"];

function scanForLinks(note: BNote, content: string | Uint8Array) {
    // Scanned here as well as on save, so that a note arriving by import carries its links to the
    // notes it points at without having to be opened and edited first. A Markdown note is asked
    // separately: it is a `code` note, whose type alone says nothing about the links it holds.
    if (!note || !(SCANNED_ON_IMPORT.includes(note.type) || note.isMarkdown())) {
        return;
    }

    try {
        getSql().transactional(() => {
            const { forceFrontendReload, content: newContent } = saveLinks(note, content);

            if (content !== newContent) {
                note.setContent(newContent, { forceFrontendReload });
            }
        });
    } catch (e: any) {
        getLog().error(`Could not scan for links note '${note.noteId}': ${e.message} ${e.stack}`);
    }
}

/**
 * Things which have to be executed after updating content, but asynchronously (separate transaction)
 */
async function asyncPostProcessContent(note: BNote, content: string | Uint8Array) {
    if (cls.isMigrationRunning()) {
        // this is rarely needed for migrations, but can cause trouble by e.g. triggering downloads
        return;
    }

    if (note.hasStringContent() && typeof content !== "string") {
        content = content.toString();
    }

    scanForLinks(note, content);
    // Read from the note rather than from `content`: scanForLinks may just have rewritten it.
    await storeLinkPreviewPictures(note);
}


// all keys should be replaced by the corresponding values
function replaceByMap(str: string, mapObj: Record<string, string>) {
    if (!mapObj) {
        return str;
    }

    const re = new RegExp(Object.keys(mapObj).join("|"), "g");

    return str.replace(re, (matched) => mapObj[matched]);
}

/**
 * Copies a note and its descendants into `newParentNoteId`, right after the original, and appends
 * `notes.duplicate-note-suffix` to the copy's title.
 *
 * With `withChildren: false`, only the note itself is copied; links and relations to its children
 * keep pointing at the original children.
 */
function duplicateSubtree(origNoteId: string, newParentNoteId: string, { withChildren = true }: { withChildren?: boolean } = {}) {
    if (origNoteId === "root") {
        throw new Error("Duplicating root is not possible");
    }

    getLog().info(`Duplicating '${origNoteId}' subtree into '${newParentNoteId}'`);

    const origNote = becca.notes[origNoteId];
    // might be null if orig note is not in the target newParentNoteId
    const origBranch = origNote.getParentBranches().find((branch) => branch.parentNoteId === newParentNoteId);

    const noteIdMapping = withChildren
        ? getNoteIdMapping(origNote)
        : { [origNote.noteId]: newEntityId() };

    const res = duplicateSubtreeInner(origNote, origBranch, newParentNoteId, noteIdMapping, withChildren);

    const duplicateNoteSuffix = t("notes.duplicate-note-suffix");

    if (!res.note.title.endsWith(duplicateNoteSuffix) && !res.note.title.startsWith(duplicateNoteSuffix)) {
        res.note.title = t("notes.duplicate-note-title", { noteTitle: res.note.title, duplicateNoteSuffix });
    }

    res.note.save();

    return res;
}

function duplicateSubtreeWithoutRoot(origNoteId: string, newNoteId: string) {
    if (origNoteId === "root") {
        throw new Error("Duplicating root is not possible");
    }

    const origNote = becca.getNote(origNoteId);
    if (origNote == null) {
        throw new Error("Unable to find note to duplicate.");
    }

    const noteIdMapping = getNoteIdMapping(origNote);
    for (const childBranch of origNote.getChildBranches()) {
        if (childBranch) {
            duplicateSubtreeInner(childBranch.getNote(), childBranch, newNoteId, noteIdMapping);
        }
    }
}

function duplicateSubtreeInner(origNote: BNote, origBranch: BBranch | null | undefined, newParentNoteId: string, noteIdMapping: Record<string, string>, withChildren = true) {
    if (origNote.isProtected && !protectedSessionService.isProtectedSessionAvailable()) {
        throw new Error(`Cannot duplicate note '${origNote.noteId}' because it is protected and protected session is not available. Enter protected session and try again.`);
    }

    const newNoteId = noteIdMapping[origNote.noteId];

    function createDuplicatedBranch() {
        return new BBranch({
            noteId: newNoteId,
            parentNoteId: newParentNoteId,
            // here increasing just by 1 to make sure it's directly after original
            notePosition: origBranch ? origBranch.notePosition + 1 : null
        }).save();
    }

    function createDuplicatedNote() {
        const newNote = new BNote({
            ...origNote,
            noteId: newNoteId,
            dateCreated: date_utils.localNowDateTime(),
            utcDateCreated: date_utils.utcNowDateTime()
        }).save();

        let content = origNote.getContent();

        if (typeof content === "string" && ["text", "relationMap", "search"].includes(origNote.type)) {
            // fix links in the content
            content = replaceByMap(content, noteIdMapping);
        }

        newNote.setContent(content);

        for (const attribute of origNote.getOwnedAttributes()) {
            const attr = new BAttribute({
                ...attribute,
                attributeId: undefined,
                noteId: newNote.noteId
            });

            // if relation points to within the duplicated tree then replace the target to the duplicated note
            // if it points outside of duplicated tree then keep the original target
            if (attr.type === "relation" && attr.value in noteIdMapping) {
                attr.value = noteIdMapping[attr.value];
            }

            // the relation targets may not be created yet, the mapping is pre-generated
            attr.save({ skipValidation: true });
        }

        if (withChildren) {
            for (const childBranch of origNote.getChildBranches()) {
                if (childBranch) {
                    duplicateSubtreeInner(childBranch.getNote(), childBranch, newNote.noteId, noteIdMapping);
                }
            }
        }

        asyncPostProcessContent(newNote, content);

        return newNote;
    }

    const existingNote = becca.notes[newNoteId];

    if (existingNote && existingNote.title !== undefined) {
        // checking that it's not just note's skeleton created because of Branch above
        // note has multiple clones and was already created from another placement in the tree,
        // so a branch is all we need for this clone
        return {
            note: existingNote,
            branch: createDuplicatedBranch()
        };
    }
    return {
        // order here is important, note needs to be created first to not mess up the becca
        note: createDuplicatedNote(),
        branch: createDuplicatedBranch()
    };

}

function getNoteIdMapping(origNote: BNote) {
    const noteIdMapping: Record<string, string> = {};

    // pregenerate new noteIds since we'll need to fix relation references even for not yet created notes
    for (const origNoteId of origNote.getDescendantNoteIds()) {
        noteIdMapping[origNoteId] = newEntityId();
    }

    return noteIdMapping;
}

export default {
    createNewNote,
    createNewNoteWithTarget,
    updateNoteData,
    getPortableContent,
    undeleteNote,
    protectNoteRecursively,
    duplicateSubtree,
    duplicateSubtreeWithoutRoot,
    getUndeletedParentBranchIds,
    triggerNoteTitleChanged,
    saveRevisionIfNeeded,
    downloadImages,
    asyncPostProcessContent
};