Skip to content

Paste faithfully from anywhere, copy out losslessly, and type markdown like Notion - #12

Open
sanjaydotpro wants to merge 40 commits into
capy/markdown-renderingfrom
capy/faithful-paste
Open

sanjaydotpro wants to merge 40 commits into
capy/markdown-renderingfrom
capy/faithful-paste

Conversation

@sanjaydotpro

Copy link
Copy Markdown
Contributor

Stacked on #11. Pasting into a note now keeps what was copied, whether from AI chats, documents, mail, spreadsheets, code editors or web pages. A markdown note gets markdown, and any other note gets the plain note format. Copying out of a note carries everything back out, and markdown can be typed the way Notion takes it. Part of HIS-4.

Reading the clipboard

  • On macOS, iOS and Windows, one native call returns everything the clipboard holds: text, HTML, Kapy Notes' own type, pictures and copied files. On Android it returns the primary clip's text and HTML.
  • macOS also reads the RTFD pictures that a Cocoa app's own HTML points at, and VS Code's language from Chromium's custom data.
  • Pastes over 16 KB are converted off the UI isolate, so a long paste doesn't freeze the editor.

What a paste becomes

  • These come through:
    • headings
    • nested and numbered lists
    • to-dos, including ☐ and ☑ paragraphs
    • quotes
    • code blocks with their language
    • tables
    • links, emphasis and strikethrough
    • superscript and subscript
    • line breaks and rules
  • Avatars are left out.
  • Math from KaTeX, MathJax and MathML becomes TeX between dollar signs. Stacked conditions under a sum become \substack, and KaTeX's non-breaking spaces in text become ordinary spaces.
  • A paste fits the line it lands on:
    • a list pasted into a list item joins that list;
    • a single line pasted mid-line stays in the line;
    • the lines around a pasted picture stay tidy.
  • A paste is one edit, so one undo takes all of it back out.
  • Paste as plain text is ⇧⌘V (Ctrl+Shift+V elsewhere, rebindable in settings). The Mac's own Paste and Match Style (⌥⇧⌘V) and Paste Text in the touch menu do the same.

Pictures in a paste

  • Pictures that are on the clipboard go in at once. A web picture holds its place with a quiet box while it downloads, and one that won't load offers a button to open its link.
  • A picture known only by its web address keeps that address on the device. The address never syncs: the note waits to sync until the picture itself is in.
  • Picture sizes given in rem, em and pt are read.
  • Undo now gives back every picture its edit removed. Before, it kept only a fixed number.

Copying out

  • Every copy and cut writes three forms:
    • Kapy Notes' own type, carrying the words, their styles, the markdown flag and every attachment's bytes. The encryption key is never included.
    • HTML with the pictures embedded, for mail and documents.
    • Markdown as the plain text, for ChatGPT, Slack and GitHub.
  • A selection copied and pasted back comes back identical, in one undo step, in plain and markdown notes alike.
  • Known gap: Android carries only the words and pictures back, through the HTML.

Typing

  • Markdown shortcuts work as in Notion:

    • # for a heading;
    • - or * for a bullet;
    • [] and [x] for checkboxes;
    • three backticks and Return for a code block;
    • --- for a divider.

    Backspace or undo straight afterwards gives back exactly what was typed. A - or -- under words stays as typed, and escapes read as plain characters.

  • The results gutter now measures the note a line at a time, so a keystroke lays out only the lines it changed. In a profile build, typing in a 5,000-line markdown note went from about 3.1 s to 1.6 s a key. benchmark/editor_typing.dart measures it. Long notes are still slow in both modes. The per-line editor (HIS-14) is the fix for that, and the default flip waits for it.

Paste fixtures

test/fixtures/paste/ holds real captures from these sources, each with a macOS clipboard snapshot:

Apple Notes, ChatGPT, Claude, Excel, Finder, Gemini, GitHub, Gmail, Google Docs, Google Sheets, Numbers, Outlook, Pages, Perplexity, Safari, Slack, Stack Exchange, VS Code, Wikipedia, Word and ordinary web pages.

Each one is checked against what it should paste as (fixture_pipeline_test.dart and tool/paste_fixtures/validate.mjs). Notion is missing, because it needs a capture from a signed-in Notion.

Testing

  • Built and tested with Flutter 3.47.4 (~/dev/flutter) after flutter pub get --enforce-lockfile. The pinned 3.47.2 at ~/development/flutter is damaged on this Mac.
  • flutter analyze is clean. The full suite passes 2,299 tests, and the only failures are the 45 goldens that also fail on main under 3.47.4.
  • Anything that ran the app used its own bundle id, set on the command line only.

