A notes product succeeds only when people can enter information without losing it, find it later, and deliver a readable copy. This guide uses a fictional community theater archive: an editor prepares programme notes, a coordinator organizes rehearsal material in Notion, and volunteers receive a PDF or an editable Word document. The examples describe an implementation and acceptance workflow. They are not claims that we have run your editor, connected your workspace, or tested these fictional documents.
Choose an editor boundary before choosing extensions
Write acceptance samples before building the toolbar. The archive needs paragraphs, headings, lists, quotations, links, and a source card containing an identifier, a title, and a review state. Keep collaboration, complex tables, and tracked changes outside the first release unless they are essential. Record CJK input, keyboard operation, mobile use, old-document imports, and future migration as requirements rather than discovering them after a demonstration.
Our open-source reference is Tiptap on GitHub. Its ProseMirror foundation and extension approach make it a useful candidate for a focused prototype. Distinguish the MIT-licensed open-source editor from subscription-dependent Pro Extensions. Assess the documentation, maintenance, extension boundaries, version compatibility, license, and migration cost together. Popularity is not evidence that your custom node will survive an upgrade. A large business difference does not automatically make a greenfield editor cheaper: selection mapping, input methods, clipboard rules, and history remain long-term responsibilities.
Prepare a decision record with existing features, required custom behavior, any proposed upstream modifications, and upgrade tests. Prefer a documented extension point when it satisfies the model. If a new engine is justified, explicitly budget for the schema, transactions, selection, history, serialization, import, and security. An editable DOM element supplies a surface; it does not supply all those contracts.
Scenario one: model the document before implementing the node
Separate the saved document from the rendered DOM. Give the source card a stable ID, allowed attributes, defaults, and a finite set of review states. Decide whether it is a block, whether it can contain editable children, how selection works, and what Backspace or Delete should do beside it. A text style such as emphasis is a mark. A structured source card is a node. Keyboard shortcuts, commands, and other behavior can be packaged as extensions. A visual node view must still respect the underlying document contract.
Create three fixtures: an empty document; ordinary bilingual text with a link; and a note containing two source cards. Specify the JSON representation, the HTML mapping, and a schema version. Preserve migration examples for old documents. If an import encounters an unknown node, report it or retain a readable placeholder. Silently removing content makes a successful import message misleading. Treat imported HTML as an exchange format that must be parsed and constrained, not as a trusted internal document.
Implement a small closed loop first. The insert command validates attributes; the node view displays the title and review state; serialization produces the agreed representation; parsing restores supported attributes. Confirm insertion, editing, selection, deletion, undo, saving, and reopening before adding more commands. Use input rules only for clearly defined short syntax. Paste rules need a separate policy because a pasted web article can contain remote images, styling, unsupported structure, and unsafe attributes. A pasted URL and a whole rich-text page are different cases.
For React integration, define when the editor instance is created and destroyed. Avoid recreating it on every parent render. Separate user edits from externally supplied content so an update does not create an edit-save-replace loop. Save requests should identify the document and its revision; a delayed response must not overwrite newer typing. A visible saved indicator should reflect an accepted save, not merely a timer or a locally queued request. Decide what happens to an unsaved draft after a network failure or a tab close.
A useful agent request is: “Add a source card with sourceId, title, and reviewState to the programme editor. Keep unknown source IDs readable. Start with the model and round-trip fixtures, then implement insert, edit, delete, and undo. Identify schema and version constraints. Do not replace the whole editor to solve a selection bug.” Deliver the model, fixtures, implementation, import/export comparison, and regression notes together; a screenshot alone cannot establish document integrity.
Diagnose input, history, and performance through observable layers
For duplicated Chinese input, record the operating system, browser, input method, composition sequence, and document changes before and after commitment. Investigate whether keyboard and input handlers both apply the same change during composition, or whether external state replaces the full document after each event. A fixed delay can conceal a race without fixing it. Filling a field with a completed Chinese string does not reproduce a real input method's composition lifecycle. Include actual IME testing on the intended environment.
For cursor jumps, compare selection positions, node identities, transactions, and component lifetimes. Look for a document replacement or unstable node view before blaming the input method. For broken undo, count the history entries created by one user action and determine whether programmatic updates should enter history. Collaboration history and local undo must be configured according to the extensions and versions actually used; two independent history mechanisms should not simply be layered together. Empty-paragraph behavior needs separate cases at the document edges, after a list, and beside a source card.
For HTML round-trip loss, locate the failing stage: parsing, the schema, serialization, or rendering. Compare semantic content such as headings, link destinations, source IDs, and text. Byte-for-byte HTML equality is often the wrong criterion because equivalent markup can differ. Define paste and output sanitization policies, including allowed attributes and link protocols. A normal-looking preview does not establish that malicious input is harmless, and a browser workflow test is not a complete XSS audit.
For large documents, measure parsing, transaction processing, node rendering, saving, and layout independently. Use small, medium, and large fixtures on the same device, recording typing delay and operation time. Investigate repeated full-document serialization or unnecessary rendering before introducing throttling or splitting. Opening one long document successfully says little about sustained editing. Keep a reproducible slow sample and a performance budget tied to the target environment.
Use a verified Skill at the browser regression step
Webapp Testing fits local UI regression after the model and editor interface exist. We checked its SkillPI detail, pinned Anthropic source, and Apache-2.0 license record. That is a source review, not a claim that we executed a security scan or ran tests on your application.
Prepare Python, Playwright, appropriate browser binaries, application startup instructions and a port, plus permission to use the fictional fixtures. Ask the agent to inspect the rendered DOM before choosing stable controls. Exercise source-card insertion, title changes, undo, save-failure feedback, and reopening. Keep assertions, screenshots, browser logs, and reproduction instructions. State the browser and exact coverage. Native IME behavior, backend durability, complete security, and compatibility across all devices still need their own evidence.
For example, a failed-save test should verify both the visible unsaved state and the continued availability of the draft. A reopen test should compare source IDs and text, not only check that the page loads. If a test passes against a mocked save, label that boundary and add a separate persistence check when a real test backend is available. This prevents a green browser report from being mistaken for an end-to-end storage guarantee.
Scenario two: organize a Notion inbox without losing provenance
Define retrieval needs before inventing tags. The theater team searches by production, material type, source, recording date, review state, and owner. Keep an inbox, a needs-review view, and an organized view. Preserve the original source and excerpt separately from the summary. A concise summary is useful for navigation but cannot replace evidence. Start with a few fictional pages to check property types, empty values, duplicates, and the queries that staff actually need.
Create a change preview containing the page ID, current location, proposed production, proposed tags, evidence for classification, attributes to change, any proposed move, and unresolved conflicts. Similar titles are not enough to identify duplicates: two rehearsal records may describe different versions of the same scene. Route uncertain matches to a review queue. A dry-run is a plan, not a guarantee that the later apply step is safe. Re-read page state before writing and skip a page that another person has changed.
When using an API or CLI, confirm the current interface version, integration access, and which pages are shared. Keep credentials in the host's appropriate credential configuration, not in prompts, notes, or public logs. If a page is inaccessible, inspect its identifier and sharing first; do not immediately expand access to the entire workspace. Apply a small batch and record success and failure per page. Retry only unfinished operations so a transient failure cannot append the same summary twice. Preserve a traceable original location and a recovery plan before moving or archiving anything.
Design a template around real queries: a production database related to a material database, with a dashboard for unreviewed items and recent changes. Write formula examples with expected inputs and outputs before using substring, filter, or map operations. Check property types, empty collections, and date boundaries against the current formula behavior. Importing Markdown does not establish that database relations, formulas, properties, and views were created correctly. Inspect each of them after import. Available automations and plan entitlements depend on the actual account; do not base the workflow on an unverified free-versus-paid claim.
A concrete handoff request is: “Review only the shared rehearsal inbox. Produce a proposed classification table with page IDs and reasons. Keep ambiguous pages unchanged. Show the changes before applying them, and report per-page results afterward.” That request states scope and evidence. It does not grant an agent permission to connect a new account or archive unrelated notes. This guide links a browser-testing Skill for its verified purpose rather than relabeling it as a Notion migration tool.
Scenario three: export semantic Markdown into accepted deliverables
Specify a mapping before conversion. Headings, ordinary lists, and links generally have straightforward representations. A source card can become a quotation block with its source and review state, while the original JSON remains in the source package. Complex tables, comments, interactive controls, and custom nodes may lose information. Present a conversion report that identifies those losses rather than quietly flattening everything.
Choose a target by use: PDF for stable reading, DOCX for later editing, and HTML for web presentation. Structured table data can have a separately designed CSV or spreadsheet export. Do not promise that every document structure converts faithfully into every data format. A conversion tool's particular file-size limit is not a general limit of Markdown, and splitting a document can break cross-references if not planned.
Pandoc's official manual is a useful reference for supported formats and conversion boundaries. Check the installed version and output formats. PDF additionally requires the chosen PDF engine and its dependencies; fonts must be available in that environment. Treat commands as version-specific instructions to review, not magic installation prompts. A bounded request is: “Convert the approved programme.md into standalone HTML and DOCX in a new output directory. Use an already installed, verified PDF engine for PDF. Keep the source unchanged and report unsupported nodes, missing images, and missing fonts.”
Inspect the intermediate representation when a PDF fails or changes layout. Confirm Chinese character coverage, font licensing for the intended use, line wrapping in long URLs, code highlighting, table page breaks, page numbers, contents navigation, and live link destinations. Use controlled image paths and package required assets for offline delivery. A remote image that loads on the author's machine may be missing for a recipient. Check that PDF text can be searched and copied, and preview every page in the target reader and page size.
Keep source content, conversion settings, dependency versions, assets, and the review record together. If a custom node cannot be represented in Word, use an explicit fallback and retain the canonical source rather than claiming an editable round trip. Reopening a generated document in the intended application is a more useful acceptance check than confirming that a file exists.
FAQ and acceptance handoff
Should we build from scratch? Prototype the hardest document and input cases first, then compare extension limits with maintenance and migration costs. Business differences alone do not settle the decision. Is correct-looking paste enough? No: check model validity, save-and-reopen behavior, undo, content policy, and export independently. A visual match proves only one layer.
Does organizing Notion require every page? Limit access to the task's necessary scope and check sharing before broadening it. Why are PDF characters missing? Inspect the engine, fonts, character coverage, and embedded result, keeping intermediate output for diagnosis. Why does a table disappear? Check whether the source contains a true table and whether the target supports its structure; simplify explicitly or keep an attachment instead of deleting content to make the layout fit.
The final handoff contains the schema and version, three document fixtures, editor regression evidence, Notion change preview and results, canonical source files, export settings, and a page-by-page review. Refresh Skill associations when the catalog changes by checking the new listing, pinned source, license, prerequisites, and the exact workflow step it covers. A similar name or a larger install count is not sufficient reason to replace a verified association.
Sources and scope
The original bilingual source records remain attached to this topic. This original theater example replaces promotional claims and unverified quotations, install counts, pricing assumptions, and blanket safety assurances. Editor selection refers to the Tiptap repository; conversion limitations and PDF prerequisites refer to the Pandoc manual. These references document tools and methods, not an installation, a Notion connection, or an executed test of this example.