Markdown without silent content loss

1 · Two different formats

The record envelope and privacy boundary are in Data Structure; request/response behavior is in API Contracts. This format does not upload GB-sized source bytes again. Notes contain source references. Base64 encodes JSON; it is not encryption.

2 · Supported node and attribute matrix

These are the actual schema names and defaults. An omitted supported attribute receives its schema default when parsed into a ProseMirror node. The Drive decoder can return the original raw JSON with omitted defaults still omitted; compare schema-normalized meaning where appropriate. Do not invent a second image node named image: the schema uses imageEmbed.

Supported structured blocks and their supported attributes must survive an untouched app-preserving Drive round trip. Schema validity still matters: a JSON object with a type string is not proof of valid child nesting, valid cell geometry or a safe URL. Check the document and table invariants before accepting it.

3 · Supported mark matrix

Strong, em, underline, strike, code, link and highlight are all supported editor marks. Only the plain-file importer has the noted gaps. The Drive block payload preserves these marks in untouched supported body blocks. Do not call this a complete GFM implementation: pipe tables and task syntax are enabled, but not every GFM extension.

4 · Required rebuild: safe plain Markdown exchange

1. Basic Markdown: import/export paragraphs, headings, quotes, ordinary lists, ordered starts, rules, hard breaks, code, links, pipe tables and tasks with tested semantic round trips. Preserve the distinctions between task states; do not turn note tasks into account workflow states.
2. Images: a standalone Markdown image becomes an imageEmbed with its safe src and alt text as caption. The schema has no inline image node; an image mixed into a sentence falls back to a normal link with visible alt text. The importer must not throw merely because it sees an image token.
3. Safe URLs: allow validated http/https URLs and the documented app-relative source/note routes. Reject or render inert javascript:, data: HTML, executable/unknown schemes and unsafe protocol-relative destinations. Preserve the visible label/alt text when a URL is rejected. Never fetch a source just to import a note and never move or duplicate the original Drive file.
4. Lossy features: plain Markdown cannot represent the current schema’s image width, cell merges/colours/widths, heading IDs, player/reference atoms, canvas summary or custom link target/rel. Make that loss visible before export. Use readable link fallbacks for source/note/canvas references; do not claim that importing those links recreates the original typed atoms.
5. Formatting gaps: keep underline, highlight and strike intact in the app-preserving path. For plain exchange, define and test an explicit supported syntax or a warned text-only fallback for the unsupported marks. Do not silently convert underline to bold or advertise literal delimiters as restored formatting. Escape Markdown labels, cell separators and other delimiters so user text cannot change the intended link/block structure. Retaining code language requires a declared schema change; the current code_block schema has no such field.
6. Rich tables: the plain fallback flattens cells to text and column alignment. Warn about omitted numbering, per-cell layout and rich block structure. Keep the original table unchanged in the app-preserving path, including colours, widths and merge attributes.
7. Failed import: preserve the existing note, confirmed base and pending operation. Return a per-note validation/read error with the existing retry behavior. An error must never be replaced by an empty paragraph and then treated as a successful import.

The rebuild may support more plain syntax only with a declared testable contract. This chapter does not require a new editor, a new file format version, a new workflow or automatic conversion of old notes.

5 · App-preserving Drive block encoding

1. The current encoder writes exactly one filesandnotes: JSON line between opening and closing frontmatter delimiters. It is not a general YAML parser. Metadata excludes content, driveRevision, driveFileId and driveReadError; other supplied record metadata is retained.
2. Each top-level block has an opening comment containing Base64 JSON for that raw node, a readable Markdown projection, and a closing comment. Nested blocks, marks and attributes are inside the top-level payload.
3. On read, the current decoder serializes the decoded node again. If the readable block body matches that projection after trimming its outer whitespace, it keeps the original raw node. Internal formatting changes can trigger reparsing even if the text looks equivalent.
4. If the readable body changed, it is parsed as Markdown and replaces only that block. Markdown before, between or after framed blocks is also imported. Untouched media and other rich blocks stay structured.
5. The first H1 found in decoded content supplies the title; otherwise the metadata/fallback title is used. The service’s authenticated mapping, not an arbitrary metadata id, determines which existing Drive note is being read.

Valid synthetic image block

The following is a complete small Drive note example. Its unchanged readable image body is not reparsed, so width 320 survives in the encoded node. Editing the image body requires the safe Markdown-image import rule above.

---
filesandnotes: {"id":"doc-image-example","title":"Field image","folderId":"folder-notes","createdAt":1793000000000,"updatedAt":1793000001000,"trashedAt":null}
---

<!-- filesandnotes:block eyJ0eXBlIjoiaW1hZ2VFbWJlZCIsImF0dHJzIjp7InNyYyI6Ii9nb29nbGUtZHJpdmUvcmF3L2ZpbGUtaW1hZ2UtZXhhbXBsZSIsImNhcHRpb24iOiJGaWVsZCBpbWFnZSIsIndpZHRoIjozMjB9fQ== -->
![Field image](/google-drive/raw/file-image-example)
<!-- /filesandnotes:block -->

Current normalization caveat: the encoder replaces the first H1’s inline content with doc.title, preserving heading attributes but dropping title marks. It also filters unknown top-level types and may synthesize a title when nothing remains. These are limitations of the current implementation, not acceptable silent-loss behavior for a rebuild. Supported title marks must survive when the title is unchanged; any intentional title rewrite must be explicit and tested.

