T-3DFJ-notes-adopts-markdown-ui

State: closed/done · Impact: high · Complexity: large

Goal

Notes is the reference integration for @sksizer/markdown-ui. This task replaces the hand-assembled editor, reader, find bar and hover preview in NotesNoteView.vue with one MdSurface, deletes the notes-local chrome the layer now owns, and moves the --obsmd-* bridge, editor, autocomplete and find CSS out of notes.css. Every later rollout wave copies this shape.

Today

Location	Role today
`solutions/determined/experiences/notes/package.json`	Depends on `@sksizer/obsidian-editor` and `@sksizer/obsidian-md` directly
`solutions/determined/experiences/notes/nuxt.config.ts`	Resolves `obsidian-md/theme.css` and `katex.min.css` via `createRequire`; transpiles both engines
`solutions/determined/experiences/notes/app/assets/notes.css`	801 lines: `--obsmd-` to `--d-` bridge, reading view, embeds, Bases, canvas, `.notes-editor` editor and autocomplete blocks, find highlights
`solutions/determined/experiences/notes/app/components/NotesNoteView.vue`	Mounts `NotesEditor`, `ObsidianMarkdown`, `NotesFindBar`, `NotesHoverPreview`; owns the mode switch (`notes-mode-switch`), `useNoteFind`, `useNoteComponents`
`solutions/determined/experiences/notes/app/components/NotesEditor.vue`	`useObsidianEditor` wrapper; the surface `MdSurface` replaces
`solutions/determined/experiences/notes/app/components/NotesFindBar.vue`	Find bar; generalised as `MdFindBar` by T-RJVA-md-ui-find-outline-hover-lifts
`solutions/determined/experiences/notes/app/components/NotesHoverPreview.vue`	Wikilink hover preview; generalised as `MdHoverPreview`
`solutions/determined/experiences/notes/app/components/NotesOutline.vue`	Outline rail content, mounted by `NotesAuxPane.vue`; generalised as `MdOutline`
`solutions/determined/experiences/notes/app/composables/useNoteFind.ts`	Find state over body, scroller and editor view; generalised as `useMarkdownFind`
`solutions/determined/experiences/notes/app/utils/noteFind.ts`	Pure find helpers, tested by `noteFind.test.ts`; lifted into the layer
`solutions/determined/experiences/notes/app/composables/useNoteComponents.ts`	`ThemedMermaidBlock` plus the `lang:base` and `obsidian-embed` component map
`solutions/determined/experiences/notes/app/composables/useEditorProvider.ts`	`EditorIndexProvider` over the vault stores
`solutions/determined/experiences/notes/app/plugins/register.ts`	Experience registration; comments cite `NotesEditor`
`solutions/determined/experiences/notes/app/composables/useNotesUi.ts`	`useNotesOutline`, `requestNotesFind`; comments cite the deleted components
`solutions/determined/experiences/notes/app/composables/useNoteScrollMemory.ts`	Consumes `useNotesOutline`; exports `NoteEditorView`
`solutions/determined/experiences/notes/app/components/NotesAuxPane.vue`	Mounts `NotesOutline` in the aux rail
`solutions/determined/tests/ui/notes/`	Playwright `notes` project; 13 specs use the `notes-find-*` and `notes-mode-switch` test ids
`scripts/guard-raw-palette.ts`	The `determined/experiences (rest)` ring holds `undeclared-token` at baseline 2 for `notes.css` (`--d-shadow-md`, `--d-bg-input`)

Proposed

Notes extends @sksizer/markdown-ui. NotesNoteView.vue mounts one MdSurface keyed by the note URL: v-model is the body (a writable computed over docs.doc and docs.edit), v-model:mode binds workspace.mode, frontmatter-panel="hidden" keeps NotesPropertiesPanel in place, and the provider is useNotesMarkdownProvider. register.ts registers:

MarkdownPlugin { id: 'notes', components: { 'lang:base': NotesEmbeddedBase, 'obsidian-embed': NotesEmbed } }

The seven notes-local chrome files are deleted. notes.css keeps only the reading view, embed, Bases, canvas and pane-rail rules. The e2e ids move to md-find-* and md-mode-toggle. The palette guard’s undeclared-token rule for the experiences ring becomes enforce().

Approach

