Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.mdxindex 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.jsonindex 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.tsindex 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.tsnew file mode 100644index 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.cssindex 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex fe73ffcee..9ced9f23e 100644--- a/packages/core/src/extensions/shared.ts+++ b/packages/core/src/extensions/shared.ts@@ -153,19 +153,27 @@ export const sharedExtensions = [// (``) 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`