@dinoxx/dinox-cli 1.0.22 → 1.1.0

package/dist/utils/errors.js

@@ -3,14 +3,20 @@ export class DinoxError extends Error {
     details;
     code;
     suggestion;
+    suggestedAction;
     recoverable;
     constructor(message, options) {
         super(message);
+        const code = normalizeErrorCode(options?.code ?? inferDinoxErrorCode(message));
+        const suggestion = options?.suggestion ?? defaultSuggestionForCode(code);
         this.name = 'DinoxError';
-        this.exitCode = options?.exitCode ?? 1;
+        this.exitCode = options?.exitCode ?? exitCodeForErrorCode(code);
         this.details = options?.details;
-        this.code = options?.code;
-        this.suggestion = options?.suggestion;
+        this.code = code;
+        this.suggestion = suggestion;
+        this.suggestedAction = options?.suggestedAction
+            ?? suggestedActionFromSuggestion(suggestion)
+            ?? defaultSuggestedActionForCode(code, message);
         this.recoverable = options?.recoverable ?? true;
         if (options?.cause !== undefined) {
             // Node 16+ supports Error.cause.
@@ -19,20 +25,47 @@ export class DinoxError extends Error {
     }
 }
 export function isDinoxError(error) {
-    return Boolean(error) && typeof error === 'object' && error.name === 'DinoxError';
+    return Boolean(error)
+        && typeof error === 'object'
+        && error.name === 'DinoxError'
+        && typeof error.exitCode === 'number';
+}
+function serializeCause(error) {
+    if (!error || typeof error !== 'object' || !('cause' in error)) {
+        return undefined;
+    }
+    const cause = error.cause;
+    if (cause === undefined) {
+        return undefined;
+    }
+    if (cause instanceof Error) {
+        return {
+            name: cause.name,
+            message: cause.message,
+            ...(cause.stack ? { stack: cause.stack } : {}),
+        };
+    }
+    return {
+        name: 'Error',
+        message: String(cause),
+    };
 }
 export function buildStructuredErrorPayload(error, verbose) {
     const message = error instanceof Error ? error.message : String(error);
     const name = error instanceof Error ? error.name : 'Error';
     const stack = error instanceof Error ? error.stack : undefined;
     if (isDinoxError(error)) {
+        const cause = verbose ? serializeCause(error) : undefined;
         return {
             name,
-            code: error.code ?? 'DINOX_ERROR',
+            code: error.code,
             message,
             recoverable: error.recoverable,
+            exit_code: error.exitCode,
             ...(error.suggestion ? { suggestion: error.suggestion } : {}),
+            ...(error.suggestedAction ? { suggested_action: error.suggestedAction } : {}),
             ...(error.details !== undefined ? { details: error.details } : {}),
+            ...(cause ? { cause } : {}),
             ...(verbose && stack ? { stack } : {}),
         };
     }
@@ -41,6 +74,191 @@ export function buildStructuredErrorPayload(error, verbose) {
         code: 'INTERNAL_ERROR',
         message,
         recoverable: false,
+        exit_code: 1,
+        suggested_action: {
+            command: 'dino doctor --format json',
+            reason: 'Inspect local auth, sync, index, daemon, and database health before retrying.',
+        },
         ...(verbose && stack ? { stack } : {}),
     };
 }
+function normalizeErrorCode(value) {
+    const normalized = value.trim().toUpperCase().replace(/[^A-Z0-9_]+/g, '_').replace(/^_+|_+$/g, '');
+    return normalized || 'COMMAND_FAILED';
+}
+function inferDinoxErrorCode(message) {
+    const text = message.trim();
+    const lower = text.toLowerCase();
+    if (/cache is not fully synchronized|stale|\bsync required\b|\bsync timed out\b|\bsync could not\b/.test(lower)) {
+        return 'SYNC_STALE';
+    }
+    if (lower.includes('not logged in')
+        || lower.includes('auth login')
+        || lower.includes('missing resolved userid')
+        || lower.includes('requires a logged-in user')
+        || lower.includes('missing backend base url')) {
+        return 'AUTH_REQUIRED';
+    }
+    if (text.startsWith('--')
+        || /^(invalid|provide|at least one|conflicting|missing|token is required|file path is required|note id is required|taskid is required|prompt name is required|prompt text is required|tag name is required|box path is required)/i.test(text)
+        || /\b(must be|requires|cannot be used together|expected|one of|required)\b/i.test(text)) {
+        return 'USAGE_ERROR';
+    }
+    if (/\b(not found|unknown|does not exist|no active|no eligible|no custom|not available)\b/i.test(text)) {
+        return 'NOT_FOUND';
+    }
+    if (/\b(already exists|duplicate|refusing|ambiguous|not unique|deleted|expired|changed after|does not match|belongs to a different user|cannot move|cannot merge|protected)\b/i.test(text)) {
+        return 'PRECONDITION_FAILED';
+    }
+    if (lower.includes('daemon')) {
+        return 'DAEMON_ERROR';
+    }
+    return 'COMMAND_FAILED';
+}
+export function exitCodeForErrorCode(code) {
+    const normalized = normalizeErrorCode(code);
+    if (normalized === 'USAGE_ERROR' || normalized === 'INVALID_ARGUMENT' || normalized.startsWith('INVALID_')) {
+        return 2;
+    }
+    if (normalized === 'AUTH_REQUIRED' || normalized === 'AUTH_INVALID' || normalized === 'UNAUTHENTICATED' || normalized.startsWith('AUTH_')) {
+        return 3;
+    }
+    if (normalized === 'SYNC_REQUIRED' || normalized === 'SYNC_STALE' || normalized === 'UPLOAD_PENDING' || normalized.startsWith('SYNC_')) {
+        return 4;
+    }
+    if (normalized === 'PRECONDITION_FAILED'
+        || normalized === 'NOT_FOUND'
+        || normalized === 'ALREADY_EXISTS'
+        || normalized === 'DAEMON_STALE'
+        || normalized === 'DAEMON_ERROR'
+        || normalized === 'DAEMON_START_FAILED'
+        || normalized.endsWith('_NOT_FOUND')
+        || normalized.endsWith('_ALREADY_EXISTS')
+        || normalized.endsWith('_REQUIRED')) {
+        return 5;
+    }
+    return 1;
+}
+function defaultSuggestionForCode(code) {
+    switch (normalizeErrorCode(code)) {
+        case 'AUTH_REQUIRED':
+        case 'AUTH_INVALID':
+        case 'UNAUTHENTICATED':
+            return 'Run `dino auth status --format json`; if auth is missing, set DINOX_TOKEN or pipe a token to `dino auth login --token-stdin` in your own terminal.';
+        case 'SYNC_REQUIRED':
+        case 'SYNC_STALE':
+            return 'Run `dino sync --strict --sync-timeout 600000 --format json`, then retry the command.';
+        case 'UPLOAD_PENDING':
+            return 'Run `dino doctor --fix --format json` to wait for pending uploads and inspect sync health.';
+        case 'DAEMON_STALE':
+        case 'DAEMON_ERROR':
+        case 'DAEMON_START_FAILED':
+            return 'Run `dino doctor --fix --format json` to restart a stale daemon and inspect local health.';
+        case 'USAGE_ERROR':
+        case 'INVALID_ARGUMENT':
+            return 'Run `dino schema --format json` to inspect valid commands, arguments, and flags.';
+        default: {
+            const normalized = normalizeErrorCode(code);
+            if (normalized.startsWith('AUTH_')) {
+                return 'Run `dino auth status --format json`; if auth is missing, set DINOX_TOKEN or pipe a token to `dino auth login --token-stdin` in your own terminal.';
+            }
+            if (normalized.startsWith('SYNC_')) {
+                return 'Run `dino sync --strict --sync-timeout 600000 --format json`, then retry the command.';
+            }
+            if (normalized.startsWith('DAEMON_')) {
+                return 'Run `dino doctor --fix --format json` to restart a stale daemon and inspect local health.';
+            }
+            return undefined;
+        }
+    }
+}
+function suggestedActionFromSuggestion(suggestion) {
+    if (!suggestion) {
+        return undefined;
+    }
+    const match = suggestion.match(/`(dino\s+[^`]+)`/) ?? suggestion.match(/['"](dino\s+[^'"]+)['"]/);
+    const command = match?.[1]?.trim();
+    if (!command) {
+        return undefined;
+    }
+    return {
+        command,
+        reason: suggestion,
+    };
+}
+function defaultSuggestedActionForCode(code, message) {
+    const normalized = normalizeErrorCode(code);
+    if (normalized === 'AUTH_REQUIRED' || normalized === 'AUTH_INVALID' || normalized === 'UNAUTHENTICATED' || normalized.startsWith('AUTH_')) {
+        return {
+            command: 'dino auth status --format json',
+            reason: 'Confirm whether CLI authentication is configured before retrying.',
+        };
+    }
+    if (normalized === 'SYNC_REQUIRED' || normalized === 'SYNC_STALE' || normalized.startsWith('SYNC_')) {
+        return {
+            command: 'dino sync --strict --sync-timeout 600000 --format json',
+            reason: 'Refresh the local PowerSync cache and prove freshness before retrying the read.',
+        };
+    }
+    if (normalized === 'UPLOAD_PENDING') {
+        return {
+            command: 'dino doctor --fix --format json',
+            reason: 'Drain pending uploads without discarding queued mutations, then recheck sync health.',
+        };
+    }
+    if (normalized.startsWith('DAEMON_') || normalized === 'DAEMON_ERROR') {
+        return {
+            command: 'dino doctor --fix --format json',
+            reason: 'Repair local daemon state and verify version/account freshness.',
+        };
+    }
+    if (normalized === 'USAGE_ERROR' || normalized === 'INVALID_ARGUMENT') {
+        return {
+            command: 'dino schema --format json',
+            reason: 'Inspect valid command arguments and flags before retrying.',
+        };
+    }
+    if (normalized === 'NOT_FOUND' || normalized.endsWith('_NOT_FOUND')) {
+        return defaultNotFoundAction(message);
+    }
+    return {
+        command: 'dino doctor --format json',
+        reason: 'Inspect auth, sync, index, daemon, and database health before retrying.',
+    };
+}
+function defaultNotFoundAction(message) {
+    if (/\bnote\b/i.test(message)) {
+        return {
+            command: 'dino note search --format json',
+            reason: 'Search notes to find a valid note id before retrying.',
+        };
+    }
+    if (/\btag\b/i.test(message)) {
+        return {
+            command: 'dino tag list --format json',
+            reason: 'List existing tags before retrying.',
+        };
+    }
+    if (/\b(box|zettel)\b/i.test(message)) {
+        return {
+            command: 'dino box list --format json',
+            reason: 'List existing zettel boxes before retrying.',
+        };
+    }
+    if (/\bstorage\b/i.test(message)) {
+        return {
+            command: 'dino storage list --format json',
+            reason: 'List available storage configs before retrying.',
+        };
+    }
+    if (/\bprompt\b/i.test(message)) {
+        return {
+            command: 'dino prompt list --format json',
+            reason: 'List existing prompts before retrying.',
+        };
+    }
+    return {
+        command: 'dino schema --format json',
+        reason: 'Inspect available command paths and retry with an existing resource.',
+    };
+}

package/dist/utils/output.d.ts

@@ -4,6 +4,7 @@ export declare function toYaml(value: unknown): string;
 export declare function toJson(value: unknown): string;
 export declare function printHumanReadableLine(text: string): void;
 export declare function printHumanReadableBlock(text: string): void;
+export declare function printHumanReadableWarning(text: string): void;
 export declare function printHumanReadableError(text: string): void;
 export declare function resolveStructuredOutputFormat(input: {
     format?: unknown;

package/dist/utils/output.js

@@ -1,4 +1,5 @@
 import { stringify as stringifyYaml } from 'yaml';
+import { DinoxError } from './errors.js';
 import { sanitizeForTerminal } from './terminalSanitization.js';
 let requestedStructuredOutputFormat = null;
 let pendingStructuredNoticeProvider = null;
@@ -23,49 +24,72 @@ export function printHumanReadableLine(text) {
 export function printHumanReadableBlock(text) {
     writeToStdout(sanitizeForTerminal(text));
 }
+export function printHumanReadableWarning(text) {
+    writeToStderr(`${sanitizeForTerminal(text)}\n`);
+}
 export function printHumanReadableError(text) {
     writeToStderr(`${sanitizeForTerminal(text)}\n`);
 }
 function normalizeStructuredOutputFormat(value) {
     if (typeof value !== 'string') {
-        throw new Error('--format must be one of: yaml, json');
+        throw new DinoxError('--format must be one of: yaml, json');
     }
     const normalized = value.trim().toLowerCase();
     if (normalized === 'yaml' || normalized === 'json') {
         return normalized;
     }
-    throw new Error('--format must be one of: yaml, json');
+    throw new DinoxError('--format must be one of: yaml, json');
 }
 export function resolveStructuredOutputFormat(input) {
-    if (input.format !== undefined && input.format !== null && input.format !== '') {
+    const hasFormat = input.format !== undefined && input.format !== null && input.format !== '';
+    const hasLegacyJson = Boolean(input.json);
+    if (hasFormat && hasLegacyJson) {
+        throw new DinoxError('--json cannot be used together with --format');
+    }
+    if (hasFormat) {
         return normalizeStructuredOutputFormat(input.format);
     }
-    if (Boolean(input.json)) {
+    if (hasLegacyJson) {
         return 'yaml';
     }
     return null;
 }
 export function parseStructuredOutputFormatFromArgv(argv) {
-    let format = null;
+    let explicitFormat = null;
+    let hasLegacyJson = false;
     for (let index = 0; index < argv.length; index += 1) {
         const arg = argv[index];
         if (!arg) {
             continue;
         }
+        if (arg === '--') {
+            break;
+        }
         if (arg === '--json') {
-            format = 'yaml';
+            hasLegacyJson = true;
             continue;
         }
         if (arg === '--format') {
-            format = normalizeStructuredOutputFormat(argv[index + 1]);
+            const nextFormat = normalizeStructuredOutputFormat(argv[index + 1]);
+            if (explicitFormat && explicitFormat !== nextFormat) {
+                throw new DinoxError('--format cannot be specified with conflicting values');
+            }
+            explicitFormat = nextFormat;
             index += 1;
             continue;
         }
         if (arg.startsWith('--format=')) {
-            format = normalizeStructuredOutputFormat(arg.slice('--format='.length));
+            const nextFormat = normalizeStructuredOutputFormat(arg.slice('--format='.length));
+            if (explicitFormat && explicitFormat !== nextFormat) {
+                throw new DinoxError('--format cannot be specified with conflicting values');
+            }
+            explicitFormat = nextFormat;
         }
     }
-    return format;
+    if (hasLegacyJson && explicitFormat) {
+        throw new DinoxError('--json cannot be used together with --format');
+    }
+    return explicitFormat ?? (hasLegacyJson ? 'yaml' : null);
 }
 export function setRequestedStructuredOutputFormat(format) {
     requestedStructuredOutputFormat = format;
@@ -117,11 +141,6 @@ function deriveStructuredNotice(value) {
             message: 'Result may be stale because the local cache did not fully synchronize.',
         };
     }
-    if (record.uploadEnabled === false) {
-        notice.upload_disabled = {
-            message: 'Local changes cannot upload because powersync.uploadBaseUrl is unset.',
-        };
-    }
     return Object.keys(notice).length > 0 ? notice : null;
 }
 function mergeStructuredNotices(base, derived) {
@@ -131,6 +150,19 @@ function mergeStructuredNotices(base, derived) {
     };
     return Object.keys(merged).length > 0 ? merged : undefined;
 }
+function summarizeStructuredError(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return {};
+    }
+    const record = value;
+    const summary = {};
+    for (const key of ['code', 'message', 'recoverable', 'exit_code', 'suggested_action']) {
+        if (record[key] !== undefined) {
+            summary[key] = record[key];
+        }
+    }
+    return summary;
+}
 export function printSuccess(value, format = getRequestedStructuredOutputFormat()) {
     if (format === 'json') {
         const data = normalizeSuccessEnvelopeData(value);
@@ -149,14 +181,18 @@ export function printError(value, format = getRequestedStructuredOutputFormat())
         const notice = getPendingStructuredNotice();
         writeToStderr(toJson({
             ok: false,
+            ...summarizeStructuredError(value),
             error: value,
             ...(notice ? { _notice: notice } : {}),
         }));
         return;
     }
-    writeToStdout(toYaml({
+    const notice = getPendingStructuredNotice();
+    writeToStderr(toYaml({
         ok: false,
+        ...summarizeStructuredError(value),
         error: value,
+        ...(notice ? { _notice: notice } : {}),
     }));
 }
 export function printYaml(value) {

package/dist/utils/redact.js

@@ -6,5 +6,5 @@ export function redactAuthorization(authorization) {
     if (trimmed.length <= 12) {
         return '***';
     }
-    return `${trimmed.slice(0, 6)}...${trimmed.slice(-4)}`;
+    return `${trimmed.slice(0, 4)}...${trimmed.slice(-2)}`;
 }

package/dist/utils/sqliteLease.d.ts

@@ -0,0 +1,8 @@
+export type SqliteLeaseOptions = {
+    lockPath: string;
+    timeoutMs: number;
+    maxWaitMs?: number;
+    pollIntervalMs?: number;
+    createBusyError?: () => Error;
+};
+export declare function acquireExclusiveSqliteLease(options: SqliteLeaseOptions): Promise<() => Promise<void>>;

package/dist/utils/sqliteLease.js

@@ -0,0 +1,59 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import Database from 'better-sqlite3';
+function isSqliteBusyError(error) {
+    if (!error || typeof error !== 'object' || !('code' in error)) {
+        return false;
+    }
+    const code = String(error.code ?? '');
+    return code === 'SQLITE_BUSY' || code === 'SQLITE_LOCKED';
+}
+export async function acquireExclusiveSqliteLease(options) {
+    const requestedTimeout = Number.isFinite(options.timeoutMs)
+        ? Math.max(1, options.timeoutMs)
+        : 1;
+    const maxWaitMs = Number.isFinite(options.maxWaitMs)
+        ? Math.max(1, options.maxWaitMs)
+        : requestedTimeout;
+    const waitMs = Math.min(requestedTimeout, maxWaitMs);
+    const pollIntervalMs = Number.isFinite(options.pollIntervalMs)
+        ? Math.max(1, options.pollIntervalMs)
+        : 50;
+    const deadline = Date.now() + waitMs;
+    await fs.mkdir(path.dirname(options.lockPath), { recursive: true, mode: 0o700 });
+    while (Date.now() <= deadline) {
+        let leaseDb = null;
+        try {
+            leaseDb = new Database(options.lockPath);
+            leaseDb.pragma('busy_timeout = 0');
+            leaseDb.exec('BEGIN EXCLUSIVE');
+            await fs.chmod(options.lockPath, 0o600).catch(() => undefined);
+            return async () => {
+                const current = leaseDb;
+                if (!current) {
+                    return;
+                }
+                try {
+                    if (current.inTransaction) {
+                        current.exec('ROLLBACK');
+                    }
+                    current.close();
+                    leaseDb = null;
+                }
+                catch (error) {
+                    // Keep the handle reachable so a caller can retry instead of silently
+                    // dropping an owner lease whose SQLite connection may still be open.
+                    throw error;
+                }
+            };
+        }
+        catch (error) {
+            leaseDb?.close();
+            if (!isSqliteBusyError(error)) {
+                throw error;
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+        }
+    }
+    throw options.createBusyError?.() ?? new Error(`Timed out waiting for SQLite lease: ${options.lockPath}`);
+}

package/dist/utils/syncTimeout.d.ts

@@ -1 +1,7 @@
-export declare function parseSyncTimeoutMs(value: unknown): number | undefined;
+export declare const MAX_SYNC_TIMEOUT_MS = 2147483647;
+type ParseSyncTimeoutOptions = {
+    invalid?: 'throw' | 'undefined';
+    label?: string;
+};
+export declare function parseSyncTimeoutMs(value: unknown, options?: ParseSyncTimeoutOptions): number | undefined;
+export {};

package/dist/utils/syncTimeout.js

@@ -1,5 +1,6 @@
 import { DinoxError } from './errors.js';
-export function parseSyncTimeoutMs(value) {
+export const MAX_SYNC_TIMEOUT_MS = 2_147_483_647;
+export function parseSyncTimeoutMs(value, options = {}) {
     if (value === undefined || value === null) {
         return undefined;
     }
@@ -7,13 +8,13 @@ export function parseSyncTimeoutMs(value) {
     if (!text) {
         return undefined;
     }
-    // Commander options are typically strings; be strict and fail fast for non-integers.
-    if (!/^\d+$/.test(text)) {
-        throw new DinoxError('--sync-timeout must be a positive integer');
-    }
     const parsed = Number(text);
-    if (!Number.isSafeInteger(parsed) || parsed <= 0) {
-        throw new DinoxError('--sync-timeout must be a positive integer');
+    if (!/^\d+$/.test(text) || !Number.isSafeInteger(parsed) || parsed <= 0 || parsed > MAX_SYNC_TIMEOUT_MS) {
+        if (options.invalid === 'undefined') {
+            return undefined;
+        }
+        const label = options.label ?? '--sync-timeout';
+        throw new DinoxError(`${label} must be a positive integer no greater than ${MAX_SYNC_TIMEOUT_MS}`);
     }
     return parsed;
 }

package/dist/utils/terminalSanitization.js

@@ -1,6 +1,10 @@
-const ANSI_ESCAPE_RE = /\x1b\[[0-9;?>=!]*[a-zA-Z]|\x1b\][^\x07]*\x07/g;
+const ANSI_ESCAPE_RE = /\x1b\[[0-?]*[ -/]*[@-~]|\x1b\](?:(?!\x07|\x1b\\)[\s\S]){0,2048}(?:\x07|\x1b\\)/g;
 export function isDangerousUnicode(rune) {
     return ((rune >= 0x200b && rune <= 0x200d) ||
+        rune === 0x061c ||
+        rune === 0x200e ||
+        rune === 0x200f ||
+        rune === 0x2060 ||
         rune === 0xfeff ||
         (rune >= 0x202a && rune <= 0x202e) ||
         (rune >= 0x2028 && rune <= 0x2029) ||
@@ -21,7 +25,7 @@ export function sanitizeForTerminal(text) {
             result += char;
             continue;
         }
-        if (code < 0x20 || code === 0x7f) {
+        if (code < 0x20 || code === 0x7f || (code >= 0x80 && code <= 0x9f)) {
             continue;
         }
         if (isDangerousUnicode(code)) {

package/dist/utils/tiptapMarkdown.js

@@ -2,6 +2,7 @@ import { DinoxError } from './errors.js';
 import { generateId } from './id.js';
 import { createAudioNodeFromLink, createFileNodeFromLink, createImageNodeWithMetadata, createVideoNodeFromLink, getDinoxMarkdownManager, } from './tiptapMarkdownSchema.js';
 import { inferMimeTypeFromHref, normalizeDinoxImageAttrs, normalizeFileBlockAttrs, normalizeFrontmatterRaw, parseDinoxMarkdownComment, } from './tiptapMarkdownSchemaUtils.js';
+import { findMarkdownCodeRanges, findMarkdownLiteralRanges, isMarkdownOffsetInSortedRanges, } from './tiptapMarkdownSyntax.js';
 const CONTENT_PREVIEW_MAX_LENGTH = 400;
 const MEDIA_COMMENT_PATTERN = /<!--\s*({[\s\S]*?})\s*-->/g;
 const MEDIA_COMMENT_PLACEHOLDER_PREFIX = 'DINOX_MEDIA_META_';
@@ -124,7 +125,11 @@ function validateAndCleanDocument(doc) {
 function preprocessMarkdownMediaComments(markdown) {
     const metadataByPlaceholder = new Map();
     let counter = 0;
-    const nextMarkdown = markdown.replace(MEDIA_COMMENT_PATTERN, (rawComment) => {
+    const codeRanges = findMarkdownCodeRanges(markdown);
+    const nextMarkdown = markdown.replace(MEDIA_COMMENT_PATTERN, (rawComment, _json, offset) => {
+        if (isMarkdownOffsetInSortedRanges(offset, codeRanges)) {
+            return rawComment;
+        }
         const parsed = parseDinoxMarkdownComment(rawComment);
         if (!parsed) {
             return rawComment;
@@ -138,6 +143,46 @@ function preprocessMarkdownMediaComments(markdown) {
         metadataByPlaceholder,
     };
 }
+function preprocessMarkdownEscapes(markdown) {
+    const protectedRanges = findMarkdownLiteralRanges(markdown);
+    const placeholderPrefix = `DINOX_ESC_${generateId().replace(/-/g, '')}_`;
+    const replacements = new Map();
+    let output = '';
+    for (let index = 0; index < markdown.length;) {
+        const next = markdown[index + 1] ?? '';
+        if (markdown[index] === '\\' &&
+            /[!"#$%&'()*+,\-./:;<=>?@[\\\]^_`{|}~]/.test(next) &&
+            !isMarkdownOffsetInSortedRanges(index, protectedRanges)) {
+            const placeholder = `${placeholderPrefix}${replacements.size}__`;
+            replacements.set(placeholder, next);
+            output += placeholder;
+            index += 2;
+            continue;
+        }
+        output += markdown[index];
+        index += 1;
+    }
+    return { markdown: output, placeholderPrefix, replacements };
+}
+function restoreMarkdownEscapes(node, placeholderPrefix, replacements) {
+    if (replacements.size === 0) {
+        return node;
+    }
+    const placeholderPattern = new RegExp(`${placeholderPrefix}\\d+__`, 'g');
+    const restoreValue = (value) => {
+        if (typeof value === 'string') {
+            return value.replace(placeholderPattern, (placeholder) => replacements.get(placeholder) ?? placeholder);
+        }
+        if (Array.isArray(value)) {
+            return value.map(restoreValue);
+        }
+        if (value && typeof value === 'object') {
+            return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, restoreValue(item)]));
+        }
+        return value;
+    };
+    return restoreValue(node);
+}
 function extractStandaloneMarkdownLink(content) {
     if (!Array.isArray(content) || content.length !== 1) {
         return null;
@@ -308,9 +353,10 @@ export function convertMarkdownToNoteContent(markdown) {
             };
         }
         const preprocessed = preprocessMarkdownMediaComments(source);
-        const parsed = getDinoxMarkdownManager().parse(preprocessed.markdown);
+        const escaped = preprocessMarkdownEscapes(preprocessed.markdown);
+        const parsed = getDinoxMarkdownManager().parse(escaped.markdown);
         const normalized = normalizeStandaloneMarkdownLinksToMediaBlocks(parsed, preprocessed.metadataByPlaceholder);
-        const contentJson = validateAndCleanDocument(normalized);
+        const contentJson = validateAndCleanDocument(restoreMarkdownEscapes(normalized, escaped.placeholderPrefix, escaped.replacements));
         const contentText = normalizeContentText(getPreviewTextFromDocument(contentJson));
         return { contentJson, contentText };
     }

package/dist/utils/tiptapMarkdownSyntax.d.ts

@@ -0,0 +1,9 @@
+export type MarkdownSourceRange = {
+    start: number;
+    end: number;
+};
+export declare function escapeLiteralMarkdownText(value: string): string;
+export declare function isMarkdownOffsetInRanges(offset: number, ranges: readonly MarkdownSourceRange[]): boolean;
+export declare function isMarkdownOffsetInSortedRanges(offset: number, ranges: readonly MarkdownSourceRange[]): boolean;
+export declare function findMarkdownCodeRanges(source: string): MarkdownSourceRange[];
+export declare function findMarkdownLiteralRanges(source: string): MarkdownSourceRange[];