package.json: add @sksizer/markdown-ui (workspace:*); remove @sksizer/obsidian-editor once grep -rn obsidian-editor app/ in the experience is empty. Keep @sksizer/obsidian-md (NotesEmbed.ts and NotesCanvasView.vue import ObsidianMarkdown directly).
nuxt.config.ts: extends: ['@sksizer/markdown-ui']; delete the obsidianTheme and katexTheme css entries and the two engine build.transpile entries.
notes.css: delete the --obsmd-*-override bridge block, the .notes-editor block, the autocomplete rules and the find-highlight rules. Replace --d-shadow-md and --d-bg-input with declared tokens on the way out. In scripts/guard-raw-palette.ts, set the determined/experiences (rest) ring’s undeclared-token to enforce().
Rename useEditorProvider.ts to useNotesMarkdownProvider.ts returning the layer’s MarkdownProvider: searchNotes, searchTags, resolveLink, assetUrl, saveAttachment, loadNote (from note-source.client.ts), onInvalidate = onAssetLoaded and onResolutionChanged combined.
register.ts: register the notes MarkdownPlugin through the layer’s useMarkdownPlugins; delete useNoteComponents.ts (its ThemedMermaidBlock is now MdMermaidBlock).
NotesNoteView.vue: replace NotesEditor, ObsidianMarkdown, NotesFindBar and NotesHoverPreview with MdSurface. Wire @save, @open-link, @tag-click, @task-toggle, @fold-toggle (to useNoteFoldMemory), @outline (to useNotesOutline) and @find-scroll. Feed useNoteScrollMemory from the exposed scroller and view; map requestNotesFind to v-model:findOpen.
NotesAuxPane.vue: mount MdOutline bound to useNotesOutline() instead of NotesOutline.
Delete NotesEditor.vue, NotesFindBar.vue, NotesHoverPreview.vue, NotesOutline.vue, useNoteFind.ts, noteFind.ts, noteFind.test.ts, useNoteComponents.ts. Fix the citing comments in useNotesUi.ts, useNoteScrollMemory.ts and register.ts.
Rename test ids in the 13 specs under solutions/determined/tests/ui/notes/ (advanced, capture-code-fence, capture-find, capture-fold-sections, capture-related, capture-table, editor, find, fold-sections, reading, refactor, scroll-memory, search-graph): notes-find-* to md-find-*, notes-mode-switch to md-mode-toggle. Keep notes-editor and notes-properties.
Root bun install; bun install --frozen-lockfile passes.
Verify: moon run product-workbench:check (confirms @determined/ui is registered once through shell and layer; fall back to shell-level extends if not), bun test app in the experience, bunx playwright test --project notes from solutions/determined, just ci-guards, moon run :check :test --affected. Manual: open a note, cycle read/live/source, toolbar bold, / menu, [[ picker, table Tab, mod+s; byte-diff an unedited save. nuxi analyze on solutions/determined/products/workbench.

Files to touch

Location	Kind	Change
`solutions/determined/experiences/notes/package.json`	modify	Add `@sksizer/markdown-ui`; drop `@sksizer/obsidian-editor`
`solutions/determined/experiences/notes/nuxt.config.ts`	modify	Extend the layer; drop theme/katex css and engine transpile entries
`solutions/determined/experiences/notes/app/assets/notes.css`	modify	Remove bridge, editor, autocomplete and find blocks; fix two undeclared tokens
`scripts/guard-raw-palette.ts`	modify	Experiences ring `undeclared-token` to `enforce()`
`solutions/determined/experiences/notes/app/composables/useEditorProvider.ts`	delete	Renamed to `useNotesMarkdownProvider.ts`
`solutions/determined/experiences/notes/app/composables/useNotesMarkdownProvider.ts`	new	`MarkdownProvider` with `loadNote` and `onInvalidate`
`solutions/determined/experiences/notes/app/plugins/register.ts`	modify	Register the notes `MarkdownPlugin`; fix `NotesEditor` comment
`solutions/determined/experiences/notes/app/components/NotesNoteView.vue`	modify	Mount `MdSurface`; drop the four replaced components and `useNoteFind`
`solutions/determined/experiences/notes/app/components/NotesAuxPane.vue`	modify	`NotesOutline` to `MdOutline`
`solutions/determined/experiences/notes/app/components/NotesEditor.vue`	delete	Replaced by `MdSurface`
`solutions/determined/experiences/notes/app/components/NotesFindBar.vue`	delete	Replaced by `MdFindBar`
`solutions/determined/experiences/notes/app/components/NotesHoverPreview.vue`	delete	Replaced by `MdHoverPreview`
`solutions/determined/experiences/notes/app/components/NotesOutline.vue`	delete	Replaced by `MdOutline`
`solutions/determined/experiences/notes/app/composables/useNoteFind.ts`	delete	Replaced by `useMarkdownFind`
`solutions/determined/experiences/notes/app/utils/noteFind.ts`	delete	Lifted into the layer
`solutions/determined/experiences/notes/app/utils/noteFind.test.ts`	delete	Moves with `noteFind.ts`
`solutions/determined/experiences/notes/app/composables/useNoteComponents.ts`	delete	Component map moves to the plugin; `ThemedMermaidBlock` is `MdMermaidBlock`
`solutions/determined/experiences/notes/app/composables/useNotesUi.ts`	modify	Comments cite `NotesFindBar`, `NotesEditor`, `useNoteFind`, `NotesOutline`
`solutions/determined/experiences/notes/app/composables/useNoteScrollMemory.ts`	modify	Comments cite `useNoteFind`; `NoteEditorView` sourced from the exposed view
`solutions/determined/tests/ui/notes/*.e2e.ts`	modify	Test id renames in the 13 specs listed in Approach step 9
`bun.lock`	modify	Root lockfile regen

Acceptance criteria

AC-1: NotesEditor.vue, NotesFindBar.vue, NotesHoverPreview.vue, NotesOutline.vue, useNoteFind.ts, noteFind.ts, noteFind.test.ts and useNoteComponents.ts no longer exist under solutions/determined/experiences/notes/app/, and a recursive grep for those six names over solutions/determined/experiences/notes returns nothing.
AC-2: NotesNoteView.vue mounts exactly one MdSurface and no ObsidianMarkdown.
AC-3: notes.css has no --obsmd-*-override declaration and no .notes-editor or .cm- selector; just ci-guards passes with the experiences ring at undeclared-token: enforce().
AC-4: notes nuxt.config.ts has no katex or theme.css entry and no engine transpile entry; moon run product-workbench:check passes.
AC-5: bunx playwright test --project notes passes, and grep -rn "notes-find-\|notes-mode-switch" solutions/determined returns nothing.
AC-6: Saving an unedited note leaves the file’s sha unchanged; editing one line yields a one-line git diff (recorded in the PR).
AC-7: nuxi analyze on solutions/determined/products/workbench shows the layer plus engines add under 150 KB gzip to the main chunk, with mermaid, KaTeX and Shiki as lazy chunks.
AC-8: Switching live, source and read on a 2 000-line note preserves cursor and scroll and completes in under 100 ms (Playwright trace from the playground harness or a performance.mark pair recorded in the PR).
AC-9: bun install --frozen-lockfile passes at the root.

Out of scope

The agent-pants experience migration (T-FQ5M-agent-pants-adopts-markdown-ui).
The chrome Playwright spec (T-M8PU-notes-chrome-e2e).
Building MdFindBar, MdOutline, MdHoverPreview (T-RJVA-md-ui-find-outline-hover-lifts); this task consumes them.
Replacing NotesPropertiesPanel with MdFrontmatterPanel; the store-bound panel stays.
NotesCanvasView.vue text-node rendering (T-TUIL-json-canvas-vue-async-renderer-seam).

Dependencies

Engine features the notes surface exposes: T-EXQ7-md-engine-command-catalogue, T-MNRO-md-engine-anchors, T-N58P-md-engine-slash-and-heading-completion, T-UYTR-md-engine-tables, T-JPB0-md-engine-math, T-VCFL-md-engine-mermaid, T-DSVW-md-engine-html-details, T-LNJA-md-engine-large-file-guard, T-0BFS-md-engine-attachments, T-E99V-md-engine-transclusion-expansion.
Chrome the surface composes: T-98EU-md-ui-toolbar-insert-frontmatter, T-8ZHI-md-ui-overlays-bubble-link-table, T-RJVA-md-ui-find-outline-hover-lifts, T-I630-md-ui-playground-e2e-perf.
D-4QGN-markdown-dialect-and-compatibility-profile: the engine stays body-only; frontmatter is split by the caller.
D-7VMX-markdown-ecosystem-strategy d.10: every migration deletes an implementation.
S-0010-design-language-consumption: no direct @nuxt/ui or Tailwind imports; --d-* tokens only.

Discovery context

Member of milestone M-931L; implements the wave-1 notes migration of D-K3EM-markdown-editor-chrome-and-plugin-environment.

Depends on

T-EXQ7-md-engine-command-catalogue, T-MNRO-md-engine-anchors, T-N58P-md-engine-slash-and-heading-completion, T-UYTR-md-engine-tables, T-JPB0-md-engine-math, T-VCFL-md-engine-mermaid, T-DSVW-md-engine-html-details, T-LNJA-md-engine-large-file-guard, T-0BFS-md-engine-attachments, T-E99V-md-engine-transclusion-expansion, T-98EU-md-ui-toolbar-insert-frontmatter, T-8ZHI-md-ui-overlays-bubble-link-table, T-RJVA-md-ui-find-outline-hover-lifts, T-I630-md-ui-playground-e2e-perf

← Back to Tasks