Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): show comment annotations dimmed instead of hiding typed text (#3009)

Nick Gomez9779a09e1aeb
diff --git a/.changeset/comment-annotations-dimmed.md b/.changeset/comment-annotations-dimmed.md
new file mode 100644
index 000000000..34551dfc3
--- /dev/null
+++ b/.changeset/comment-annotations-dimmed.md
@@ -0,0 +1,23 @@
+---
+'@inkeep/open-knowledge': patch
+---
+
+Show comment annotations dimmed in the editor instead of hiding them.
+
+Text that looks like comment syntax (`<!-- note -->`, `%%note%%`) is claimed by
+the comment promoter the next time a document is re-derived. The resulting
+comment mark and comment block rendered `display: none`, so prose a user typed
+as ordinary text disappeared from the editor while the bytes on disk stayed
+intact, with no way to recover it from the WYSIWYG.
+
+Comments now render dimmed in the editing surface, with the delimiter form shown
+alongside the body and a dashed rail plus gutter marker on the block form so it
+reads as annotation rather than as a blockquote. The app's read-only views that
+mount the editor schema (skill viewer, rendered diff) show comment bodies dimmed
+too; only fully rendered markdown output still hides them, as literal HTML
+comments. Comments are still dropped from cross-app clipboard payloads, and
+bytes are untouched in both directions.
+
+To turn an annotation back into ordinary text, edit the delimiters in source
+mode (`Cmd+/`) — backslash-escaping either delimiter (`\%\%`) keeps the run as
+prose. There is no WYSIWYG control for this yet.
diff --git a/docs/content/migrate/obsidian.mdx b/docs/content/migrate/obsidian.mdx
index c0c79076b..4898975d3 100644
--- a/docs/content/migrate/obsidian.mdx
+++ b/docs/content/migrate/obsidian.mdx
@@ -36,7 +36,7 @@ Most of what you write in Obsidian renders and round-trips in OpenKnowledge unch
| Tags | `#tag`, or `tags:` in frontmatter | Both forms are indexed and searchable. |
| Callouts | `> [!note]`, `> [!warning]`, foldable `> [!tip]-` | Rendered with icons. 15 types including Obsidian's set (`success`, `question`, `failure`, `bug`, `example`, `quote`, …); aliases like `summary` / `tldr` fold to `abstract`. |
| Highlights | `==highlighted==` | Rendered as a highlight mark. |
-| Comments | `%%hidden note%%` | Hidden in the editor, kept in the file. (`<!-- -->` works too.) |
+| Comments | `%%hidden note%%` | Shown dimmed in the editor (Obsidian live-preview style), hidden in published output and cross-app paste, kept byte-for-byte in the file. (`<!-- -->` works too.) |
| Math | `$inline$`, `$$block$$` | Rendered as LaTeX math. |
| Mermaid | ` ```mermaid ` fenced blocks | Rendered as diagrams. |
| Footnotes | `[^1]` with `[^1]: …` | Supported, including named footnotes. |
diff --git a/packages/app/package.json b/packages/app/package.json
index c553dc038..342cc81b7 100644
--- a/packages/app/package.json
+++ b/packages/app/package.json
@@ -26,7 +26,7 @@
"measure:fuzz": "bash scripts/measure-fuzz.sh",
"measure:stress": "bash scripts/measure-stress.sh",
"perf:compare": "bash scripts/perf-compare.sh",
- "test:e2e": "playwright test tests/stress/ux-interactions.e2e.ts tests/stress/file-tree-create.e2e.ts tests/stress/file-tree-drag-to-root.e2e.ts tests/stress/file-tree-deselect-to-root.e2e.ts tests/stress/create-then-rename-editable.e2e.ts tests/stress/find-replace.e2e.ts tests/stress/editor-tabs.e2e.ts tests/stress/crdt-stress.e2e.ts tests/stress/slash-command.e2e.ts tests/stress/paste-fidelity.e2e.ts tests/stress/fr-7a-disconnect-source-mode.e2e.ts tests/stress/docs-open.e2e.ts tests/stress/frozen-table-headers.e2e.ts tests/stress/asset-embed.e2e.ts tests/stress/asset-embed-advanced.e2e.ts tests/stress/asset-click-dispatch.e2e.ts tests/stress/handoff.e2e.ts tests/stress/multi-agent-presence.e2e.ts tests/stress/editor-mode-persistence.e2e.ts tests/stress/lint-config-toggle.e2e.ts tests/stress/schema-edit-fields-view.e2e.ts tests/stress/sidebar-search-pill.e2e.ts tests/stress/navigation-history.e2e.ts tests/stress/command-palette-semantic.e2e.ts tests/stress/agent-activity-panel.e2e.ts tests/stress/drop-pipeline-auto-open.e2e.ts tests/stress/command-palette-flicker.e2e.ts tests/stress/cm6-list-hanging-indent.e2e.ts tests/stress/ng7-rapid-nav-coherence.e2e.ts tests/stress/reveal-on-activate.e2e.ts tests/stress/selection-indicator.e2e.ts tests/stress/new-file-cross-doc-bleed.e2e.ts tests/stress/editor-mode-flip-cross-doc-bleed.e2e.ts tests/stress/editor-area-viewport-resize.e2e.ts tests/stress/qa-sidebar-responsive.e2e.ts tests/stress/prd-6955-reassertion-repro.e2e.ts tests/stress/prd-6955-reassertion-wedge.e2e.ts tests/stress/prd-6914-repro.e2e.ts tests/stress/showall-lazy-tree.e2e.ts tests/stress/tabs-component-strip.e2e.ts tests/stress/source-find-scroll.e2e.ts tests/stress/harness-app-warmth.e2e.ts tests/stress/qa-canary-authoring-both-modes.e2e.ts tests/stress/qa-canary-live-typing.e2e.ts tests/stress/keystroke-cadence-danger-space.e2e.ts tests/stress/jsx-unregistered-backspace-delete.e2e.ts tests/stress/jsx-unregistered-ime-concurrent.e2e.ts tests/stress/jsx-backspace-delete.e2e.ts tests/stress/link-authoring-bytes.e2e.ts tests/stress/link-authoring-apex.e2e.ts tests/stress/command-palette-parity.e2e.ts tests/stress/settings-search.e2e.ts tests/stress/chip-popover-positioning.e2e.ts tests/stress/docs-open-scroll-restore.e2e.ts tests/stress/file-tree-decoration-chip-strip-repro.e2e.ts tests/stress/grip-click-nodeselect.e2e.ts tests/stress/jsx-halo-semantics.e2e.ts tests/stress/jsx-image-body-click.e2e.ts tests/stress/jsx-prop-panel-placeholder.e2e.ts tests/stress/jsx-range-encompass-halo.e2e.ts tests/stress/jsx-wildcard-convert.e2e.ts tests/stress/markdown-lint.e2e.ts tests/stress/unified-problems.e2e.ts tests/stress/mid-type-recovery.e2e.ts tests/stress/observer-a-multi-client.e2e.ts tests/stress/outline-toolbar-occlusion.e2e.ts tests/stress/quiet-tree-hidden-doc.e2e.ts tests/stress/raw-mdx-fallback-onblur-upgrade.e2e.ts tests/stress/rename-noext-probe.e2e.ts tests/stress/show-ok-folders.e2e.ts tests/stress/source-polish.e2e.ts tests/stress/warm-skeleton-scroll-restore.e2e.ts tests/stress/props-toggle-scroll-preserve.e2e.ts tests/stress/yjs-no-dual-import.e2e.ts tests/stress/slash-command-auto-open.e2e.ts tests/stress/graph-panel-surfaces.e2e.ts tests/stress/clipboard-relative-url-source-fallback.e2e.ts tests/stress/asset-embed-real-fidelity.e2e.ts tests/stress/prop-upload.e2e.ts tests/stress/rename-content-preservation.e2e.ts tests/stress/rename-consolidation.e2e.ts tests/stress/outline-navigation.e2e.ts tests/stress/prd-7627-default-swatch.e2e.ts tests/stress/clipboard-dollar-math-source-fallback.e2e.ts tests/stress/source-mode-undo-keymap.e2e.ts tests/stress/timeline-recovered-restore.e2e.ts tests/stress/blank-line-preservation.e2e.ts tests/stress/landing-helpers.e2e.ts tests/stress/mode-switch-landing.e2e.ts",
+ "test:e2e": "playwright test tests/stress/ux-interactions.e2e.ts tests/stress/file-tree-create.e2e.ts tests/stress/file-tree-drag-to-root.e2e.ts tests/stress/file-tree-deselect-to-root.e2e.ts tests/stress/create-then-rename-editable.e2e.ts tests/stress/find-replace.e2e.ts tests/stress/editor-tabs.e2e.ts tests/stress/crdt-stress.e2e.ts tests/stress/slash-command.e2e.ts tests/stress/paste-fidelity.e2e.ts tests/stress/fr-7a-disconnect-source-mode.e2e.ts tests/stress/docs-open.e2e.ts tests/stress/frozen-table-headers.e2e.ts tests/stress/asset-embed.e2e.ts tests/stress/asset-embed-advanced.e2e.ts tests/stress/asset-click-dispatch.e2e.ts tests/stress/handoff.e2e.ts tests/stress/multi-agent-presence.e2e.ts tests/stress/editor-mode-persistence.e2e.ts tests/stress/lint-config-toggle.e2e.ts tests/stress/schema-edit-fields-view.e2e.ts tests/stress/sidebar-search-pill.e2e.ts tests/stress/navigation-history.e2e.ts tests/stress/command-palette-semantic.e2e.ts tests/stress/agent-activity-panel.e2e.ts tests/stress/drop-pipeline-auto-open.e2e.ts tests/stress/command-palette-flicker.e2e.ts tests/stress/cm6-list-hanging-indent.e2e.ts tests/stress/ng7-rapid-nav-coherence.e2e.ts tests/stress/reveal-on-activate.e2e.ts tests/stress/selection-indicator.e2e.ts tests/stress/new-file-cross-doc-bleed.e2e.ts tests/stress/editor-mode-flip-cross-doc-bleed.e2e.ts tests/stress/editor-area-viewport-resize.e2e.ts tests/stress/qa-sidebar-responsive.e2e.ts tests/stress/prd-6955-reassertion-repro.e2e.ts tests/stress/prd-6955-reassertion-wedge.e2e.ts tests/stress/prd-6914-repro.e2e.ts tests/stress/showall-lazy-tree.e2e.ts tests/stress/tabs-component-strip.e2e.ts tests/stress/source-find-scroll.e2e.ts tests/stress/harness-app-warmth.e2e.ts tests/stress/qa-canary-authoring-both-modes.e2e.ts tests/stress/qa-canary-live-typing.e2e.ts tests/stress/keystroke-cadence-danger-space.e2e.ts tests/stress/jsx-unregistered-backspace-delete.e2e.ts tests/stress/jsx-unregistered-ime-concurrent.e2e.ts tests/stress/jsx-backspace-delete.e2e.ts tests/stress/link-authoring-bytes.e2e.ts tests/stress/link-authoring-apex.e2e.ts tests/stress/command-palette-parity.e2e.ts tests/stress/settings-search.e2e.ts tests/stress/chip-popover-positioning.e2e.ts tests/stress/docs-open-scroll-restore.e2e.ts tests/stress/file-tree-decoration-chip-strip-repro.e2e.ts tests/stress/grip-click-nodeselect.e2e.ts tests/stress/jsx-halo-semantics.e2e.ts tests/stress/jsx-image-body-click.e2e.ts tests/stress/jsx-prop-panel-placeholder.e2e.ts tests/stress/jsx-range-encompass-halo.e2e.ts tests/stress/jsx-wildcard-convert.e2e.ts tests/stress/markdown-lint.e2e.ts tests/stress/unified-problems.e2e.ts tests/stress/mid-type-recovery.e2e.ts tests/stress/observer-a-multi-client.e2e.ts tests/stress/outline-toolbar-occlusion.e2e.ts tests/stress/quiet-tree-hidden-doc.e2e.ts tests/stress/raw-mdx-fallback-onblur-upgrade.e2e.ts tests/stress/rename-noext-probe.e2e.ts tests/stress/show-ok-folders.e2e.ts tests/stress/source-polish.e2e.ts tests/stress/warm-skeleton-scroll-restore.e2e.ts tests/stress/props-toggle-scroll-preserve.e2e.ts tests/stress/yjs-no-dual-import.e2e.ts tests/stress/slash-command-auto-open.e2e.ts tests/stress/graph-panel-surfaces.e2e.ts tests/stress/clipboard-relative-url-source-fallback.e2e.ts tests/stress/asset-embed-real-fidelity.e2e.ts tests/stress/prop-upload.e2e.ts tests/stress/rename-content-preservation.e2e.ts tests/stress/rename-consolidation.e2e.ts tests/stress/outline-navigation.e2e.ts tests/stress/prd-7627-default-swatch.e2e.ts tests/stress/clipboard-dollar-math-source-fallback.e2e.ts tests/stress/source-mode-undo-keymap.e2e.ts tests/stress/timeline-recovered-restore.e2e.ts tests/stress/blank-line-preservation.e2e.ts tests/stress/landing-helpers.e2e.ts tests/stress/mode-switch-landing.e2e.ts tests/stress/comment-annotation-visibility.e2e.ts",
"test:e2e:install-browsers": "playwright install chromium webkit firefox",
"test:visual": "playwright test --config playwright.visual.config.ts",
"test:visual:update": "playwright test --config playwright.visual.config.ts --update-snapshots",
diff --git a/packages/app/src/editor/clipboard/comment-clipboard-contract.test.ts b/packages/app/src/editor/clipboard/comment-clipboard-contract.test.ts
index 8eb9250ea..43a301c40 100644
--- a/packages/app/src/editor/clipboard/comment-clipboard-contract.test.ts
+++ b/packages/app/src/editor/clipboard/comment-clipboard-contract.test.ts
@@ -645,7 +645,7 @@ describe('carrier proof — mdManager.parse restores comment constructs from the
// ─── renderHTML omission contract (attribute level, pinned) ────────────
describe('renderHTML stamps the clipboard opt-out attr', () => {
- test('comment mark renders with data-clipboard-omit="true" + display:none', () => {
+ test('comment mark renders with data-clipboard-omit="true" and no hiding style', () => {
const json = md.parse('Prose with %%hidden note%% inside.');
const doc = schema.nodeFromJSON(json);
let found = false;
@@ -655,7 +655,9 @@ describe('renderHTML stamps the clipboard opt-out attr', () => {
const spec = mark.type.spec.toDOM?.(mark, true);
const attrs = (spec as [string, Record<string, string>])?.[1] ?? {};
expect(attrs['data-clipboard-omit']).toBe('true');
- expect(attrs.style).toContain('display: none');
+ // Omission rides the attribute, never a style — the editing
+ // surface has to keep showing whatever the promoter claimed.
+ expect(attrs.style ?? '').not.toContain('display: none');
found = true;
}
}
@@ -663,7 +665,7 @@ describe('renderHTML stamps the clipboard opt-out attr', () => {
expect(found).toBe(true);
});
- test('commentBlock renders with data-clipboard-omit="true" + display:none', () => {
+ test('commentBlock renders with data-clipboard-omit="true" and no hiding style', () => {
const json = md.parse('Visible.\n\n%%\n\nsecret block body\n\n%%');
const doc = schema.nodeFromJSON(json);
let found = false;
@@ -672,7 +674,7 @@ describe('renderHTML stamps the clipboard opt-out attr', () => {
const spec = node.type.spec.toDOM?.(node);
const attrs = (spec as [string, Record<string, string>])?.[1] ?? {};
expect(attrs['data-clipboard-omit']).toBe('true');
- expect(attrs.style).toContain('display: none');
+ expect(attrs.style ?? '').not.toContain('display: none');
found = true;
}
});
diff --git a/packages/app/src/globals.comment-annotations.test.ts b/packages/app/src/globals.comment-annotations.test.ts
new file mode 100644
index 000000000..df71c6081
--- /dev/null
+++ b/packages/app/src/globals.comment-annotations.test.ts
@@ -0,0 +1,102 @@
+/**
+ * globals.css — comment annotations must stay legible.
+ *
+ * Comment annotations used to be hidden by an inline `display: none` in the PM
+ * binding, which the schema class guard in
+ * `tests/dom/promoter-claimed-text-visibility.dom.test.tsx` covers. Once that
+ * style moved out of the schema, this stylesheet became the thing that decides
+ * whether a promoted run is legible — and jsdom loads no stylesheet, so a
+ * `.comment-mark { display: none }` regression would restore the original bug
+ * with the whole suite green.
+ *
+ * Reading the stylesheet as data is the sibling `globals.*.test.ts` pattern.
+ * The check covers both spellings of hiding that reach this file: the literal
+ * declarations and the Tailwind utility form, since `@apply hidden` compiles
+ * to `display: none` and this stylesheet uses `@apply` throughout.
+ *
+ * It is a text-level check, not a computed-style one — it cannot see cascade,
+ * specificity, or an ancestor that hides the subtree. The Playwright case in
+ * `tests/stress/comment-annotation-visibility.e2e.ts` reads `getComputedStyle`
+ * against the compiled stylesheet and dominates this one; this stays as the
+ * deterministic tier that runs on every unit invocation.
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, test } from 'vitest';
+
+const GLOBALS_CSS = resolve(dirname(fileURLToPath(import.meta.url)), 'globals.css');
+
+/** Declaration bodies of every rule whose selector list mentions `selector`. */
+function ruleBodiesFor(css: string, selector: string): string[] {
+ const bodies: string[] = [];
+ // Selector lists span lines and carry pseudo-elements / attribute
+ // qualifiers, so match up to the opening brace rather than assume a shape.
+ const pattern = new RegExp(`([^{}]*${selector.replace('.', '\\.')}[^{}]*)\\{([^}]*)\\}`, 'g');
+ let match: RegExpExecArray | null = pattern.exec(css);
+ while (match !== null) {
+ bodies.push(match[2]);
+ match = pattern.exec(css);
+ }
+ return bodies;
+}
+
+/**
+ * Both spellings of "this element is not rendered". The utility arm matters as
+ * much as the literal one: `@apply hidden` and `@apply invisible` compile to
+ * `display: none` and `visibility: hidden`, and leave no literal token in the
+ * source for the first arm to catch.
+ *
+ * The utility name has to start a token, hence the lookbehind rather than a
+ * word boundary: `\b` treats `-` as a boundary, so it would report
+ * `@apply overflow-hidden` as a hiding rule. A variant prefix separator is
+ * admitted alongside whitespace so `@apply md:hidden` still counts.
+ */
+const HIDING_DECLARATION =
+ /display\s*:\s*none|visibility\s*:\s*hidden|opacity\s*:\s*0(?!\.)|@apply\s[^;{}]*(?<=[\s:])(?:hidden|invisible)(?=\s|;|$)/i;
+
+const ANNOTATION_SELECTORS = ['.comment-mark', '.comment-block'] as const;
+
+describe('globals.css keeps comment annotations legible', () => {
+ const css = readFileSync(GLOBALS_CSS, 'utf8');
+
+ test.each(ANNOTATION_SELECTORS)('%s carries no rule that hides it', (selector) => {
+ const bodies = ruleBodiesFor(css, selector);
+ // Non-vacuity: the selector has to actually be styled, or this would pass
+ // on a stylesheet that never mentions it.
+ expect(bodies.length).toBeGreaterThan(0);
+ expect(bodies.filter((body) => HIDING_DECLARATION.test(body))).toEqual([]);
+ });
+
+ test.each(ANNOTATION_SELECTORS)('%s is dimmed via the muted-foreground token', (selector) => {
+ const bodies = ruleBodiesFor(css, selector);
+ expect(bodies.some((body) => /color\s*:\s*var\(--muted-foreground\)/.test(body))).toBe(true);
+ });
+
+ // The predicate is the whole guard, so it gets its own fixtures rather than
+ // resting on the stylesheet happening to contain each shape today.
+ test.each([
+ ['literal display', 'display: none;'],
+ ['literal visibility', 'visibility: hidden;'],
+ ['literal opacity', 'opacity: 0;'],
+ ['utility display', '@apply hidden;'],
+ ['utility visibility', '@apply invisible;'],
+ ['utility among others', '@apply mt-2 hidden rounded-sm;'],
+ ['utility behind a breakpoint variant', '@apply md:hidden;'],
+ ['utility behind a theme variant', '@apply dark:invisible;'],
+ ])('the hiding predicate fires on %s', (_label, declaration) => {
+ expect(HIDING_DECLARATION.test(declaration)).toBe(true);
+ });
+
+ test.each([
+ ['a fractional opacity', 'opacity: 0.6;'],
+ ['an unrelated utility', '@apply mt-2 rounded-sm;'],
+ ['a colour', 'color: var(--muted-foreground);'],
+ ['an overflow rule', 'overflow: hidden;'],
+ ['an overflow utility', '@apply overflow-hidden;'],
+ ['a hyphenated utility ending in the token', '@apply scrollbar-hidden;'],
+ ])('the hiding predicate does not fire on %s', (_label, declaration) => {
+ expect(HIDING_DECLARATION.test(declaration)).toBe(false);
+ });
+});
diff --git a/packages/app/src/globals.css b/packages/app/src/globals.css
index 9c57a24b0..680723d9c 100644
--- a/packages/app/src/globals.css
+++ b/packages/app/src/globals.css
@@ -1235,6 +1235,83 @@
@apply py-0.5 px-1 rounded-sm bg-amber-100 dark:bg-amber-900/50;
}
+/* Authoring annotations (`%%…%%`, `<!-- … -->`). The editing surface shows
+ * them dimmed rather than hiding them: the comment promoter claims literal
+ * comment syntax wherever it appears in the bytes, including prose a user
+ * typed without meaning it as a comment, so `display: none` here would
+ * delete typed text from the surface it was typed into. Reading surfaces
+ * still hide them — the mdast→hast renderer emits a literal HTML comment.
+ *
+ * The delimiters are not in the document (the promoter strips them and
+ * records the form as an attribute), so they are drawn as pseudo-elements.
+ * That keeps them out of the text content ProseMirror maps positions
+ * against and out of the serialized bytes. */
+.comment-mark {
+ color: var(--muted-foreground);
+ font-style: italic;
+}
+
+/* The delimiters are chrome, not prose. `content: "…" / ""` supplies an empty
+ * alternative text so assistive technology does not read the punctuation out
+ * as part of the sentence — `user-select: none` only governs mouse selection
+ * and in-editor copy, it says nothing to AT. No extra opacity: these glyphs
+ * are the only signifier that a run is an annotation, so dimming them below
+ * the body they label put them under the 3:1 non-text contrast floor in the
+ * light theme. */
+.comment-mark::before,
+.comment-mark::after {
+ content: "%%" / "";
+ font-style: normal;
+ user-select: none;
+}
+
+.comment-mark[data-source-form="html"]::before {
+ content: "<!--" / "";
+ margin-right: 0.15em;
+}
+
+.comment-mark[data-source-form="html"]::after {
+ content: "-->" / "";
+ margin-left: 0.15em;
+}
+
+/* The block form needs an affordance the inline form gets from its delimiter
+ * glyphs, and it has to stay distinguishable from a blockquote, which sits a
+ * few rules below with its own muted left rail. A dashed rail plus a `%%`
+ * marker in the gutter carries both: dashed reads as "not part of the prose"
+ * where blockquote's solid rail reads as "quoted prose", and the marker names
+ * the construct the way the inline glyphs do. */
+.comment-block {
+ position: relative;
+ color: var(--muted-foreground);
+ font-style: italic;
+ border-left: 2px dashed color-mix(in oklab, var(--muted-foreground) 45%, transparent);
+ padding-left: 0.75rem;
+ margin: 0.5rem 0;
+}
+
+/* `background: inherit` rather than the page token so the knockout tracks the
+ * local surface when the block sits inside a callout, a card, or a selection
+ * highlight. The offset stays inside the block's own margin box so the marker
+ * cannot collide with the previous line's descenders or clip when the block is
+ * a first child. */
+.comment-block::before {
+ content: "%%" / "";
+ position: absolute;
+ left: 0.35rem;
+ top: -0.45em;
+ font-style: normal;
+ font-size: 0.7em;
+ line-height: 1;
+ padding: 0 0.15rem;
+ background: inherit;
+ user-select: none;
+}
+
+.comment-block[data-source-form="html"]::before {
+ content: "<!--" / "";
+}
+
.ProseMirror .ok-find-match {
border-radius: 0.15rem;
background-color: color-mix(in oklab, var(--color-agent) 28%, transparent);
diff --git a/packages/app/tests/dom/comment-visibility-after-rederive.dom.test.tsx b/packages/app/tests/dom/comment-visibility-after-rederive.dom.test.tsx
new file mode 100644
index 000000000..fe70dc5ec
--- /dev/null
+++ b/packages/app/tests/dom/comment-visibility-after-rederive.dom.test.tsx
@@ -0,0 +1,178 @@
+/**
+ * Typed comment syntax must stay visible in the WYSIWYG.
+ *
+ * The comment promoter claims a literal `<!-- … -->` / `%%…%%` run on the
+ * next re-derivation, so prose a user typed becomes a `comment` mark or a
+ * `commentBlock` node. When those bindings render `display: none` the text
+ * leaves the editing surface entirely while the bytes on disk stay perfect:
+ * the author sees their sentence delete itself and has no way to get it back
+ * from the WYSIWYG. Comments are annotation, not deletion — the editing
+ * surface shows them dimmed (Obsidian live-preview behaviour) and only
+ * reading surfaces hide them.
+ *
+ * The rig is the production re-derivation, not a re-implementation of it:
+ * Observer A serializes the fragment into Y.Text, Observer B splits the
+ * frontmatter region off and re-parses the body with `parseWithFallback`.
+ * A test that only checked `parse()` would miss the composition that
+ * actually re-derives a live document.
+ *
+ * Visibility is read off the rendered ProseMirror DOM rather than the node
+ * tree, because "the text is still in the document" is exactly the property
+ * that held while the bug was live.
+ */
+
+import { MarkdownManager, sharedExtensions, stripFrontmatter } from '@inkeep/open-knowledge-core';
+import { cleanup } from '@testing-library/react';
+import { Editor, type JSONContent } from '@tiptap/core';
+import { afterEach, describe, expect, test } from 'vitest';
+
+const mdManager = new MarkdownManager({
+ extensions: sharedExtensions,
+ deriveStructuralFreshness: true,
+});
+
+const mounted: Array<{ editor: Editor; container: HTMLDivElement }> = [];
+
+afterEach(() => {
+ for (const { editor, container } of mounted.splice(0)) {
+ editor.destroy();
+ container.remove();
+ }
+ cleanup();
+});
+
+function mount(content?: JSONContent): { editor: Editor; container: HTMLDivElement } {
+ const container = document.createElement('div');
+ document.body.appendChild(container);
+ const editor = new Editor({
+ element: container,
+ ...(content ? { content } : {}),
+ extensions: sharedExtensions,
+ editable: true,
+ });
+ const entry = { editor, container };
+ mounted.push(entry);
+ return entry;
+}
+
+/** Observer A serialize into Observer B's frontmatter-stripped re-parse. */
+function rederive(doc: JSONContent): { bytes: string; next: JSONContent } {
+ const bytes = mdManager.serialize(doc);
+ return { bytes, next: mdManager.parseWithFallback(stripFrontmatter(bytes).body) };
+}
+
+/**
+ * Text a reader can actually see. Skips any subtree the renderer hid with an
+ * inline `display: none` or `hidden`, which is what made the typed run
+ * vanish. `textContent` would report the hidden run as present and pass.
+ */
+function visibleText(root: HTMLElement): string {
+ let out = '';
+ const walk = (node: ChildNode): void => {
+ if (node.nodeType === Node.TEXT_NODE) {
+ out += node.textContent ?? '';
+ return;
+ }
+ if (!(node instanceof HTMLElement)) return;
+ if (
+ node.style.display === 'none' ||
+ node.style.visibility === 'hidden' ||
+ node.hasAttribute('hidden')
+ )
+ return;
+ for (const child of Array.from(node.childNodes)) walk(child);
+ };
+ for (const child of Array.from(root.childNodes)) walk(child);
+ return out;
+}
+
+/** Type a literal run with the input-rule pipeline bypassed, as paste does. */
+function insertLiteral(editor: Editor, text: string): void {
+ editor.view.dispatch(editor.state.tr.insertText(text));
+}
+
+describe('typed comment syntax survives re-derivation visibly', () => {
+ const CASES = [
+ { name: 'html, whole paragraph', typed: '<!-- hidden note -->', visible: 'hidden note' },
+ { name: 'percent, whole paragraph', typed: '%%hidden note%%', visible: 'hidden note' },
+ { name: 'html, mid paragraph', typed: 'before <!-- mid --> after', visible: 'mid' },
+ { name: 'percent, mid paragraph', typed: 'before %%mid%% after', visible: 'mid' },
+ ] as const;
+
+ for (const { name, typed, visible } of CASES) {
+ test(`${name}: the typed run is visible before AND after re-derivation`, () => {
+ const { editor, container } = mount();
+ insertLiteral(editor, typed);
+ expect(visibleText(container)).toContain(visible);
+
+ const { next } = rederive(editor.getJSON());
+ editor.commands.setContent(next);
+
+ expect(visibleText(container)).toContain(visible);
+ });
+
+ test(`${name}: the bytes are unchanged by the re-derivation`, () => {
+ const { editor } = mount();
+ insertLiteral(editor, typed);
+
+ // Iterate the re-derivation on its own rather than through the editor:
+ // a mounted editor appends a TrailingNode, which adds a newline that
+ // belongs to the editor's affordance rather than to the round-trip.
+ let doc: JSONContent = editor.getJSON();
+ for (let iteration = 0; iteration < 4; iteration += 1) {
+ const step = rederive(doc);
+ expect(step.bytes).toBe(`${typed}\n`);
+ doc = step.next;
+ }
+ });
+ }
+});
+
+describe('a comment stays marked as a comment while it is visible', () => {
+ test('the promoted run renders inside the comment mark element', () => {
+ const { editor, container } = mount();
+ insertLiteral(editor, 'before %%mid%% after');
+ editor.commands.setContent(rederive(editor.getJSON()).next);
+
+ const marker = container.querySelector('[data-comment-mark]');
+ expect(marker).not.toBeNull();
+ expect(marker?.textContent).toBe('mid');
+ });
+
+ test('the promoted block renders inside the comment block element', () => {
+ const { editor, container } = mount();
+ insertLiteral(editor, '<!-- hidden note -->');
+ editor.commands.setContent(rederive(editor.getJSON()).next);
+
+ const marker = container.querySelector('[data-comment-block]');
+ expect(marker).not.toBeNull();
+ expect(marker?.textContent).toContain('hidden note');
+ });
+
+ test('a deliberately applied comment mark is visible too', () => {
+ const { editor, container } = mount();
+ editor.commands.setComment();
+ insertLiteral(editor, 'deliberate note');
+
+ expect(visibleText(container)).toContain('deliberate note');
+ expect(container.querySelector('[data-comment-mark]')).not.toBeNull();
+ });
+});
+
+describe('comment content stays out of the clipboard', () => {
+ test('both bindings keep the clipboard opt-out stamp', () => {
+ const { editor, container } = mount();
+ insertLiteral(editor, 'before %%mid%% after');
+ editor.commands.setContent(rederive(editor.getJSON()).next);
+ expect(
+ container.querySelector('[data-comment-mark]')?.getAttribute('data-clipboard-omit'),
+ ).toBe('true');
+
+ const block = mount();
+ insertLiteral(block.editor, '<!-- hidden note -->');
+ block.editor.commands.setContent(rederive(block.editor.getJSON()).next);
+ expect(
+ block.container.querySelector('[data-comment-block]')?.getAttribute('data-clipboard-omit'),
+ ).toBe('true');
+ });
+});
diff --git a/packages/app/tests/dom/promoter-claimed-text-visibility.dom.test.tsx b/packages/app/tests/dom/promoter-claimed-text-visibility.dom.test.tsx
new file mode 100644
index 000000000..48f3f749c
--- /dev/null
+++ b/packages/app/tests/dom/promoter-claimed-text-visibility.dom.test.tsx
@@ -0,0 +1,149 @@
+/**
+ * Class guard for the claim-then-hide shape.
+ *
+ * The markdown pipeline runs a chain of promoters that turn literal source
+ * runs into live constructs on every re-derivation. That is the authoring
+ * feature, and it is fine as long as the construct still SHOWS the claimed
+ * text. It stops being fine when the resulting PM binding hides its own
+ * content: the run then leaves the editing surface while the bytes stay
+ * perfect, and the author has no way to reach the text from the WYSIWYG.
+ *
+ * Two complementary checks. The schema sweep is the general one — it probes
+ * every mark and node the editor can hold, so a future extension that
+ * reaches for `display: none` fails here rather than in a user's document.
+ * The typed sweep is the specific one, running the promoters that keep their
+ * claimed run as text through a real editor and the production re-derivation.
+ */
+
+import { MarkdownManager, sharedExtensions, stripFrontmatter } from '@inkeep/open-knowledge-core';
+import { cleanup } from '@testing-library/react';
+import { Editor, getSchema, type JSONContent } from '@tiptap/core';
+import { afterEach, describe, expect, test } from 'vitest';
+
+const mdManager = new MarkdownManager({
+ extensions: sharedExtensions,
+ deriveStructuralFreshness: true,
+});
+
+const mounted: Array<{ editor: Editor; container: HTMLDivElement }> = [];
+
+afterEach(() => {
+ for (const { editor, container } of mounted.splice(0)) {
+ editor.destroy();
+ container.remove();
+ }
+ cleanup();
+});
+
+function mount(): { editor: Editor; container: HTMLDivElement } {
+ const container = document.createElement('div');
+ document.body.appendChild(container);
+ const editor = new Editor({ element: container, extensions: sharedExtensions, editable: true });
+ const entry = { editor, container };
+ mounted.push(entry);
+ return entry;
+}
+
+function visibleText(root: HTMLElement): string {
+ let out = '';
+ const walk = (node: ChildNode): void => {
+ if (node.nodeType === Node.TEXT_NODE) {
+ out += node.textContent ?? '';
+ return;
+ }
+ if (!(node instanceof HTMLElement)) return;
+ if (
+ node.style.display === 'none' ||
+ node.style.visibility === 'hidden' ||
+ node.hasAttribute('hidden')
+ )
+ return;
+ for (const child of Array.from(node.childNodes)) walk(child);
+ };
+ for (const child of Array.from(root.childNodes)) walk(child);
+ return out;
+}
+
+/** The rendered attrs a type stamps, or null when the probe can't build one. */
+function renderedAttrs(spec: unknown): Record<string, unknown> | null {
+ if (!Array.isArray(spec)) return null;
+ const attrs = spec[1];
+ if (typeof attrs !== 'object' || attrs === null || Array.isArray(attrs)) return null;
+ return attrs as Record<string, unknown>;
+}
+
+const HIDING_STYLE = /display\s*:\s*none|visibility\s*:\s*hidden/i;
+
+describe('no editor mark or node hides its own content', () => {
+ const schema = getSchema(sharedExtensions);
+
+ test('no mark renders a hiding inline style', () => {
+ const offenders: string[] = [];
+ for (const markType of Object.values(schema.marks)) {
+ let attrs: Record<string, unknown> | null = null;
+ try {
+ attrs = renderedAttrs(markType.spec.toDOM?.(markType.create(), true));
+ } catch {
+ // A type whose renderer needs richer context than a bare instance
+ // can't be probed; it is not evidence of hiding either way.
+ continue;
+ }
+ const style = attrs?.style;
+ if (typeof style === 'string' && HIDING_STYLE.test(style)) offenders.push(markType.name);
+ }
+ expect(offenders).toEqual([]);
+ });
+
+ test('no node renders a hiding inline style', () => {
+ const offenders: string[] = [];
+ for (const nodeType of Object.values(schema.nodes)) {
+ let attrs: Record<string, unknown> | null = null;
+ try {
+ const node = nodeType.createAndFill();
+ if (!node) continue;
+ attrs = renderedAttrs(nodeType.spec.toDOM?.(node));
+ } catch {
+ continue;
+ }
+ const style = attrs?.style;
+ if (typeof style === 'string' && HIDING_STYLE.test(style)) offenders.push(nodeType.name);
+ }
+ expect(offenders).toEqual([]);
+ });
+});
+
+describe('promoters that keep their claimed run as text keep it visible', () => {
+ // Each entry is a literal a user can type as prose, plus the substring the
+ // editing surface must still show once the promoter has claimed it. Widget
+ // constructs (JSX components, math atoms) are deliberately absent: they
+ // replace the run with a rendered element rather than hiding text, which is
+ // a different question from this guard's.
+ const CASES = [
+ { promoter: 'comment (percent)', typed: 'before %%mid%% after', visible: 'mid' },
+ { promoter: 'comment (html)', typed: 'before <!-- mid --> after', visible: 'mid' },
+ { promoter: 'wiki link', typed: '[[note]]', visible: 'note' },
+ { promoter: 'autolink (scheme)', typed: 'see https://example.com now', visible: 'example.com' },
+ { promoter: 'autolink (www)', typed: 'see www.example.com now', visible: 'example.com' },
+ { promoter: 'autolink (email)', typed: 'mail [email protected] now', visible: '[email protected]' },
+ { promoter: 'autolink (angle)', typed: '<https://example.com>', visible: 'example.com' },
+ { promoter: 'tag', typed: 'see #roadmap for more', visible: 'roadmap' },
+ { promoter: 'highlight (html)', typed: 'a <mark>x</mark> b', visible: 'x' },
+ { promoter: 'highlight (equals)', typed: 'a ==hi== b', visible: 'hi' },
+ { promoter: 'inline code', typed: 'call `run` now', visible: 'run' },
+ { promoter: 'link', typed: '[label](https://example.com)', visible: 'label' },
+ { promoter: 'task item', typed: '- [ ] todo', visible: 'todo' },
+ ] as const;
+
+ for (const { promoter, typed, visible } of CASES) {
+ test(`${promoter}: "${typed}" still shows "${visible}" after re-derivation`, () => {
+ const { editor, container } = mount();
+ editor.view.dispatch(editor.state.tr.insertText(typed));
+
+ const bytes = mdManager.serialize(editor.getJSON());
+ const next: JSONContent = mdManager.parseWithFallback(stripFrontmatter(bytes).body);
+ editor.commands.setContent(next);
+
+ expect(visibleText(container)).toContain(visible);
+ });
+ }
+});
diff --git a/packages/app/tests/stress/comment-annotation-visibility.e2e.ts b/packages/app/tests/stress/comment-annotation-visibility.e2e.ts
new file mode 100644
index 000000000..61cb28a48
--- /dev/null
+++ b/packages/app/tests/stress/comment-annotation-visibility.e2e.ts
@@ -0,0 +1,88 @@
+/**
+ * Comment annotations stay legible in a real browser.
+ *
+ * The bug this guards was an inline `display: none` in the PM binding, which
+ * the schema sweep covers, and the fix moved legibility into `globals.css`,
+ * which `src/globals.comment-annotations.test.ts` covers as text. Neither tier
+ * reads a computed style: jsdom loads no stylesheet, and the CSS-as-data check
+ * cannot see cascade, specificity, an `@apply` that compiles to a hiding
+ * declaration, or an ancestor rule that hides the subtree.
+ *
+ * This is the only tier that runs the compiled stylesheet with real cascade,
+ * so it is where "the author can actually see their annotation" is decided.
+ *
+ * Requires: Playwright browsers installed. Server provided per-worker by the
+ * `workerServer` fixture in `_helpers/fixtures.ts`.
+ */
+
+import { expect, test, waitForActiveProviderSynced } from './_helpers';
+
+const SEED = [
+ 'Ordinary prose above.',
+ '',
+ 'A sentence with %%an inline percent note%% inside it.',
+ '',
+ 'A sentence with <!-- an inline html note --> inside it.',
+ '',
+ '<!-- a whole-paragraph html comment -->',
+ '',
+ '%%',
+ '',
+ 'A multi-line percent comment block.',
+ '',
+ '%%',
+ '',
+ 'Ordinary prose below.',
+].join('\n');
+
+test('promoted comment annotations render visibly, not hidden', async ({ page, api }) => {
+ const docName = `comment-visibility-${Date.now()}`;
+ await api.seedDocs([{ name: docName, markdown: SEED }]);
+ await page.goto(`/#/${docName}`);
+ await waitForActiveProviderSynced(page);
+
+ const editor = page.locator('.tiptap-editor .ProseMirror').first();
+ await expect(editor).toContainText('Ordinary prose above');
+
+ const inlineMark = page.locator('.tiptap-editor [data-comment-mark]').first();
+ const block = page.locator('.tiptap-editor [data-comment-block]').first();
+
+ // `toBeVisible` already fails on display/visibility/zero-size, which is the
+ // property under test stated in Playwright's own vocabulary.
+ await expect(inlineMark).toBeVisible();
+ await expect(block).toBeVisible();
+
+ // And the bodies are readable, not merely present in the layout.
+ await expect(inlineMark).toHaveText('an inline percent note');
+ await expect(block).toContainText('a whole-paragraph html comment');
+
+ // Read the computed style the compiled stylesheet actually produced, so a
+ // regression routed through cascade or `@apply hidden` fails here even
+ // though it leaves no literal declaration for the CSS-as-data tier to find.
+ for (const locator of [inlineMark, block]) {
+ const computed = await locator.evaluate((element) => {
+ const style = getComputedStyle(element);
+ return {
+ display: style.display,
+ visibility: style.visibility,
+ opacity: Number.parseFloat(style.opacity),
+ };
+ });
+ expect(computed.display).not.toBe('none');
+ expect(computed.visibility).not.toBe('hidden');
+ expect(computed.opacity).toBeGreaterThan(0);
+ }
+
+ // The delimiter glyphs are the affordance that names the construct, and they
+ // are pseudo-element content — invisible to `textContent`, so assert them
+ // where they live.
+ const inlineGlyph = await inlineMark.evaluate(
+ (element) => getComputedStyle(element, '::before').content,
+ );
+ expect(inlineGlyph).toContain('%%');
+
+ // The annotation must not be confusable with the blockquote that shares the
+ // muted-left-rail treatment a few rules away in the same stylesheet.
+ const blockBorder = await block.evaluate((element) => getComputedStyle(element).borderLeftStyle);
+ expect(blockBorder).toBe('dashed');
+});
diff --git a/packages/core/src/extensions/comment-block.ts b/packages/core/src/extensions/comment-block.ts
index 5ebcd9045..60c12b5eb 100644
--- a/packages/core/src/extensions/comment-block.ts
+++ b/packages/core/src/extensions/comment-block.ts
@@ -1,9 +1,18 @@
/**
- * commentBlock — multi-line literal authoring annotation. Hidden in
+ * commentBlock — multi-line literal authoring annotation. Dimmed in
* WYSIWYG, hidden on cross-app clipboard paste; survives in markdown
* source as `%%\n…\n%%` (Obsidian-style block) or `<!-- … -->` (HTML
- * comment, possibly multi-line). Rendered with `display: none` +
- * `data-clipboard-omit="true"` so authors edit it in source mode.
+ * comment, possibly multi-line). Rendered with `data-clipboard-omit="true"`
+ * and a `comment-block` class the app styles as dimmed annotation.
+ *
+ * Like the inline sister mark, this node does NOT hide its body in the
+ * editing surface: the promoter claims literal comment syntax wherever it
+ * appears, so hiding it makes typed text disappear from the surface it was
+ * typed into. Published output still hides comments — the mdast→hast
+ * renderer emits them as literal `<!-- … -->` HTML comments. Every surface
+ * that mounts this schema UNDER THE APP STYLESHEET, including the app's
+ * read-only TipTap views, shows the body dimmed; a consumer that supplies
+ * neither `.comment-block` styling nor its own gets undecorated prose.
*
* Sister to the inline `comment` PM mark (`comment-mark.ts`); the two
* cover the full hidden-content surface:
@@ -103,13 +112,12 @@ export const CommentBlock = Node.create({
'aside',
{
'data-comment-block': '',
- // Hidden in WYSIWYG via inline `display: none` (no app-side CSS
- // dependency). Inline style is decisive across cross-app
- // destination CSS. `data-clipboard-omit` makes the live-DOM
- // walker drop the subtree from outbound payloads.
+ // `data-clipboard-omit` makes the live-DOM walker drop the subtree
+ // from outbound payloads, and `comment-scrub.ts` derives the schema's
+ // omitted mark/node set by probing this very attribute — so omission
+ // is carried by the attribute, not by any styling.
'data-clipboard-omit': 'true',
class: 'comment-block',
- style: 'display: none;',
...HTMLAttributes,
},
0,
diff --git a/packages/core/src/extensions/comment-mark.ts b/packages/core/src/extensions/comment-mark.ts
index 420cdeec3..f73bcf026 100644
--- a/packages/core/src/extensions/comment-mark.ts
+++ b/packages/core/src/extensions/comment-mark.ts
@@ -1,14 +1,28 @@
/**
- * comment — literal authoring annotation. Hidden in WYSIWYG, hidden on
+ * comment — literal authoring annotation. Dimmed in WYSIWYG, hidden on
* cross-app clipboard paste; survives in markdown source as `%%text%%`
* (Obsidian-style) or `<!-- text -->` (HTML comment form).
*
* Both source forms parse into this mark on a text run via
- * `comment-promoter.ts`. The mark renders with `style="display: none"`
- * + `data-clipboard-omit="true"`, so authors who write a comment can't
- * see it in WYSIWYG and the clipboard walker drops it from outbound
- * payloads. Source mode (CodeMirror) shows the literal `%%…%%` /
- * `<!-- … -->` bytes — that's where authors create and edit comments.
+ * `comment-promoter.ts`. The mark renders with `data-clipboard-omit="true"`,
+ * so the clipboard walker drops it from outbound payloads, and with a
+ * `comment-mark` class the app styles as dimmed annotation. Source mode
+ * (CodeMirror) shows the literal `%%…%%` / `<!-- … -->` bytes.
+ *
+ * The mark deliberately does NOT hide the run in the editing surface. The
+ * promoter claims literal comment syntax wherever it appears, including
+ * prose a user typed without meaning it as a comment, so hiding the run
+ * makes typed text disappear from the surface it was typed into with no way
+ * to recover it there.
+ *
+ * Published output still hides comments — the mdast→hast renderer emits them
+ * as literal `<!-- … -->` HTML comments, which browsers do not display. The
+ * split is editor-schema versus rendered-markdown, not editable versus
+ * read-only: the app's read-only TipTap surfaces (the skill viewer, the
+ * rendered diff) mount this same schema under the same stylesheet, so they
+ * show comment bodies dimmed too. That is the intended reading for both —
+ * a diff that silently dropped an annotation change would be lying about
+ * the edit.
*
* Round-trip via `to-markdown-handlers.ts`'s `comment` handler: each
* source form preserves on save. The PM mark carries a `sourceForm`
@@ -49,8 +63,8 @@ export const CommentMark = Mark.create({
name: 'comment',
// Lower priority than structural marks (strong, emphasis) so the comment
// composes inside them rather than the other way round on parse. Matches
- // the priority math/highlight didn't need to set (those are atom/visible
- // shapes); for the hidden-text mark, the inside-bias produces the more
+ // the priority math/highlight didn't need to set (those are atom shapes);
+ // for an inline mark over ordinary text, the inside-bias produces the more
// intuitive nesting on rich-text edits.
priority: 10,
excludes: '',
@@ -85,15 +99,12 @@ export const CommentMark = Mark.create({
'span',
{
'data-comment-mark': '',
- // Hidden in WYSIWYG via inline `display: none` (no app-side CSS
- // dependency). Inline style is decisive — it wins regardless of
- // any cross-app destination CSS that might try to override the
- // class. `data-clipboard-omit` makes the live-DOM clipboard walker
- // drop the subtree from outbound payloads (no marker class
- // appears in cross-app paste).
+ // `data-clipboard-omit` makes the live-DOM clipboard walker drop the
+ // subtree from outbound payloads, and `comment-scrub.ts` derives the
+ // schema's omitted mark/node set by probing this very attribute — so
+ // omission is carried by the attribute, not by any styling.
'data-clipboard-omit': 'true',
class: 'comment-mark',
- style: 'display: none;',
...HTMLAttributes,
},
0,
diff --git a/packages/core/src/extensions/shared.ts b/packages/core/src/extensions/shared.ts
index fe73ffcee..9ced9f23e 100644
--- a/packages/core/src/extensions/shared.ts
+++ b/packages/core/src/extensions/shared.ts
@@ -153,19 +153,27 @@ export const sharedExtensions = [
// (`![alt](src)`) keep flowing through the `image` node above.
ImageReferenceFidelity,
Highlight,
+ // Legibility contract for the two comment descriptors below: neither
+ // self-hides any more, so a consumer that mounts this schema owns the
+ // `.comment-mark` / `.comment-block` styling that marks an annotation as
+ // one. Without it a comment renders as ordinary prose. The app supplies it
+ // in `globals.css`; nothing else in this workspace renders the schema to a
+ // DOM (the server never does, docs render through `mdastToHtml`).
+ //
// Custom comment mark — literal authoring annotation. Recognises
// `%%text%%` (Obsidian) and `<!-- text -->` (HTML comment) inline
- // forms. Renders with `display: none` + `data-clipboard-omit="true"`
- // so the text is invisible in WYSIWYG and dropped from cross-app
- // clipboard payloads. The PM mark carries `sourceForm` (`'percent' |
+ // forms. Renders with `data-clipboard-omit="true"` so the text is
+ // dropped from cross-app clipboard payloads, and dimmed rather than
+ // hidden in WYSIWYG so a promoted run never removes typed text from
+ // the editing surface. The PM mark carries `sourceForm` (`'percent' |
// 'html'`); PM-mediated saves preserve the form the author typed.
CommentMark,
// Block counterpart — block-level literal authoring annotation.
// Recognises `%%\n…\n%%` (Obsidian fence) and `<!-- … -->`
// (single-paragraph HTML comment, including multi-child paragraphs
- // whose body contains inline markdown). Renders with `display: none`
- // + `data-clipboard-omit="true"`. PM node carries `sourceForm` +
- // `sourceLayout` attributes; saves preserve byte-stable round-trip.
+ // whose body contains inline markdown). Same dimmed-not-hidden
+ // treatment and `data-clipboard-omit="true"`. PM node carries
+ // `sourceForm` + `sourceLayout`; saves preserve byte-stable round-trip.
CommentBlock,
// Footnote inline reference `[^id]` (atom) + block definition
// `[^id]: body` (block). remark-gfm parses into mdast `footnoteReference`