Parsing structured JSON also upgrades a paragraph containing only a Drive audio/video reference into an audio/video embed, and a standalone YouTube inline reference into a youtubeReference. These are known compatibility normalizations. Keep source URLs and IDs unchanged; do not apply such upgrades to a reference embedded in an ordinary sentence.

6 · External edits, malformed metadata and unknown content

Recovery must obey Failure Recovery. Retaining an original for recovery means the user’s browser/Drive and request-scoped processing; it does not authorize a persistent readable server archive. Do not delete the last good local copy, merge base, queue entry or the remote original to make validation pass.

7 · Synthetic before/after expectations

Untouched rich source

Before (editor JSON):
{"type":"imageEmbed","attrs":{"src":"/google-drive/raw/file-image-example","caption":"Field image","width":320}}

App-preserving Drive encode → decode:
The same node and width:320 return. The source bytes remain in Drive.

Plain export:
![Field image](/google-drive/raw/file-image-example)

Required safe plain import:
imageEmbed with the same src and caption, width:null;
warn that plain export did not carry width.
Current source instead throws on the image token: a known gap to fix.

Changed paragraph, untouched audio

Before: framed paragraph "Original observation." followed by audioEmbed.
External edit: replace only the paragraph’s readable body with:
**Changed outside the app**

Expected:
paragraph → text "Changed outside the app" marked strong;
following audioEmbed → original JSON unchanged;
note ID, folder and optional metadata → unchanged.
A local edit newer than the confirmed base is still merged/handled by the normal sync contract.

Do not confuse live input rules with Markdown import

Editor underline mark → current plain export: __Underlined__
Current plain import: strong mark, not underline.
Editor highlight mark → current plain export: ==Highlighted==
Current plain import: literal delimiter text, not highlight.
Editor strike mark → current plain export: ~~Struck~~
Current plain import: literal delimiter text, not strike.

Required: preserve these marks in app-preserving Drive storage.
Plain export/import must state its tested syntax or warned fallback;
none of the current outcomes above is a lossless-formatting claim.

8 · Executable fixture expectations

The synthetic fixture set has a valid rich note with every supported body mark, lists, tasks, aligned rich table cells, image width, audio/video, note/media references, a canvas summary and optional YouTube nodes. All identifiers are fictional and no fixture performs live API calls. The app-preserving fixture uses an ordinary unmarked title H1 so the current title-mark limitation is not hidden inside a passing assertion.

1. MD-DRIVE-RICH: validate input with parseDocument(input.content).check(); deep-compare decodeDriveNote(encodeDriveNote(input)) with the expected complete record. Compare title, IDs, timestamps, optional metadata, block order, marks and attributes, not only textContent.
2. MD-DRIVE-EXTERNAL-HEADING: change only the readable H1 projection; require the new title and exact equality of every untouched block.
3. MD-PLAIN-TABLE / MD-PLAIN-TASKS: compare parsed node JSON, alignment and task status/checked pairs. JSON-normalize ProseMirror output before deepStrictEqual because its attrs objects can have a null prototype. Check the documented normalization separately from source-byte equality.
4. MD-PLAIN-FENCE / LINK / UNDERLINE / HIGHLIGHT-STRIKE / REFERENCES: the current-outcome fixtures expose losses. Required rebuild acceptance must not count an observed current gap as a successfully retained feature.
5. MD-CURRENT-IMAGE-GAP: current source error is recorded separately from the required safe image/link result. The rebuild must pass the latter.
6. MD-BAD-METADATA / MD-BAD-BLOCK: decoding rejects; integration checks retain existing local/base/pending data and do not send an empty replacement.
7. MD-METADATA-ONLY: the current decoder’s empty fallback is evidence, not the acceptance result. Verify the required protection around a known nonempty note.

The JSON fixture bundle separates 13 current-source evidence cases in fixtures from 7 mandatory target cases in requiredRebuildCases. Run the latter against the generated implementation; do not silently skip them to claim acceptance. Run these assertions with the fixture runner described in Acceptance. Record current-source observations separately from required rebuild checks. Add mandatory checks for supported title marks, unknown node/mark payloads, unsafe URLs, image import and nonempty-note protection; the current codec does not already satisfy all of them.

9 · Implementation prompt

Read Markdown Compatibility, Data Structure, API Contracts and Failure Recovery before implementing conversion.
Keep plain Markdown exchange separate from app-preserving Drive Markdown. Preserve the documented schema names, attributes, IDs and reference URLs.
Implement a lossless supported-node/mark/metadata Drive round trip, including supported title marks; keep external paragraph edits local to their changed blocks.
Make plain-format losses explicit. Import standalone Markdown images as safe imageEmbed nodes and inline images as safe labelled links; reject unsafe URLs without losing visible text.
Validate metadata and complete node shapes. Unknown or malformed content, HTML error pages and ambiguous empty results must not overwrite good notes, confirmed bases or pending work.
Keep failed/unsupported content recoverable in the user browser/Drive, with the existing per-note error/retry path. Do not add a persistent server note archive, a second sync protocol or a new workflow.
Run the synthetic compatibility fixtures plus required rebuild tests. Report known current-source gaps separately; do not copy them into the rebuilt implementation.

Source-checked against client/paper/editor-core.ts, client/paper/canvas-node.ts, src/services/drive-notes-markdown-service.js, src/services/notes-markdown-service.js and the Drive refresh validation in src/services/drive-notes-service.js. This chapter adds documentation and fixture evidence, not a runtime fix or a claim about production.