Not verified:

  • The Windows reader and writer are only compiled, by this PR's CI. Nothing has run them.
  • iOS tests hang on this Mac's simulator, and the Android build failed earlier, so neither has run on a device.
  • No copy or paste has gone through a real system clipboard. The tests use private pasteboards and channel fakes.

Overlap with #5 and #6

#5 (results at the ends of lines) and this branch both change line_metrics.dart. A trial merge with #6 and #5 is resolved: it analyzes clean and the editor suites pass. Once they land, this stack will be rebased onto main.

Open in Capy

@sanjaydotpro
sanjaydotpro force-pushed the capy/markdown-rendering branch 2 times, most recently from 23bd2f0 to eadf170 Compare November 17, 2026 05:31
Real headless-Chrome captures (Wikipedia, ChatGPT, Gemini, Perplexity, GitHub,
Google Docs/Sheets, MDN, Ask Ubuntu, emoji), synthesized native-app payloads
(Word, Outlook, Excel, Numbers, Apple Notes, Pages, Safari, Slack, Gmail,
VS Code, Finder, images), and the scripts that produced them, including a
read-only macOS pasteboard capture script.
Reads the clipboard's richest useful representation (an editor's code,
HTML, rich text, markdown text, plain text) and writes it as markdown for
a markdown note or as words plus heading, bold and italic ranges for a
plain one. Covers AI chats' math (KaTeX annotations, MathML, data-math),
Word lists, Google Docs code, GitHub task lists, Apple's sized headings,
emoji pictures and SVG badges.
The first pasted line joins the line at the caret and takes its kind, list
items continue the list, quotes stay quoted, and code and table cells only
take words.
A pasted picture from the web is held by a ref that remembers its address
(NoteImageRef.src). It is fetched at paste time, at most four at once, and
a failed download keeps its place with a Retry button.
Paste reads the whole clipboard at once, converts it off the UI isolate
when it is large, and inserts it as one undoable edit with picture
placeholders. Pasting into a table cell keeps line breaks as <br>, and
Cmd/Ctrl+Shift+V pastes the words only.
The rich clipboard channel gets a read method returning text, HTML,
the source URL, Safari's web archive, RTF and RTFD converted to HTML
with their pictures, VS Code's metadata, Kapy's own fragment, file
URLs and an image. Write also publishes Kapy's fragment type and can
target a named pasteboard, which the new tests use.
HTML Format with its header, Unicode text, dropped files, Kapy's
registered fragment format, and a picture: the PNG format when an app
published one, else the bitmap encoded as PNG with WIC. Write also
publishes Kapy's fragment as UTF-8.
The same snapshot as macOS, fetched with one items call so iOS asks
for permission to paste at most once. Write also publishes Kapy's
fragment type and can target a named pasteboard.
The first item's HTML and text, its content URI's bytes when that is a
picture (up to 25 MB), and the clip's MIME types.
Electron pickles DataTransfer's custom types into
org.chromium.web-custom-data, which is the only place a real VS Code
copy carries vscode-editor-data.
Each fixture goes onto a private pasteboard as recorded and is read the
way the channel reads. Snapshots with derived data are compared with
macos-snapshot.json; update_macos_snapshots.sh regenerates them.
Apple Notes, Pages and TextEdit write public.html with the Cocoa HTML
writer, which shows each picture by a file:/// URL of its name that no
reader can open. The RTFD beside it holds the bytes, so they are read
into resources under that URL even when the HTML itself is used.
Each fixture now carries expected.md and expected.plain.txt, the note a
paste from it produces in a markdown note and in a plain one, and a test
runs the whole corpus through the pipeline against them.
Undo and redo restore attachments from the refs the editor remembers each edit took out, and it kept only the latest 20. Undoing a paste of more pictures than that, or deleting a selection holding them, lost the rest on the way back. The newest edit's removals are now kept whole.
A picture moved onto a line of its own left the space before it at the end of the line above and the space after it at the start of the line below.
Unit tests for what each part of the paste pipeline promises, beside the fixture corpus that checks them together: the HTML reader's rules for each source, both writers, markdown text, the converter's choice of representation, MathML to TeX, and the downloader's limits.
A one-column table in a script position is what KaTeX draws \substack as. It was written back as a matrix, which typesets at full size under the operator.
Measured in a debug test run, a 32 KB markdown paste into a plain note took about 60 ms to convert, which is several frames. At 16 KB the worst path takes about 30 ms in debug, and less in a release build.
A rich paste lands in the note's own format with its carried picture in place, and a web picture that can't be fetched keeps its place, its address and a Retry button.
A note already waits to sync until every picture in it is uploaded, and a picture still at its address has nothing to upload. So NoteImageRef.src stays on the device and the sync contract is unchanged. The field's comment said otherwise; a sync test now holds the real behaviour in place.
Beside Retry, Open link takes the address to the browser, for a picture whose link has expired or needs a sign-in the app doesn't have.
KaTeX's MathML spells the spaces inside \text{} as U+00A0. Written back into TeX they were invisible characters a renderer may not draw as spaces.
Gemini sizes its file-chip icons in rem, so they read as having no size and came in as full-width pictures instead of being dropped with the other icons.
A selection of a Stack Exchange answer brought its posters' 32 px avatars in as pictures. A small picture whose alt text or class says avatar, or one from Gravatar, says who wrote something rather than what they wrote.
A dash or two under a line of words is a bullet or a divider on its way,
so the line above no longer flashes into a heading while it is typed.
An escape's backslash is no longer read by the calculator, so \- 5 is the
minus five it shows.
[x] makes a ticked task, a fence and Return writes its closing fence, and
--- under words gets a blank line so it stays a divider. Backspace or Undo
straight after a shortcut gives back what was typed, escaped so it stays
text. Nothing converts while an input method is composing.
writeHtml says what HtmlPasteReader reads, in the HTML Google Docs, Word,
Gmail and Notion paste: a to-do is the ☐ or ☑ it looks like, code keeps its
language class, tables keep their header row and alignment, and math is its
TeX between dollars, marked with the TeX in data-latex. Embedded characters
stand in for a note's pictures, which hold their place as one character.
noteHtml renders a note for copying out: a markdown note through the
markdown reader, read the way the editor reads it (math only between
dollars, a star between operands is multiplication), and a plain note
through its own format, with the bold, italic, heading and subtitle it keeps
beside the text. convertNote rewrites a note's text for a note of the other
kind through the paste writers, keeping every attachment's place.
A fragment copied out of a note now writes the kapy type beside its HTML
and text: versioned JSON with the body, its format ranges, whether it came
from a markdown note, and each attachment's ref with the bytes a paste
stores. Where the source note keeps an attachment, and the key that seals
it, stay out of it; reading it back recomputes the hash and refuses
anything malformed or past the copy caps.

