feat(editor): support ;; cursor marker in favorite keyword expansion

[datlechin]

Summary

Closes #1795.

SQL Favorites with a keyword already expand to the full saved query from the autocomplete popup. This adds the missing piece from #1795: a way to say where the cursor lands after expansion.

• Put ;; anywhere in a favorite's query. On expansion the marker is stripped and the cursor is placed at its position. Without a marker the cursor stays at the end of the inserted SQL, as before.
• Only the first ;; counts as a marker; later occurrences stay literal.
• Works for DB-stored favorites and linked .sql files with @keyword frontmatter, since both flow through the same completion path.

Research note: ;; is not a TablePlus convention. TablePlus has no cursor placement in its keyword bindings (requested there since 2018, never built). The marker is TablePro's own syntax, proposed by the issue author.

Implementation

• New SQLSnippetMarker finds and strips the first ;;, returning the caret offset in UTF-16 units (NSString-based, per the repo perf rules, so multibyte text before the marker resolves correctly).
• New SQLCompletionInsertion.resolve(for:) owns the full accept-time decision: the favorite marker rule, the existing function () rule, and the end-of-text default. Marker handling is gated on the .favorite kind, so other completions containing a literal ;; are never altered.
• SQLCompletionAdapter.completionWindowApplyCompletion shrinks to resolve, one replaceCharacters call, and setCursorPositions. One insert mutation means one Cmd+Z restores the typed keyword. The IME hasMarkedText() guard is unchanged.
• FavoriteEditDialog shows a caption under the Query field explaining the marker.
• Docs: Cursor Placement section on the Favorites page, a note on the Autocomplete page, and a frontmatter note for linked files.

Tests

• SQLSnippetMarkerTests: marker at start/middle/end, first-occurrence-only, multibyte/emoji offset correctness, and the issue's exact template.
• SQLCompletionInsertionTests: favorite with and without marker, mid-query marker, function paren rule, markerless favorite ending in (), non-favorite item containing a literal ;;.
• SQLCompletionProviderTests: the favorite factory keeps the raw marker in insertText, pinning that stripping happens at accept time only.

There is no direct test for completionWindowApplyCompletion itself: all branching moved into the pure helpers, and the remaining AppKit glue matches the accepted pattern in performFormatSQL. A TextViewController test harness was evaluated and rejected because the CodeEdit package does not export its test utilities.

Out of scope

• iCloud sync for SQL Favorites. SyncRecordType.favorite and .favoriteFolder exist but are unwired in SyncCoordinator, so favorites do not sync today. Pre-existing gap, should get its own issue.
• Honoring ;; in whole-tab insertion paths (Insert Favorite, run in new tab, drag and drop, Quick Switcher). Those set tab state before an editor exists and need a pending-cursor mechanism like the SQL editor should receive focus when creating a new tab #1765 focus fix.
• Marker support for plugin-provided statement completions.
• Completion ranking changes.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
TablePro	🔴 Failed	–	Jul 2, 2026, 1:35 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.