Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
import { fnv1a } from "./utils.js";
export const YOUTUBE_REGEX = /(?:youtube\.com\/watch\?[^\s#]*v=|youtu\.be\/|youtube(?:-nocookie)?\.com\/embed\/|youtube\.com\/shorts\/)([a-zA-Z0-9_-]{11})/;
export function extractYouTubeVideoId(url: string): string | null {
const match = url.match(YOUTUBE_REGEX);
return match ? match[1] : null;
}
/**
* True when the URL is one a link preview may ever point at.
*
* A preview's URL reaches the renderers as a `data-url` attribute of the stored note HTML, and the
* HTML sanitizers (both `sanitize-html` on save and DOMPurify on render) pass `data-*` values
* through untouched — they check attribute *names*, not the contents of custom ones. So a note
* carrying `data-url="javascript:…"`, whether it arrived by import, ETAPI, sync from a compromised
* instance, or hand-edited HTML, would otherwise be rendered as a live `<a href="javascript:…">`
* — in the app *and* on the public share page. The metadata endpoint only ever produces http(s)
* URLs, so anything else is illegitimate by construction.
*/
export function isHttpUrl(url: string | undefined | null): boolean {
if (!url) {
return false;
}
try {
const { protocol } = new URL(url);
return protocol === "http:" || protocol === "https:";
} catch {
return false;
}
}
/**
* The URL to put in a link preview's `href`, or `about:blank` when it is not one we may link to.
* Mirrors what the share view's `sanitizeUrl` does with a hostile scheme: render the element, make
* the link inert. See {@link isHttpUrl}.
*/
export function safeLinkPreviewHref(url: string | undefined | null): string {
return isHttpUrl(url) ? String(url) : "about:blank";
}
/**
* A preview image reference the renderers may load: an inline `data:` image, or an attachment of
* this very instance.
*
* The metadata pipeline never produces anything else. The server downloads the favicon and the card
* image itself and hands back base64 `data:` URIs, precisely so that the note carries the picture
* instead of hotlinking the origin site; the client then offloads both into attachments and stores
* their `api/attachments/…` URLs, leaving the inline form only for a preview whose upload failed
* and for notes written before that. So a *remote* URL in `data-favicon` / `data-image` is
* illegitimate by construction — the mirror image of the {@link isHttpUrl} rule for `data-url`,
* where http(s) is the only legitimate case.
*
* That matters because those attributes reach an `<img src>` that fires on page load with no click,
* and `data-*` survives both sanitizers untouched (see {@link isHttpUrl}), so a note arriving by
* import, ETAPI or sync could otherwise make every reader of the note — and every visitor to it as a
* shared page — announce themselves to a third party. Keeping the check here, at the render sinks,
* means no stored value can produce an outbound request whatever route it came in by.
*/
export function isLocalPreviewImageSrc(src: string | undefined | null): boolean {
if (!src) {
return false;
}
const trimmed = src.trim();
// An SVG data URI is included on purpose: the server itself emits one for a vector favicon, and
// scripts inside an SVG loaded through <img> do not run.
if (/^data:image\/[a-z0-9.+-]+[;,]/i.test(trimmed)) {
return true;
}
// Exactly the shape the attachment upload endpoint returns. Anchored, so a protocol-relative
// `//evil.test/api/attachments/…` or a traversal cannot masquerade as one.
return /^api\/attachments\/[a-zA-Z0-9_]+\/image\/[^\s"'<>]*$/.test(trimmed);
}
/**
* The value to put in a preview's `<img src>`, or `undefined` when it is not one we may load.
* Every caller already renders a placeholder for a preview with no image (a neutral dot for the
* favicon, a link glyph for the card), so a rejected value degrades to that rather than to a broken
* image. See {@link isLocalPreviewImageSrc}.
*/
export function safeLinkPreviewImageSrc(src: string | undefined | null): string | undefined {
return isLocalPreviewImageSrc(src) ? String(src).trim() : undefined;
}
/**
* The host a URL points at, or the URL itself when it cannot be read as one.
*
* Both the site name a preview falls back to showing and the title its favicon is stored under, so
* it lives here rather than on either side: the picture and the label have to name the same site.
*/
export function safeHostname(url: string): string {
try {
return new URL(url).hostname;
} catch {
return url;
}
}
/**
* The attachment title a link preview's cover image is stored under.
*
* This is the deduplication key (see `isDeduplicatedAttachmentRole`), so it has to name exactly one
* page: pasting a URL twice must reuse the first picture, and two different URLs must never land on
* the same one. It is also what a reader sees in the attachment list, where several rows of
* "image.jpeg" say nothing about which is which.
*
* So it is both — a readable part built from the host and the last path segment, and a short digest
* of the whole address. The readable part cannot be the key on its own: reducing a URL to
* filename-safe characters is lossy, and `.../a/b` and `.../a-b` would reduce to the same name and
* then to the same picture. The digest settles identity; the prefix is there to be read.
*
* The fragment is left out of both. It never reaches the server and never changes the picture, so
* two links into different sections of one page share the cover they both showed anyway.
*
* A YouTube video is named by its ID instead, so all address forms of one video share a thumbnail.
*/
export function linkPreviewImageName(url: string): string {
const videoId = extractYouTubeVideoId(url);
if (videoId) {
return `youtube-${videoId}`;
}
let canonical = url;
let readable = toFileNamePart(url);
try {
const parsed = new URL(url);
parsed.hash = "";
canonical = parsed.toString();
const lastSegment = toFileNamePart(decodeURIComponent(parsed.pathname).split("/").filter(Boolean).pop() ?? "");
// The hostname is kept as it is written. It is already a file name — letters, digits, dots
// and dashes, an international one having been punycoded by the parse — so reducing it too
// would only spell the same site one way here and another under its favicon, which is
// titled by the bare hostname.
readable = lastSegment ? `${parsed.hostname}-${lastSegment}` : parsed.hostname;
} catch {
// Not an address that can be taken apart — rare, since a preview only ever has an http(s)
// URL. The digest identifies it regardless; only the readable part suffers.
}
return `${capReadable(readable) || "image"}-${fnv1a(canonical).toString(16).padStart(8, "0")}`;
}
/** How much of the readable part to keep, so a long path does not crowd out the attachment list. */
const PREVIEW_NAME_MAX_READABLE = 60;
/**
* Reduces a part of the address that is not already a file name — a path segment, or the lot.
*
* The trim matches one dash rather than a run of them, which is all there can be: the collapse just
* before it leaves no two dashes adjacent. A run would also be an address's to choose — this is
* handed whatever a link was pasted as — and `-+$` costs a scan from every position it starts at.
*/
function toFileNamePart(value: string): string {
return value.replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-|-$/g, "");
}
/** Bounds the readable part, and never lets it end on the punctuation a cut leaves behind. */
function capReadable(value: string): string {
return value.slice(0, PREVIEW_NAME_MAX_READABLE).replace(/^[-.]+|[-.]+$/g, "");
}
export interface LinkEmbedMetadata {
url: string;
title?: string;
description?: string;
image?: string;
favicon?: string;
siteName?: string;
embedType: "youtube" | "opengraph";
/** The shape of a video, as its width and height in whole numbers, such as `9/16`. */
aspectRatio?: string;
/**
* True when the page could not be read at all — a network error, a bot challenge (many sites
* answer a server-side fetch with a Cloudflare interstitial), a non-HTML response, or a page
* carrying no title of its own. The remaining fields then hold nothing but a hostname-derived
* placeholder, so an auto-detected URL is left as a plain link rather than becoming a preview
* that shows less than the URL itself did. Never persisted into the note's HTML.
*/
unresolved?: boolean;
}
/**
* A runtime-neutral view of a block's child node, decoupled from any editor's
* model types so the logic below can be unit-tested with plain objects.
*/
export interface BlockChildLike {
/** True for a text node; false for any element (image, soft break, widget, …). */
isText: boolean;
/** Text contents when `isText`; ignored otherwise. */
data?: string;
}
/**
* True when `url` is the sole content of a block — its only non-whitespace text
* is the URL and it holds no other elements. Surrounding whitespace (such as the
* trailing space that triggers auto-linking) is ignored.
*/
export function isUrlAloneInBlock(children: Iterable<BlockChildLike>, url: string): boolean {
let text = "";
for (const child of children) {
// Any non-text node (inline image, soft break, mention, …) means the
// URL isn't alone.
if (!child.isText) {
return false;
}
text += child.data ?? "";
}
return text.trim() === url;
}
export type LinkPreviewKind = "embed" | "card" | "mention";
/** Where an auto-detected URL sits, and what the user did right after typing it. */
export interface LinkPreviewPlacement {
/** The URL is the block's only content (see {@link isUrlAloneInBlock}). */
urlAloneInBlock: boolean;
/**
* The block is a plain top-level paragraph — not a list item, table cell, quote or heading.
* A block-level preview inside those reads as a layout accident, so they stay inline.
*/
blockIsStandalone: boolean;
/**
* The caret has left the block, which is what pressing Enter does. While the caret is still
* there the user is plausibly mid-sentence, so the URL has not (yet) been *left* alone.
*/
caretLeftBlock: boolean;
}
/**
* Chooses how an auto-detected URL should be previewed.
*
* A URL only becomes a block-level preview when the user deliberately left it alone on its own
* line — sole content of a plain paragraph, then Enter. That gesture is the signal; anything else
* (text either side, a list/table/quote, or a caret still sitting in the block because the user is
* still typing) yields an unobtrusive inline mention.
*
* Given that gesture, the URL decides which block form: an embeddable one (e.g. YouTube) becomes a
* player, everything else a card.
*/
export function chooseLinkPreviewKind(embedType: string, placement: LinkPreviewPlacement): LinkPreviewKind {
if (!placement.urlAloneInBlock || !placement.blockIsStandalone || !placement.caretLeftBlock) {
return "mention";
}
return embedType !== "opengraph" ? "embed" : "card";
}