The HTML is now the note as noteHtml renders it, each picture a data URI
at the width the note shows it, and it still opens with the v1 marker so
an older build pastes the pictures back. The plain text is a markdown
note's own markdown with ![image] for each picture, or a plain note's own
text. fromSnapshot prefers the kapy type to the marker, and a fragment of
32 KB or more is written and read on another isolate.
Ctrl-C and Ctrl-X, the menu's Copy and Cut, and the selection toolbar's
Copy now write the whole fragment for any selection rather than only one
holding a picture; Copy plain text is unchanged. Files, voice notes and
videos travel with their bytes while the selection keeps to the fragment
caps, and past them each is copied as its label, with a toast saying so.

Pasting a fragment rebuilds it as one edit, and so one undo step: its
styles come back, pictures are stored again at their width, files and
videos go in as dropped ones do and voice notes as recordings do. A
fragment from a note of the other kind is converted on the way in. A
keyboard copy now leaves the formatting toolbar up, as the field's own
copy does.
The new shortcut adds a row to Settings > Shortcuts, which shortens the
list's scrollbar thumb by a few pixels.
A note without markdown takes its words from the platform's own text
call again and pastes them exactly as it always has: no conversion, no
styles, Windows line ends and all. A conversion is markdown, which only
reads well drawn, so only a markdown note converts what it pastes, and it
reads everything on the clipboard in one go so a dictation app restoring
the clipboard cannot split what it converts.

Words alone copy out of a note without markdown the way the field copies
them; a selection that holds an attachment still goes out whole.

The plain writer's paste path, its formats, the reader of markdown for a
note without markdown and the old fragment read go with it. Every paste
fixture now goes through the editor's own Paste into both kinds of note:
without markdown it must come out exactly as the clipboard's text.
A list straight after another, as a bulleted list running into a
numbered one, now goes on down the page without a blank line between
them, unless the source had an empty line there. The HTML reader notes
such a line, and a note's own markdown keeps it through copy-out, where
the HTML a note copies writes it as an empty paragraph.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant