From 98e01f28d4cbbeabfb16107580292bb5f781fab8 Mon Sep 17 00:00:00 2001
From: Einar <einari@me.com>
Date: Wed, 30 Sep 2026 20:00:15 +0200
Subject: [PATCH 1/4] Add MarkdownEditor with formatting, preview, completion
 and uploads

A controlled markdown editor published as the ./MarkdownEditor subpath:
one bordered box with a formatting toolbar and a round corner toggle
that swaps it to a host-rendered preview.

- Completion is generic: a MarkdownCompletion names a string or RegExp
  trigger and a suggest callback. The editor recognizes the trigger at
  the caret, debounces, aborts and drops stale answers, renders the list
  at the caret above any dialog, and inserts the picked suggestion.
- Pasted and dropped files upload through an uploadFile callback behind
  a placeholder that is resolved by value, or removed on failure.
- No markdown renderer ships: renderPreview hands rendering and
  sanitization to the host, so the subpath adds no dependencies.
- Stable parts, labels with English defaults, and a toolbar with one
  Tab stop and Control/Command shortcuts.
---
 Migrator/test/transform.test.js               |   4 +
 Source/MarkdownEditor/CaretPosition.ts        |  16 +
 Source/MarkdownEditor/MarkdownCompletion.ts   |  75 ++++
 .../MarkdownCompletionContext.ts              |  13 +
 .../MarkdownEditor/MarkdownCompletionMatch.ts |  24 ++
 Source/MarkdownEditor/MarkdownEditor.css      | 224 ++++++++++++
 Source/MarkdownEditor/MarkdownEditor.tsx      | 329 ++++++++++++++++++
 Source/MarkdownEditor/MarkdownEditorLabels.ts |  66 ++++
 Source/MarkdownEditor/MarkdownEditorMode.ts   |  14 +
 Source/MarkdownEditor/MarkdownEditorParts.ts  |  45 +++
 Source/MarkdownEditor/MarkdownFormat.ts       |  41 +++
 Source/MarkdownEditor/MarkdownLineBlock.ts    |  16 +
 Source/MarkdownEditor/MarkdownModeToggle.tsx  |  60 ++++
 Source/MarkdownEditor/MarkdownSuggestion.ts   |  24 ++
 .../MarkdownEditor/MarkdownSuggestionList.tsx | 124 +++++++
 Source/MarkdownEditor/MarkdownTextEdit.ts     |  16 +
 Source/MarkdownEditor/MarkdownToolbar.tsx     | 112 ++++++
 Source/MarkdownEditor/MarkdownWritingArea.tsx | 156 +++++++++
 Source/MarkdownEditor/README.md               |  40 +++
 Source/MarkdownEditor/applyMarkdownFormat.ts  |  59 ++++
 Source/MarkdownEditor/caretPositionIn.ts      |  71 ++++
 .../defaultMarkdownEditorLabels.ts            |  26 ++
 .../MarkdownEditor/defaultMarkdownFormats.ts  |  14 +
 Source/MarkdownEditor/filesIn.ts              |  13 +
 Source/MarkdownEditor/findCompletionMatch.ts  |  66 ++++
 .../given/an_editor_in_the_dom.ts             | 136 ++++++++
 .../when_completing_a_trigger.ts              |  83 +++++
 .../for_MarkdownEditor/when_formatting.ts     |  58 +++
 .../when_toggling_the_preview.ts              |  61 ++++
 .../when_uploading_a_pasted_file.ts           |  72 ++++
 .../when_inserting_a_link.ts                  |  31 ++
 .../when_toggling_a_code_block.ts             |  31 ++
 .../when_toggling_a_line_format.ts            |  47 +++
 .../when_toggling_an_inline_format.ts         |  47 +++
 .../for_findCompletionMatch/given.ts          |  15 +
 .../when_a_pattern_trigger_is_typed.ts        |  34 ++
 .../when_a_string_trigger_is_typed.ts         |  61 ++++
 .../when_several_triggers_match.ts            |  15 +
 .../when_toggling.ts                          |  12 +
 .../when_resolving_an_upload_placeholder.ts   |  28 ++
 .../when_replacing_a_range.ts                 |  14 +
 Source/MarkdownEditor/formatIcons.tsx         |  33 ++
 Source/MarkdownEditor/formatShortcuts.ts      |  11 +
 Source/MarkdownEditor/index.ts                |  16 +
 Source/MarkdownEditor/insertLink.ts           |  40 +++
 Source/MarkdownEditor/lineBlockAround.ts      |  24 ++
 .../MarkdownEditor/nextMarkdownEditorMode.ts  |  12 +
 Source/MarkdownEditor/replacePlaceholder.ts   |  17 +
 Source/MarkdownEditor/replaceRange.ts         |  22 ++
 Source/MarkdownEditor/toggleCodeBlock.ts      |  42 +++
 Source/MarkdownEditor/toggleInlineMarker.ts   |  46 +++
 Source/MarkdownEditor/toggleLinePrefix.ts     |  44 +++
 Source/MarkdownEditor/uploadPlaceholderFor.ts |  13 +
 .../MarkdownEditor/useMarkdownCompletion.ts   | 165 +++++++++
 Source/MarkdownEditor/useMarkdownUploads.ts   | 102 ++++++
 Source/api-surface.json                       |  20 +-
 Source/package.json                           |   5 +
 Source/scripts/export-inventory.json          |   2 +
 Source/scripts/generate-parts.mjs             |  42 +++
 Source/scripts/parts-inventory.json           |  20 ++
 Source/styles.css                             |   1 +
 Source/types/parts.ts                         |  12 +
 62 files changed, 3080 insertions(+), 2 deletions(-)
 create mode 100644 Source/MarkdownEditor/CaretPosition.ts
 create mode 100644 Source/MarkdownEditor/MarkdownCompletion.ts
 create mode 100644 Source/MarkdownEditor/MarkdownCompletionContext.ts
 create mode 100644 Source/MarkdownEditor/MarkdownCompletionMatch.ts
 create mode 100644 Source/MarkdownEditor/MarkdownEditor.css
 create mode 100644 Source/MarkdownEditor/MarkdownEditor.tsx
 create mode 100644 Source/MarkdownEditor/MarkdownEditorLabels.ts
 create mode 100644 Source/MarkdownEditor/MarkdownEditorMode.ts
 create mode 100644 Source/MarkdownEditor/MarkdownEditorParts.ts
 create mode 100644 Source/MarkdownEditor/MarkdownFormat.ts
 create mode 100644 Source/MarkdownEditor/MarkdownLineBlock.ts
 create mode 100644 Source/MarkdownEditor/MarkdownModeToggle.tsx
 create mode 100644 Source/MarkdownEditor/MarkdownSuggestion.ts
 create mode 100644 Source/MarkdownEditor/MarkdownSuggestionList.tsx
 create mode 100644 Source/MarkdownEditor/MarkdownTextEdit.ts
 create mode 100644 Source/MarkdownEditor/MarkdownToolbar.tsx
 create mode 100644 Source/MarkdownEditor/MarkdownWritingArea.tsx
 create mode 100644 Source/MarkdownEditor/README.md
 create mode 100644 Source/MarkdownEditor/applyMarkdownFormat.ts
 create mode 100644 Source/MarkdownEditor/caretPositionIn.ts
 create mode 100644 Source/MarkdownEditor/defaultMarkdownEditorLabels.ts
 create mode 100644 Source/MarkdownEditor/defaultMarkdownFormats.ts
 create mode 100644 Source/MarkdownEditor/filesIn.ts
 create mode 100644 Source/MarkdownEditor/findCompletionMatch.ts
 create mode 100644 Source/MarkdownEditor/for_MarkdownEditor/given/an_editor_in_the_dom.ts
 create mode 100644 Source/MarkdownEditor/for_MarkdownEditor/when_completing_a_trigger.ts
 create mode 100644 Source/MarkdownEditor/for_MarkdownEditor/when_formatting.ts
 create mode 100644 Source/MarkdownEditor/for_MarkdownEditor/when_toggling_the_preview.ts
 create mode 100644 Source/MarkdownEditor/for_MarkdownEditor/when_uploading_a_pasted_file.ts
 create mode 100644 Source/MarkdownEditor/for_applyMarkdownFormat/when_inserting_a_link.ts
 create mode 100644 Source/MarkdownEditor/for_applyMarkdownFormat/when_toggling_a_code_block.ts
 create mode 100644 Source/MarkdownEditor/for_applyMarkdownFormat/when_toggling_a_line_format.ts
 create mode 100644 Source/MarkdownEditor/for_applyMarkdownFormat/when_toggling_an_inline_format.ts
 create mode 100644 Source/MarkdownEditor/for_findCompletionMatch/given.ts
 create mode 100644 Source/MarkdownEditor/for_findCompletionMatch/when_a_pattern_trigger_is_typed.ts
 create mode 100644 Source/MarkdownEditor/for_findCompletionMatch/when_a_string_trigger_is_typed.ts
 create mode 100644 Source/MarkdownEditor/for_findCompletionMatch/when_several_triggers_match.ts
 create mode 100644 Source/MarkdownEditor/for_nextMarkdownEditorMode/when_toggling.ts
 create mode 100644 Source/MarkdownEditor/for_replacePlaceholder/when_resolving_an_upload_placeholder.ts
 create mode 100644 Source/MarkdownEditor/for_replaceRange/when_replacing_a_range.ts
 create mode 100644 Source/MarkdownEditor/formatIcons.tsx
 create mode 100644 Source/MarkdownEditor/formatShortcuts.ts
 create mode 100644 Source/MarkdownEditor/index.ts
 create mode 100644 Source/MarkdownEditor/insertLink.ts
 create mode 100644 Source/MarkdownEditor/lineBlockAround.ts
 create mode 100644 Source/MarkdownEditor/nextMarkdownEditorMode.ts
 create mode 100644 Source/MarkdownEditor/replacePlaceholder.ts
 create mode 100644 Source/MarkdownEditor/replaceRange.ts
 create mode 100644 Source/MarkdownEditor/toggleCodeBlock.ts
 create mode 100644 Source/MarkdownEditor/toggleInlineMarker.ts
 create mode 100644 Source/MarkdownEditor/toggleLinePrefix.ts
 create mode 100644 Source/MarkdownEditor/uploadPlaceholderFor.ts
 create mode 100644 Source/MarkdownEditor/useMarkdownCompletion.ts
 create mode 100644 Source/MarkdownEditor/useMarkdownUploads.ts

diff --git a/Migrator/test/transform.test.js b/Migrator/test/transform.test.js
index b81c5a2f..024c3cbe 100644
--- a/Migrator/test/transform.test.js
+++ b/Migrator/test/transform.test.js
@@ -176,6 +176,9 @@ describe('root namespace maps', () => {
             './CommandStepper',
             // Nested refinement of the historical CommandForm namespace.
             './CommandForm/fields',
+            // Added after Components 4.0 and never a Components 3 root namespace, so no Components 3
+            // import can name it and the codemod has nothing to rewrite.
+            './MarkdownEditor',
             // Per-area CSS entry points (feat/per-area-stylesheets): side-effect stylesheet
             // imports, not symbol imports, so the codemod has nothing to rewrite for them —
             // same as the pre-existing aggregate './styles' above.
@@ -192,6 +195,7 @@ describe('root namespace maps', () => {
             './Display/styles',
             './Dropdown/styles',
             './Filter/styles',
+            './MarkdownEditor/styles',
             './Notifications/styles',
             './ObjectContentEditor/styles',
             './ObjectNavigationalBar/styles',
diff --git a/Source/MarkdownEditor/CaretPosition.ts b/Source/MarkdownEditor/CaretPosition.ts
new file mode 100644
index 00000000..e7026101
--- /dev/null
+++ b/Source/MarkdownEditor/CaretPosition.ts
@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Where the caret of a writing area is on screen, in viewport coordinates.
+ */
+export interface CaretPosition {
+    /** The left edge of the caret. */
+    left: number;
+
+    /** The top of the line the caret is on. */
+    top: number;
+
+    /** The bottom of the line the caret is on. */
+    bottom: number;
+}
diff --git a/Source/MarkdownEditor/MarkdownCompletion.ts b/Source/MarkdownEditor/MarkdownCompletion.ts
new file mode 100644
index 00000000..7b794e2e
--- /dev/null
+++ b/Source/MarkdownEditor/MarkdownCompletion.ts
@@ -0,0 +1,75 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ReactNode } from 'react';
+import type { MarkdownCompletionContext } from './MarkdownCompletionContext';
+import type { MarkdownSuggestion } from './MarkdownSuggestion';
+
+/**
+ * Configures autocompletion for a {@link MarkdownEditor}: what starts it, and where the suggestions
+ * come from. The editor recognizes the trigger at the caret, asks {@link suggest} for suggestions,
+ * renders the list, and writes the picked suggestion's text over the trigger and what followed it.
+ *
+ * ```ts
+ * const issues: MarkdownCompletion = {
+ *     trigger: '#',
+ *     allowSpaces: true,
+ *     label: 'Issues',
+ *     suggest: async (query, { signal }) => (await searchIssues(query, signal)).map(issue => ({
+ *         id: issue.id,
+ *         insertText: `#${issue.number}`,
+ *         label: issue.title,
+ *         detail: `#${issue.number}`,
+ *     })),
+ * };
+ * ```
+ */
+export interface MarkdownCompletion {
+    /**
+     * What starts a completion.
+     *
+     * A string, such as `'#'` or `'@'`, starts one when it is typed at the start of a line or after
+     * whitespace; what follows it up to the caret, on the same line, is the query.
+     *
+     * A regular expression is matched against the current line up to the caret and starts a completion
+     * when its match ends at the caret. The whole match is what a picked suggestion replaces, and the
+     * query is the named group `query` when there is one, otherwise the first group, otherwise the
+     * whole match. Anchor it with `$` and use a lookbehind such as `(?<=^|\s)` for word boundaries.
+     */
+    trigger: string | RegExp;
+
+    /**
+     * Whether the query of a string trigger may contain spaces - searching by title rather than by a
+     * single word. Leading spaces are dropped from the query. Defaults to `false`.
+     */
+    allowSpaces?: boolean;
+
+    /** How many characters must follow the trigger before suggestions are asked for. Defaults to `0`. */
+    minimumQueryLength?: number;
+
+    /** How long typing must pause, in milliseconds, before suggestions are asked for. Defaults to `150`. */
+    debounce?: number;
+
+    /**
+     * Returns the suggestions for what has been typed after the trigger. May answer synchronously or
+     * with a promise; an answer for a query the person has already typed past is dropped, and so is a
+     * rejected one. An empty answer closes the list.
+     * @param query What has been typed after the trigger.
+     * @param context The {@link MarkdownCompletionContext} of the request.
+     * @returns The suggestions to offer, in the order to offer them.
+     */
+    suggest: (
+        query: string,
+        context: MarkdownCompletionContext,
+    ) => readonly MarkdownSuggestion[] | Promise<readonly MarkdownSuggestion[]>;
+
+    /** Accessible name of the suggestion list. Defaults to the editor's `suggestions` label. */
+    label?: string;
+
+    /**
+     * Renders the content of one suggestion in place of the default detail, label and annotation.
+     * @param suggestion The suggestion to render.
+     * @returns What to show for it.
+     */
+    renderSuggestion?: (suggestion: MarkdownSuggestion) => ReactNode;
+}
diff --git a/Source/MarkdownEditor/MarkdownCompletionContext.ts b/Source/MarkdownEditor/MarkdownCompletionContext.ts
new file mode 100644
index 00000000..f8b9a1c2
--- /dev/null
+++ b/Source/MarkdownEditor/MarkdownCompletionContext.ts
@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * What a {@link MarkdownCompletion} is told alongside the query when it is asked for suggestions.
+ */
+export interface MarkdownCompletionContext {
+    /**
+     * Aborted as soon as the answer is no longer wanted - the person typed on, moved the caret away or
+     * picked something. Pass it to `fetch` or check it before doing more work.
+     */
+    signal: AbortSignal;
+}
diff --git a/Source/MarkdownEditor/MarkdownCompletionMatch.ts b/Source/MarkdownEditor/MarkdownCompletionMatch.ts
new file mode 100644
index 00000000..803ff1df
--- /dev/null
+++ b/Source/MarkdownEditor/MarkdownCompletionMatch.ts
@@ -0,0 +1,24 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { MarkdownCompletion } from './MarkdownCompletion';
+
+/**
+ * A completion trigger found at the caret, and the query typed after it.
+ */
+export interface MarkdownCompletionMatch {
+    /** The completion whose trigger was found. */
+    completion: MarkdownCompletion;
+
+    /** The position of the matched completion in the list it was configured in. */
+    completionIndex: number;
+
+    /** Where the trigger starts - the start of what a picked suggestion replaces. */
+    start: number;
+
+    /** The caret - the end of what a picked suggestion replaces. */
+    end: number;
+
+    /** What has been typed after the trigger. */
+    query: string;
+}
diff --git a/Source/MarkdownEditor/MarkdownEditor.css b/Source/MarkdownEditor/MarkdownEditor.css
new file mode 100644
index 00000000..41abe67f
--- /dev/null
+++ b/Source/MarkdownEditor/MarkdownEditor.css
@@ -0,0 +1,224 @@
+/* Copyright (c) Cratis. All rights reserved. */
+/* Licensed under the MIT license. See LICENSE file in the project root for full license information. */
+
+.cratis-markdown-editor {
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    box-sizing: border-box;
+    width: 100%;
+    height: 100%;
+    overflow: hidden;
+    background: var(--cratis-surface-ground);
+    border: 1px solid var(--cratis-surface-border);
+    border-radius: var(--cratis-border-radius, 6px);
+    color: var(--cratis-text-color);
+}
+
+.cratis-markdown-editor:focus-within {
+    border-color: var(--cratis-primary-color);
+}
+
+.cratis-markdown-editor[data-invalid] {
+    border-color: var(--cratis-red-500);
+}
+
+.cratis-markdown-editor[data-disabled] {
+    opacity: var(--cratis-disabled-opacity, 0.6);
+}
+
+.cratis-markdown-editor__toolbar {
+    display: flex;
+    flex-wrap: wrap;
+    flex-shrink: 0;
+    align-items: center;
+    gap: 2px;
+    padding: 4px 6px;
+    background: var(--cratis-surface-card);
+    border-bottom: 1px solid var(--cratis-surface-border);
+}
+
+.cratis-markdown-editor--toggleable .cratis-markdown-editor__toolbar {
+    padding-right: 2.75rem;
+}
+
+.cratis-markdown-editor__separator {
+    width: 1px;
+    height: 1rem;
+    margin: 0 4px;
+    background: var(--cratis-surface-border);
+}
+
+.cratis-markdown-editor__format {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 1.75rem;
+    height: 1.75rem;
+    padding: 0;
+    color: var(--cratis-text-color-secondary);
+    background: transparent;
+    border: 0;
+    border-radius: 4px;
+    font-size: 0.8125rem;
+}
+
+.cratis-markdown-editor__format:hover:not(:disabled) {
+    color: var(--cratis-highlight-text-color);
+    background: var(--cratis-highlight-bg);
+    cursor: pointer;
+}
+
+.cratis-markdown-editor__format:focus-visible,
+.cratis-markdown-editor__toggle:focus-visible {
+    outline: none;
+    box-shadow: var(--cratis-focus-ring);
+}
+
+.cratis-markdown-editor__toggle {
+    position: absolute;
+    top: 0.3rem;
+    right: 0.35rem;
+    z-index: 1;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 2rem;
+    height: 2rem;
+    padding: 0;
+    color: var(--cratis-text-color-secondary);
+    background: var(--cratis-surface-card);
+    border: 1px solid var(--cratis-surface-border);
+    border-radius: 50%;
+    cursor: pointer;
+    font-size: 0.875rem;
+}
+
+.cratis-markdown-editor__toggle:hover {
+    color: var(--cratis-text-color);
+    background: var(--cratis-surface-hover);
+}
+
+.cratis-markdown-editor__toggle[data-pressed],
+.cratis-markdown-editor__toggle[data-pressed]:hover {
+    color: var(--cratis-primary-color-text);
+    background: var(--cratis-primary-color);
+    border-color: var(--cratis-primary-color);
+}
+
+.cratis-markdown-editor__body {
+    position: relative;
+    flex: 1 1 auto;
+    min-height: 4rem;
+}
+
+.cratis-markdown-editor__textarea,
+.cratis-markdown-editor__preview {
+    position: absolute;
+    inset: 0;
+    box-sizing: border-box;
+    width: 100%;
+    height: 100%;
+    margin: 0;
+    padding: 0.75rem;
+    overflow: auto;
+    color: var(--cratis-text-color);
+    background: transparent;
+}
+
+.cratis-markdown-editor__textarea,
+.cratis-markdown-editor__textarea:hover,
+.cratis-markdown-editor__textarea:focus {
+    border: 0;
+    border-radius: 0;
+    outline: none;
+    box-shadow: none;
+    resize: none;
+    font-family: var(--cratis-font-mono, ui-monospace, SFMono-Regular, Menlo, Consolas, monospace);
+    font-size: 0.8125rem;
+    line-height: 1.5;
+}
+
+.cratis-markdown-editor__textarea::placeholder,
+.cratis-markdown-editor__empty {
+    color: var(--cratis-text-color-secondary);
+}
+
+.cratis-markdown-editor__preview {
+    padding-right: 3rem;
+}
+
+.cratis-markdown-editor__empty {
+    margin: 0;
+    font-style: italic;
+}
+
+.cratis-markdown-editor__status {
+    flex-shrink: 0;
+    padding: 4px 8px;
+    color: var(--cratis-text-color-secondary);
+    background: var(--cratis-surface-card);
+    border-top: 1px solid var(--cratis-surface-border);
+    font-size: 0.75rem;
+}
+
+.cratis-markdown-editor__suggestions {
+    position: fixed;
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+    box-sizing: border-box;
+    width: min(32rem, calc(100vw - 1rem));
+    max-height: 18rem;
+    padding: 4px;
+    overflow-y: auto;
+    background: var(--cratis-surface-overlay);
+    border: 1px solid var(--cratis-surface-border);
+    border-radius: 6px;
+    box-shadow: var(--cratis-shadow-overlay);
+}
+
+.cratis-markdown-editor__suggestion {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 6px 10px;
+    color: var(--cratis-text-color);
+    border-radius: 4px;
+    cursor: pointer;
+    font-size: 0.8125rem;
+}
+
+.cratis-markdown-editor__suggestion[data-selected] {
+    color: var(--cratis-highlight-text-color);
+    background: var(--cratis-highlight-bg);
+}
+
+.cratis-markdown-editor__suggestion-detail {
+    flex-shrink: 0;
+    color: var(--cratis-text-color-secondary);
+    font-family: var(--cratis-font-mono, ui-monospace, SFMono-Regular, Menlo, Consolas, monospace);
+}
+
+.cratis-markdown-editor__suggestion-label {
+    flex: 1;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+.cratis-markdown-editor__suggestion-annotation {
+    flex-shrink: 0;
+    color: var(--cratis-text-color-secondary);
+    font-size: 0.6875rem;
+}
+
+@media (forced-colors: active) {
+    .cratis-markdown-editor__suggestion[data-selected],
+    .cratis-markdown-editor__toggle[data-pressed] {
+        forced-color-adjust: none;
+        color: HighlightText;
+        background: Highlight;
+    }
+}
diff --git a/Source/MarkdownEditor/MarkdownEditor.tsx b/Source/MarkdownEditor/MarkdownEditor.tsx
new file mode 100644
index 00000000..4e698bdd
--- /dev/null
+++ b/Source/MarkdownEditor/MarkdownEditor.tsx
@@ -0,0 +1,329 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useId, useLayoutEffect, useRef, useState, type ReactNode } from 'react';
+import { classNames } from '../ClassNames/classNames';
+import { unstable_useOverlayEnvironment } from '../renderer/RendererContext';
+import { OVERLAY_OFFSET, zIndexAboveDialog } from '../renderer/dialogStack';
+import { useNearestDialogZIndex } from '../renderer/DialogStackContext';
+import type { ExactPartKeys } from '../types/ExactPartKeys';
+import type { PartsOf } from '../types/parts';
+import type { CaretPosition } from './CaretPosition';
+import type { MarkdownCompletion } from './MarkdownCompletion';
+import type { MarkdownEditorLabels } from './MarkdownEditorLabels';
+import { MarkdownEditorMode } from './MarkdownEditorMode';
+import type { MarkdownEditorParts } from './MarkdownEditorParts';
+import type { MarkdownFormat } from './MarkdownFormat';
+import type { MarkdownTextEdit } from './MarkdownTextEdit';
+import { MarkdownModeToggle } from './MarkdownModeToggle';
+import { MarkdownSuggestionList } from './MarkdownSuggestionList';
+import { MarkdownToolbar } from './MarkdownToolbar';
+import { MarkdownWritingArea } from './MarkdownWritingArea';
+import { applyMarkdownFormat } from './applyMarkdownFormat';
+import { caretPositionIn } from './caretPositionIn';
+import { defaultMarkdownEditorLabels } from './defaultMarkdownEditorLabels';
+import { defaultMarkdownFormats } from './defaultMarkdownFormats';
+import { useMarkdownCompletion } from './useMarkdownCompletion';
+import { useMarkdownUploads } from './useMarkdownUploads';
+
+const markdownEditorPartsMatchManifest: ExactPartKeys<MarkdownEditorParts, PartsOf<'MarkdownEditor'>> = true;
+void markdownEditorPartsMatchManifest;
+
+/** The height the editor falls back to when its container leaves its height to its content. */
+const defaultHeight = 320;
+
+/** Props for {@link MarkdownEditor}. */
+export interface MarkdownEditorProps {
+    /** The markdown being edited. */
+    value: string;
+
+    /** Called with the markdown as it is written, formatted, completed or uploaded into. */
+    onChange: (value: string) => void;
+
+    /** Called when focus leaves the writing area. */
+    onBlur?: () => void;
+
+    /** Placeholder shown while the markdown is empty. */
+    placeholder?: string;
+
+    /**
+     * The height the editor takes when its container leaves its height to its content - a number of
+     * pixels or any CSS length. Inside a container with a height of its own the editor fills that
+     * instead. Defaults to 320 pixels.
+     */
+    height?: number | string;
+
+    /** The mode the editor opens in. Defaults to {@link MarkdownEditorMode.Write}. */
+    initialMode?: MarkdownEditorMode;
+
+    /** Focuses the writing area as the editor mounts. */
+    autoFocus?: boolean;
+
+    /** Disables writing, formatting and uploading. */
+    disabled?: boolean;
+
+    /** Shows the markdown without letting it be changed. */
+    readOnly?: boolean;
+
+    /** Marks the markdown as invalid, as a failed validation does. */
+    invalid?: boolean;
+
+    /**
+     * The formatting toolbar, as groups of formats separated from each other. Pass `false` for no
+     * toolbar. Defaults to text styles, blocks and links, and lists.
+     */
+    formats?: readonly (readonly MarkdownFormat[])[] | false;
+
+    /**
+     * Renders the preview of the markdown. The editor ships no markdown renderer - rendering, and what
+     * HTML is allowed through, belongs to the host - so the preview toggle only shows when this is given.
+     * @param markdown The markdown to render. Never empty: the editor shows its own empty text instead.
+     * @returns The rendered markdown.
+     */
+    renderPreview?: (markdown: string) => ReactNode;
+
+    /** Autocompletions offered while their trigger is typed, such as `#` for issues or `@` for people. */
+    completions?: readonly MarkdownCompletion[];
+
+    /**
+     * Uploads a file pasted or dropped into the writing area and returns the markdown that stands for
+     * it, such as an image or a link. Omit to leave pasting and dropping files to the browser.
+     * @param file The file to upload.
+     * @returns The markdown that replaces the file's placeholder.
+     */
+    uploadFile?: (file: File) => Promise<string>;
+
+    /**
+     * Told about a file whose upload failed. Its placeholder has already been taken out again.
+     * @param file The file that failed to upload.
+     * @param error What {@link uploadFile} rejected with.
+     */
+    onUploadFailed?: (file: File, error: unknown) => void;
+
+    /** Overrides for the editor's labels. Unset fields fall back to English. */
+    labels?: MarkdownEditorLabels;
+
+    /** The writing area's element id, for a `<label htmlFor>`. */
+    id?: string;
+
+    /** The writing area's accessible name. Defaults to the `editor` label unless `aria-labelledby` is given. */
+    'aria-label'?: string;
+
+    /** The id of the element naming the writing area. */
+    'aria-labelledby'?: string;
+
+    /** The id of the element describing the writing area, such as a validation message. */
+    'aria-describedby'?: string;
+
+    /** Extra class name on the editor's root. */
+    className?: string;
+
+    /** Pass-through attributes for the editor's stable parts. */
+    pt?: MarkdownEditorParts;
+}
+
+/**
+ * A markdown editor: one bordered box holding a formatting toolbar and the writing area, with a round
+ * toggle in its corner that swaps the whole box to the rendered preview. It fills the container it is
+ * given, recognizes configured completion triggers at the caret, and uploads pasted or dropped files
+ * through the host.
+ *
+ * Only one pane shows at a time: a markdown surface usually lives in a dialog or panel that is already
+ * narrow, and a side-by-side preview would halve the writing width for something wanted only now and
+ * then.
+ */
+export const MarkdownEditor = (props: MarkdownEditorProps) => {
+    const { value, onChange, height = defaultHeight, disabled = false, readOnly = false, invalid = false } = props;
+    const labels = { ...defaultMarkdownEditorLabels, ...props.labels };
+    const [mode, setMode] = useState(
+        props.renderPreview ? (props.initialMode ?? MarkdownEditorMode.Write) : MarkdownEditorMode.Write,
+    );
+    const [selection, setSelection] = useState({ start: value.length, end: value.length });
+    const [caret, setCaret] = useState<CaretPosition>();
+    const textareaRef = useRef<HTMLTextAreaElement>(null);
+    const pendingSelection = useRef<MarkdownTextEdit>(undefined);
+    const latest = useRef({ value, caret: value.length });
+    latest.current.value = value;
+    const baseId = useId();
+    const overlayEnvironment = unstable_useOverlayEnvironment();
+    const nearestDialogZIndex = useNearestDialogZIndex();
+
+    const editable = !disabled && !readOnly;
+    const completion = useMarkdownCompletion(
+        value,
+        selection.start,
+        selection.end,
+        editable && mode === MarkdownEditorMode.Write ? (props.completions ?? []) : [],
+    );
+
+    const applyEdit = (edit: MarkdownTextEdit) => {
+        latest.current = { value: edit.value, caret: edit.selectionEnd };
+        pendingSelection.current = edit;
+        setSelection({ start: edit.selectionStart, end: edit.selectionEnd });
+        onChange(edit.value);
+    };
+
+    const uploads = useMarkdownUploads({
+        uploadFile: editable ? props.uploadFile : undefined,
+        onUploadFailed: props.onUploadFailed,
+        currentValue: () => latest.current.value,
+        insertAtCaret: text => {
+            const { value: current, caret: at } = latest.current;
+            const position = Math.min(at, current.length);
+            const caretAfter = position + text.length;
+            applyEdit({
+                value: `${current.slice(0, position)}${text}${current.slice(position)}`,
+                selectionStart: caretAfter,
+                selectionEnd: caretAfter,
+            });
+        },
+        replaceValue: next => {
+            latest.current = { ...latest.current, value: next };
+            onChange(next);
+        },
+    });
+
+    // Restores the selection an edit asked for once the edited markdown is in the writing area.
+    useLayoutEffect(() => {
+        const pending = pendingSelection.current;
+        const textarea = textareaRef.current;
+        if (!pending || !textarea || textarea.value !== pending.value) return;
+        pendingSelection.current = undefined;
+        textarea.focus();
+        textarea.setSelectionRange(pending.selectionStart, pending.selectionEnd);
+    });
+
+    // Measured before paint, so the list never flashes at the caret's previous place while typing.
+    useLayoutEffect(() => {
+        const textarea = textareaRef.current;
+        setCaret(completion.isOpen && textarea ? caretPositionIn(textarea, selection.end) : undefined);
+    }, [completion.isOpen, value, selection.end]);
+
+    const applyFormat = (format: MarkdownFormat) => {
+        const textarea = textareaRef.current;
+        if (!textarea || !editable) return;
+        applyEdit(applyMarkdownFormat(value, textarea.selectionStart, textarea.selectionEnd, format));
+    };
+
+    const formats = props.formats === false ? [] : (props.formats ?? defaultMarkdownFormats);
+    const hasToolbar = formats.some(group => group.length > 0);
+    const canPreview = props.renderPreview !== undefined;
+    const suggestionsId = `${baseId}-suggestions`;
+    const optionId = (index: number) => `${baseId}-suggestion-${index}`;
+    const container = overlayEnvironment.getContainer();
+    const busy = uploads.uploading.length > 0;
+    const minHeight = typeof height === 'number' ? `${height}px` : height;
+
+    return (
+        <div
+            {...props.pt?.root}
+            className={classNames(
+                'cratis-markdown-editor',
+                canPreview && 'cratis-markdown-editor--toggleable',
+                props.className,
+                props.pt?.root?.className,
+            )}
+            style={{ minHeight, ...props.pt?.root?.style }}
+            data-cratis-part='root'
+            data-disabled={disabled || undefined}
+            data-invalid={invalid || undefined}
+            data-readonly={readOnly || undefined}
+            data-busy={busy || undefined}
+        >
+            {canPreview && (
+                <MarkdownModeToggle
+                    mode={mode}
+                    onModeChange={setMode}
+                    showPreviewLabel={labels.showPreview}
+                    showMarkdownLabel={labels.showMarkdown}
+                    parts={props.pt?.toggle}
+                />
+            )}
+            {mode === MarkdownEditorMode.Write && hasToolbar && (
+                <MarkdownToolbar
+                    formats={formats}
+                    labels={labels}
+                    disabled={!editable}
+                    onFormat={applyFormat}
+                    parts={props.pt}
+                />
+            )}
+            <div className='cratis-markdown-editor__body'>
+                {mode === MarkdownEditorMode.Preview && props.renderPreview ? (
+                    <div
+                        {...props.pt?.preview}
+                        className={classNames('cratis-markdown-editor__preview', props.pt?.preview?.className)}
+                        data-cratis-part='preview'
+                    >
+                        {value.trim().length > 0 ? (
+                            props.renderPreview(value)
+                        ) : (
+                            <p className='cratis-markdown-editor__empty'>{labels.emptyPreview}</p>
+                        )}
+                    </div>
+                ) : (
+                    <MarkdownWritingArea
+                        value={value}
+                        onChange={onChange}
+                        onBlur={props.onBlur}
+                        placeholder={props.placeholder}
+                        autoFocus={props.autoFocus}
+                        disabled={disabled}
+                        readOnly={readOnly}
+                        invalid={invalid}
+                        id={props.id}
+                        aria-label={props['aria-label']}
+                        aria-labelledby={props['aria-labelledby']}
+                        aria-describedby={props['aria-describedby']}
+                        parts={props.pt?.textarea}
+                        textareaRef={textareaRef}
+                        labels={labels}
+                        completion={completion}
+                        uploads={uploads}
+                        suggestionsId={suggestionsId}
+                        activeOptionId={completion.isOpen ? optionId(completion.activeIndex) : undefined}
+                        onSelectionChange={(start, end) => {
+                            latest.current = { ...latest.current, caret: end };
+                            setSelection({ start, end });
+                        }}
+                        onEdit={applyEdit}
+                        onFormat={applyFormat}
+                    />
+                )}
+            </div>
+            {busy && (
+                <div
+                    {...props.pt?.status}
+                    role='status'
+                    className={classNames('cratis-markdown-editor__status', props.pt?.status?.className)}
+                    data-cratis-part='status'
+                >
+                    {labels.uploading(uploads.uploading)}
+                </div>
+            )}
+            {completion.isOpen && caret && container && (
+                <MarkdownSuggestionList
+                    id={suggestionsId}
+                    optionId={optionId}
+                    label={completion.match?.completion.label ?? labels.suggestions}
+                    suggestions={completion.suggestions}
+                    activeIndex={completion.activeIndex}
+                    caret={caret}
+                    zIndex={
+                        nearestDialogZIndex === null
+                            ? 'var(--cratis-z-index-overlay)'
+                            : zIndexAboveDialog(nearestDialogZIndex, OVERLAY_OFFSET)
+                    }
+                    container={container}
+                    onHighlight={completion.highlight}
+                    onChoose={suggestion => {
+                        const edit = completion.choose(suggestion);
+                        if (edit) applyEdit(edit);
+                    }}
+                    renderSuggestion={completion.match?.completion.renderSuggestion}
+                    parts={props.pt}
+                />
+            )}
+        </div>
+    );
+};
diff --git a/Source/MarkdownEditor/MarkdownEditorLabels.ts b/Source/MarkdownEditor/MarkdownEditorLabels.ts
new file mode 100644
index 00000000..c5d07901
--- /dev/null
+++ b/Source/MarkdownEditor/MarkdownEditorLabels.ts
@@ -0,0 +1,66 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Overrides for every label a {@link MarkdownEditor} renders or announces. Any field left unset falls
+ * back to a literal English default, so a host with its own translations passes them here.
+ */
+export interface MarkdownEditorLabels {
+    /** Accessible name of the writing area when the host gives it none. Defaults to `'Markdown'`. */
+    editor?: string;
+
+    /** Accessible name of the formatting toolbar. Defaults to `'Formatting'`. */
+    toolbar?: string;
+
+    /** The bold format. Defaults to `'Bold'`. */
+    bold?: string;
+
+    /** The italic format. Defaults to `'Italic'`. */
+    italic?: string;
+
+    /** The strikethrough format. Defaults to `'Strikethrough'`. */
+    strikethrough?: string;
+
+    /** The heading format. Defaults to `'Heading'`. */
+    heading?: string;
+
+    /** The quote format. Defaults to `'Quote'`. */
+    quote?: string;
+
+    /** The inline code format. Defaults to `'Code'`. */
+    code?: string;
+
+    /** The code block format. Defaults to `'Code block'`. */
+    codeBlock?: string;
+
+    /** The link format. Defaults to `'Link'`. */
+    link?: string;
+
+    /** The bulleted list format. Defaults to `'Bulleted list'`. */
+    bulletList?: string;
+
+    /** The numbered list format. Defaults to `'Numbered list'`. */
+    numberedList?: string;
+
+    /** The task list format. Defaults to `'Task list'`. */
+    taskList?: string;
+
+    /** What the mode toggle says while the markdown is showing. Defaults to `'Show preview'`. */
+    showPreview?: string;
+
+    /** What the mode toggle says while the preview is showing. Defaults to `'Show markdown'`. */
+    showMarkdown?: string;
+
+    /** Shown in the preview when there is no markdown. Defaults to `'Nothing to preview'`. */
+    emptyPreview?: string;
+
+    /** Accessible name of a suggestion list whose completion names none. Defaults to `'Suggestions'`. */
+    suggestions?: string;
+
+    /**
+     * Announces the files uploading. Defaults to `Uploading <names>…`.
+     * @param fileNames The names of the files uploading, in the order they were added.
+     * @returns The text to show.
+     */
+    uploading?: (fileNames: readonly string[]) => string;
+}
diff --git a/Source/MarkdownEditor/MarkdownEditorMode.ts b/Source/MarkdownEditor/MarkdownEditorMode.ts
new file mode 100644
index 00000000..ad5cd1ce
--- /dev/null
+++ b/Source/MarkdownEditor/MarkdownEditorMode.ts
@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * What a {@link MarkdownEditor} is showing. Only one pane is on screen at a time: the markdown being
+ * written, or the rendered preview of it.
+ */
+export enum MarkdownEditorMode {
+    /** The raw markdown, with the formatting toolbar. */
+    Write = 'write',
+
+    /** The markdown rendered by the host's preview renderer. */
+    Preview = 'preview',
+}
diff --git a/Source/MarkdownEditor/MarkdownEditorParts.ts b/Source/MarkdownEditor/MarkdownEditorParts.ts
new file mode 100644
index 00000000..715852d1
--- /dev/null
+++ b/Source/MarkdownEditor/MarkdownEditorParts.ts
@@ -0,0 +1,45 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { HTMLAttributes, TextareaHTMLAttributes } from 'react';
+
+/** Attributes passed through to one part of a {@link MarkdownEditor}, including `data-*` attributes. */
+export type MarkdownEditorPartAttributes<TElement> = HTMLAttributes<TElement> & {
+    [attribute: `data-${string}`]: string | number | boolean | undefined;
+};
+
+/**
+ * Stable Cratis-owned parts for styling a {@link MarkdownEditor}. Each is marked with a matching
+ * `data-cratis-part` attribute, and what is passed here is spread onto that element - the editor's own
+ * value, selection and event wiring always win.
+ */
+export interface MarkdownEditorParts {
+    /** The editor's single bordered box. Carries `data-disabled`, `data-invalid`, `data-readonly` and `data-busy`. */
+    root?: MarkdownEditorPartAttributes<HTMLDivElement>;
+
+    /** The formatting toolbar. */
+    toolbar?: MarkdownEditorPartAttributes<HTMLDivElement>;
+
+    /** Every formatting button in the toolbar. Carries `data-disabled`. */
+    format?: MarkdownEditorPartAttributes<HTMLButtonElement>;
+
+    /** The round button that swaps between the markdown and the preview. Carries `data-pressed`. */
+    toggle?: MarkdownEditorPartAttributes<HTMLButtonElement>;
+
+    /** The writing area. Carries `data-disabled`, `data-invalid` and `data-readonly`. */
+    textarea?: Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'value' | 'defaultValue' | 'onChange'> & {
+        [attribute: `data-${string}`]: string | number | boolean | undefined;
+    };
+
+    /** The rendered preview pane. */
+    preview?: MarkdownEditorPartAttributes<HTMLDivElement>;
+
+    /** The status line announcing uploads in progress. */
+    status?: MarkdownEditorPartAttributes<HTMLDivElement>;
+
+    /** The suggestion list that opens at the caret while a completion is typed. */
+    suggestions?: MarkdownEditorPartAttributes<HTMLDivElement>;
+
+    /** Every entry in the suggestion list. Carries `data-selected` on the highlighted one. */
+    suggestion?: MarkdownEditorPartAttributes<HTMLDivElement>;
+}
diff --git a/Source/MarkdownEditor/MarkdownFormat.ts b/Source/MarkdownEditor/MarkdownFormat.ts
new file mode 100644
index 00000000..21fcdb28
--- /dev/null
+++ b/Source/MarkdownEditor/MarkdownFormat.ts
@@ -0,0 +1,41 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * A formatting action offered by the {@link MarkdownEditor}'s toolbar. Each one edits the markdown
+ * around the current selection, and applying it to text that already carries it takes it off again.
+ */
+export enum MarkdownFormat {
+    /** Wraps the selection in `**`. */
+    Bold = 'bold',
+
+    /** Wraps the selection in `_`. */
+    Italic = 'italic',
+
+    /** Wraps the selection in `~~`. */
+    Strikethrough = 'strikethrough',
+
+    /** Prefixes the selected lines with `## `. */
+    Heading = 'heading',
+
+    /** Prefixes the selected lines with `> `. */
+    Quote = 'quote',
+
+    /** Wraps the selection in backticks. */
+    Code = 'code',
+
+    /** Fences the selected lines in a code block. */
+    CodeBlock = 'codeBlock',
+
+    /** Turns the selection into a link and selects the address to type over. */
+    Link = 'link',
+
+    /** Prefixes the selected lines with `- `. */
+    BulletList = 'bulletList',
+
+    /** Numbers the selected lines `1. `, `2. `, … */
+    NumberedList = 'numberedList',
+
+    /** Prefixes the selected lines with `- [ ] `. */
+    TaskList = 'taskList',
+}
diff --git a/Source/MarkdownEditor/MarkdownLineBlock.ts b/Source/MarkdownEditor/MarkdownLineBlock.ts
new file mode 100644
index 00000000..cec1fba8
--- /dev/null
+++ b/Source/MarkdownEditor/MarkdownLineBlock.ts
@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The whole lines a selection touches - the unit that line formats such as lists and quotes apply to.
+ */
+export interface MarkdownLineBlock {
+    /** Where the first touched line starts. */
+    start: number;
+
+    /** Where the last touched line ends, before its line break. */
+    end: number;
+
+    /** The touched lines, without their line breaks. */
+    lines: string[];
+}
diff --git a/Source/MarkdownEditor/MarkdownModeToggle.tsx b/Source/MarkdownEditor/MarkdownModeToggle.tsx
new file mode 100644
index 00000000..750e058c
--- /dev/null
+++ b/Source/MarkdownEditor/MarkdownModeToggle.tsx
@@ -0,0 +1,60 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { FaEye, FaPen } from 'react-icons/fa6';
+import { classNames } from '../ClassNames/classNames';
+import { MarkdownEditorMode } from './MarkdownEditorMode';
+import type { MarkdownEditorPartAttributes } from './MarkdownEditorParts';
+import { nextMarkdownEditorMode } from './nextMarkdownEditorMode';
+
+/** Props for {@link MarkdownModeToggle}. */
+export interface MarkdownModeToggleProps {
+    /** The mode being shown. */
+    mode: MarkdownEditorMode;
+
+    /** Called with the mode to show next. */
+    onModeChange: (mode: MarkdownEditorMode) => void;
+
+    /** What the button says while the markdown is showing. */
+    showPreviewLabel: string;
+
+    /** What the button says while the preview is showing. */
+    showMarkdownLabel: string;
+
+    /** Pass-through attributes for the button. */
+    parts?: MarkdownEditorPartAttributes<HTMLButtonElement>;
+}
+
+/**
+ * The round button in the editor's top-right corner that swaps between the markdown and its preview.
+ * A toggle rather than two buttons: `aria-pressed` says whether the preview is showing and the label
+ * names what pressing it does, so assistive technology announces both the state and the action.
+ */
+export const MarkdownModeToggle = ({
+    mode,
+    onModeChange,
+    showPreviewLabel,
+    showMarkdownLabel,
+    parts,
+}: MarkdownModeToggleProps) => {
+    const previewing = mode === MarkdownEditorMode.Preview;
+    const label = previewing ? showMarkdownLabel : showPreviewLabel;
+
+    return (
+        <button
+            {...parts}
+            type='button'
+            className={classNames('cratis-markdown-editor__toggle', parts?.className)}
+            data-cratis-part='toggle'
+            data-pressed={previewing || undefined}
+            aria-pressed={previewing}
+            aria-label={label}
+            title={label}
+            onClick={() => onModeChange(nextMarkdownEditorMode(mode))}
+        >
+            <span className='cratis-markdown-editor__toggle-icon' aria-hidden='true'>
+                {previewing ? <FaPen /> : <FaEye />}
+            </span>
+        </button>
+    );
+};
diff --git a/Source/MarkdownEditor/MarkdownSuggestion.ts b/Source/MarkdownEditor/MarkdownSuggestion.ts
new file mode 100644
index 00000000..4bea7cf3
--- /dev/null
+++ b/Source/MarkdownEditor/MarkdownSuggestion.ts
@@ -0,0 +1,24 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * One entry in the list a {@link MarkdownCompletion} offers while its trigger is being typed. The host
+ * maps whatever it looks up - an issue, a person, a document - into this shape; the editor renders it
+ * and writes {@link insertText} into the markdown when it is picked.
+ */
+export interface MarkdownSuggestion {
+    /** Identifies the suggestion within one list. Used as its key and in its element id. */
+    id: string;
+
+    /** The text that replaces the trigger and everything typed after it when the suggestion is picked. */
+    insertText: string;
+
+    /** The main text of the entry, such as a title or a name. */
+    label: string;
+
+    /** Secondary text shown ahead of the label in a monospace face, such as `owner/repository#12`. */
+    detail?: string;
+
+    /** A short annotation shown after the label, such as the kind of thing suggested. */
+    annotation?: string;
+}
diff --git a/Source/MarkdownEditor/MarkdownSuggestionList.tsx b/Source/MarkdownEditor/MarkdownSuggestionList.tsx
new file mode 100644
index 00000000..c05ce91b
--- /dev/null
+++ b/Source/MarkdownEditor/MarkdownSuggestionList.tsx
@@ -0,0 +1,124 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { CSSProperties, ReactNode } from 'react';
+import { createPortal } from 'react-dom';
+import { classNames } from '../ClassNames/classNames';
+import type { CaretPosition } from './CaretPosition';
+import type { MarkdownEditorParts } from './MarkdownEditorParts';
+import type { MarkdownSuggestion } from './MarkdownSuggestion';
+
+/** Room kept below the caret before the list opens above it instead. */
+const roomBelow = 240;
+
+/** Props for {@link MarkdownSuggestionList}. */
+export interface MarkdownSuggestionListProps {
+    /** The list's element id, which the writing area points at. */
+    id: string;
+
+    /** Builds the element id of the suggestion at an index, which the writing area points at when it is highlighted. */
+    optionId: (index: number) => string;
+
+    /** The list's accessible name. */
+    label: string;
+
+    /** The suggestions to show. */
+    suggestions: readonly MarkdownSuggestion[];
+
+    /** The index of the highlighted suggestion. */
+    activeIndex: number;
+
+    /** Where the caret is. */
+    caret: CaretPosition;
+
+    /** The stacking order to open at - above any dialog the editor sits in. */
+    zIndex: string;
+
+    /** Where to portal the list to. */
+    container: HTMLElement;
+
+    /** Highlights a suggestion as the pointer moves onto it. */
+    onHighlight: (index: number) => void;
+
+    /** Picks a suggestion. */
+    onChoose: (suggestion: MarkdownSuggestion) => void;
+
+    /** Renders the content of a suggestion in place of the default. */
+    renderSuggestion?: (suggestion: MarkdownSuggestion) => ReactNode;
+
+    /** Pass-through attributes for the list and its entries. */
+    parts?: Pick<MarkdownEditorParts, 'suggestions' | 'suggestion'>;
+}
+
+const DefaultSuggestion = ({ suggestion }: { suggestion: MarkdownSuggestion }) => (
+    <>
+        {suggestion.detail && <span className='cratis-markdown-editor__suggestion-detail'>{suggestion.detail}</span>}
+        <span className='cratis-markdown-editor__suggestion-label'>{suggestion.label}</span>
+        {suggestion.annotation && (
+            <span className='cratis-markdown-editor__suggestion-annotation'>{suggestion.annotation}</span>
+        )}
+    </>
+);
+
+/**
+ * The list of suggestions that opens at the caret while a completion is typed.
+ *
+ * Portaled out of the editor so no scrolling or clipping ancestor cuts it off, and marked as a top
+ * layer so a modal dialog around the editor neither hides it from assistive technology nor closes when
+ * it is clicked. Focus never leaves the writing area: the list is driven through
+ * `aria-activedescendant`, and pressing an entry does not take focus.
+ */
+export const MarkdownSuggestionList = ({
+    id,
+    optionId,
+    label,
+    suggestions,
+    activeIndex,
+    caret,
+    zIndex,
+    container,
+    onHighlight,
+    onChoose,
+    renderSuggestion,
+    parts,
+}: MarkdownSuggestionListProps) => {
+    const opensAbove = caret.bottom + roomBelow > window.innerHeight && caret.top > window.innerHeight - caret.bottom;
+    const style: CSSProperties = {
+        ...parts?.suggestions?.style,
+        zIndex,
+        left: Math.max(0, Math.min(caret.left, window.innerWidth - 16)),
+        ...(opensAbove ? { bottom: window.innerHeight - caret.top + 4 } : { top: caret.bottom + 4 }),
+    };
+
+    return createPortal(
+        <div
+            {...parts?.suggestions}
+            id={id}
+            role='listbox'
+            aria-label={label}
+            className={classNames('cratis-markdown-editor__suggestions', parts?.suggestions?.className)}
+            data-cratis-part='suggestions'
+            data-react-aria-top-layer='true'
+            style={style}
+        >
+            {suggestions.map((suggestion, index) => (
+                <div
+                    key={suggestion.id}
+                    {...parts?.suggestion}
+                    id={optionId(index)}
+                    role='option'
+                    aria-selected={index === activeIndex}
+                    className={classNames('cratis-markdown-editor__suggestion', parts?.suggestion?.className)}
+                    data-cratis-part='suggestion'
+                    data-selected={index === activeIndex || undefined}
+                    onMouseDown={event => event.preventDefault()}
+                    onMouseEnter={() => onHighlight(index)}
+                    onClick={() => onChoose(suggestion)}
+                >
+                    {renderSuggestion ? renderSuggestion(suggestion) : <DefaultSuggestion suggestion={suggestion} />}
+                </div>
+            ))}
+        </div>,
+        container,
+    );
+};
diff --git a/Source/MarkdownEditor/MarkdownTextEdit.ts b/Source/MarkdownEditor/MarkdownTextEdit.ts
new file mode 100644
index 00000000..2721ace3
--- /dev/null
+++ b/Source/MarkdownEditor/MarkdownTextEdit.ts
@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Markdown after an edit, together with the selection the writing area should show afterwards.
+ */
+export interface MarkdownTextEdit {
+    /** The markdown after the edit. */
+    value: string;
+
+    /** Where the selection starts after the edit. */
+    selectionStart: number;
+
+    /** Where the selection ends after the edit. Equal to {@link selectionStart} for a plain caret. */
+    selectionEnd: number;
+}
diff --git a/Source/MarkdownEditor/MarkdownToolbar.tsx b/Source/MarkdownEditor/MarkdownToolbar.tsx
new file mode 100644
index 00000000..0fd0a335
--- /dev/null
+++ b/Source/MarkdownEditor/MarkdownToolbar.tsx
@@ -0,0 +1,112 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Fragment, useRef, useState, type KeyboardEvent } from 'react';
+import { classNames } from '../ClassNames/classNames';
+import type { MarkdownFormat } from './MarkdownFormat';
+import type { MarkdownEditorLabels } from './MarkdownEditorLabels';
+import type { MarkdownEditorParts } from './MarkdownEditorParts';
+import { formatIcons } from './formatIcons';
+import { formatShortcuts } from './formatShortcuts';
+
+/** Props for {@link MarkdownToolbar}. */
+export interface MarkdownToolbarProps {
+    /** The formats to offer, in groups separated from each other. */
+    formats: readonly (readonly MarkdownFormat[])[];
+
+    /** The resolved labels. */
+    labels: Required<MarkdownEditorLabels>;
+
+    /** Whether the formats can be applied. */
+    disabled: boolean;
+
+    /** Applies a format to the writing area's selection. */
+    onFormat: (format: MarkdownFormat) => void;
+
+    /** Pass-through attributes for the toolbar and its buttons. */
+    parts?: Pick<MarkdownEditorParts, 'toolbar' | 'format'>;
+}
+
+const shortcutFor = (format: MarkdownFormat) => {
+    for (const [letter, shortcut] of formatShortcuts) {
+        if (shortcut === format) return `Control+${letter.toUpperCase()} Meta+${letter.toUpperCase()}`;
+    }
+    return undefined;
+};
+
+const navigationKeys = new Set(['ArrowLeft', 'ArrowRight', 'Home', 'End']);
+
+/**
+ * The formatting toolbar above the writing area. One Tab stop: the arrow keys, Home and End move
+ * between the buttons, as the ARIA toolbar pattern describes. A button press never takes focus from
+ * the writing area, so the selection it formats stays where it was.
+ */
+export const MarkdownToolbar = ({ formats, labels, disabled, onFormat, parts }: MarkdownToolbarProps) => {
+    const flat = formats.flat();
+    const [focusIndex, setFocusIndex] = useState(0);
+    const buttons = useRef<(HTMLButtonElement | null)[]>([]);
+    const current = Math.min(focusIndex, Math.max(flat.length - 1, 0));
+
+    const onKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+        parts?.toolbar?.onKeyDown?.(event);
+        if (!navigationKeys.has(event.key) || flat.length === 0) return;
+        event.preventDefault();
+        const next =
+            event.key === 'Home'
+                ? 0
+                : event.key === 'End'
+                  ? flat.length - 1
+                  : (current + (event.key === 'ArrowRight' ? 1 : -1) + flat.length) % flat.length;
+        setFocusIndex(next);
+        buttons.current[next]?.focus();
+    };
+
+    const offsets = formats.map((_, groupIndex) =>
+        formats.slice(0, groupIndex).reduce((total, group) => total + group.length, 0),
+    );
+
+    return (
+        <div
+            {...parts?.toolbar}
+            role='toolbar'
+            aria-label={labels.toolbar}
+            className={classNames('cratis-markdown-editor__toolbar', parts?.toolbar?.className)}
+            data-cratis-part='toolbar'
+            onKeyDown={onKeyDown}
+        >
+            {formats.map((group, groupIndex) => (
+                <Fragment key={group.join('-')}>
+                    {groupIndex > 0 && <span className='cratis-markdown-editor__separator' aria-hidden='true' />}
+                    {group.map((format, formatIndex) => {
+                        const index = offsets[groupIndex] + formatIndex;
+                        return (
+                            <button
+                                key={format}
+                                {...parts?.format}
+                                ref={element => {
+                                    buttons.current[index] = element;
+                                }}
+                                type='button'
+                                className={classNames('cratis-markdown-editor__format', parts?.format?.className)}
+                                data-cratis-part='format'
+                                data-disabled={disabled || undefined}
+                                disabled={disabled}
+                                tabIndex={index === current ? 0 : -1}
+                                aria-label={labels[format]}
+                                aria-keyshortcuts={shortcutFor(format)}
+                                title={labels[format]}
+                                onMouseDown={event => event.preventDefault()}
+                                onFocus={() => setFocusIndex(index)}
+                                onClick={() => onFormat(format)}
+                            >
+                                <span className='cratis-markdown-editor__format-icon' aria-hidden='true'>
+                                    {formatIcons[format]}
+                                </span>
+                            </button>
+                        );
+                    })}
+                </Fragment>
+            ))}
+        </div>
+    );
+};
diff --git a/Source/MarkdownEditor/MarkdownWritingArea.tsx b/Source/MarkdownEditor/MarkdownWritingArea.tsx
new file mode 100644
index 00000000..976bced5
--- /dev/null
+++ b/Source/MarkdownEditor/MarkdownWritingArea.tsx
@@ -0,0 +1,156 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ClipboardEvent, DragEvent, KeyboardEvent, RefObject, SyntheticEvent } from 'react';
+import { classNames } from '../ClassNames/classNames';
+import type { MarkdownEditorLabels } from './MarkdownEditorLabels';
+import type { MarkdownEditorParts } from './MarkdownEditorParts';
+import type { MarkdownEditorProps } from './MarkdownEditor';
+import type { MarkdownFormat } from './MarkdownFormat';
+import type { MarkdownTextEdit } from './MarkdownTextEdit';
+import { filesIn } from './filesIn';
+import { formatShortcuts } from './formatShortcuts';
+import type { MarkdownCompletionState } from './useMarkdownCompletion';
+import type { MarkdownUploadsState } from './useMarkdownUploads';
+
+/** Props for {@link MarkdownWritingArea}. */
+export interface MarkdownWritingAreaProps
+    extends Pick<
+        MarkdownEditorProps,
+        | 'value'
+        | 'onChange'
+        | 'onBlur'
+        | 'placeholder'
+        | 'autoFocus'
+        | 'disabled'
+        | 'readOnly'
+        | 'invalid'
+        | 'id'
+        | 'aria-label'
+        | 'aria-labelledby'
+        | 'aria-describedby'
+    > {
+    /** Pass-through attributes for the textarea. */
+    parts?: MarkdownEditorParts['textarea'];
+
+    /** The writing area's element, which the editor formats and measures. */
+    textareaRef: RefObject<HTMLTextAreaElement | null>;
+
+    /** The resolved labels. */
+    labels: Required<MarkdownEditorLabels>;
+
+    /** The completion being typed at the caret. */
+    completion: MarkdownCompletionState;
+
+    /** The uploads started from this editor. */
+    uploads: MarkdownUploadsState;
+
+    /** The element id of the suggestion list. */
+    suggestionsId: string;
+
+    /** The element id of the highlighted suggestion, while the list is open. */
+    activeOptionId?: string;
+
+    /** Called when the selection moves. */
+    onSelectionChange: (start: number, end: number) => void;
+
+    /** Applies an edit that also places the selection. */
+    onEdit: (edit: MarkdownTextEdit) => void;
+
+    /** Applies a format to the selection, as a keyboard shortcut asks. */
+    onFormat: (format: MarkdownFormat) => void;
+}
+
+const hasFiles = (event: DragEvent<HTMLTextAreaElement>) => Array.from(event.dataTransfer.types).includes('Files');
+
+/**
+ * The textarea of a {@link MarkdownEditor}, with its completion keys, formatting shortcuts, and file
+ * paste and drop.
+ */
+export const MarkdownWritingArea = (props: MarkdownWritingAreaProps) => {
+    const { completion, uploads, textareaRef, parts } = props;
+    const disabled = props.disabled ?? false;
+    const readOnly = props.readOnly ?? false;
+    const invalid = props.invalid ?? false;
+
+    const reportSelection = (event: SyntheticEvent<HTMLTextAreaElement>) =>
+        props.onSelectionChange(event.currentTarget.selectionStart, event.currentTarget.selectionEnd);
+
+    const onKeyDown = (event: KeyboardEvent<HTMLTextAreaElement>) => {
+        parts?.onKeyDown?.(event);
+        const edit = completion.handleKeyDown(event);
+        if (edit) {
+            props.onEdit(edit);
+            return;
+        }
+        if (event.defaultPrevented || event.altKey || event.shiftKey || !(event.ctrlKey || event.metaKey)) return;
+        const format = formatShortcuts.get(event.key.toLowerCase());
+        if (!format || disabled || readOnly) return;
+        event.preventDefault();
+        props.onFormat(format);
+    };
+
+    const onPaste = (event: ClipboardEvent<HTMLTextAreaElement>) => {
+        parts?.onPaste?.(event);
+        if (!uploads.isEnabled) return;
+        const files = filesIn(event.clipboardData.items);
+        if (files.length === 0) return;
+        event.preventDefault();
+        uploads.upload(files);
+    };
+
+    const onDrop = (event: DragEvent<HTMLTextAreaElement>) => {
+        parts?.onDrop?.(event);
+        if (!uploads.isEnabled) return;
+        const files = Array.from(event.dataTransfer.files);
+        if (files.length === 0) return;
+        event.preventDefault();
+        uploads.upload(files);
+    };
+
+    return (
+        <textarea
+            {...parts}
+            ref={textareaRef}
+            id={props.id}
+            className={classNames('cratis-markdown-editor__textarea', parts?.className)}
+            data-cratis-part='textarea'
+            data-disabled={disabled || undefined}
+            data-invalid={invalid || undefined}
+            data-readonly={readOnly || undefined}
+            value={props.value}
+            placeholder={props.placeholder}
+            disabled={disabled}
+            readOnly={readOnly}
+            autoFocus={props.autoFocus}
+            spellCheck
+            aria-label={props['aria-labelledby'] ? props['aria-label'] : (props['aria-label'] ?? props.labels.editor)}
+            aria-labelledby={props['aria-labelledby']}
+            aria-describedby={props['aria-describedby']}
+            aria-invalid={invalid || undefined}
+            aria-multiline='true'
+            aria-autocomplete={completion.isOpen ? 'list' : undefined}
+            aria-controls={completion.isOpen ? props.suggestionsId : undefined}
+            aria-activedescendant={props.activeOptionId}
+            onChange={event => {
+                props.onSelectionChange(event.target.selectionStart, event.target.selectionEnd);
+                props.onChange(event.target.value);
+            }}
+            onSelect={event => {
+                parts?.onSelect?.(event);
+                reportSelection(event);
+            }}
+            onKeyDown={onKeyDown}
+            onBlur={event => {
+                parts?.onBlur?.(event);
+                props.onBlur?.();
+            }}
+            onPaste={onPaste}
+            onDrop={onDrop}
+            onDragOver={event => {
+                parts?.onDragOver?.(event);
+                if (uploads.isEnabled && hasFiles(event)) event.preventDefault();
+            }}
+        />
+    );
+};
diff --git a/Source/MarkdownEditor/README.md b/Source/MarkdownEditor/README.md
new file mode 100644
index 00000000..c79ed25b
--- /dev/null
+++ b/Source/MarkdownEditor/README.md
@@ -0,0 +1,40 @@
+# MarkdownEditor
+
+A controlled markdown editor: one bordered box with a formatting toolbar, a round corner toggle that swaps
+the box to a host-rendered preview, configurable autocompletion at the caret, and uploads of pasted or
+dropped files through a host callback. Product documentation: `Documentation/MarkdownEditor/index.md`.
+
+## Component hierarchy
+
+- `MarkdownEditor.tsx` — composition root. Owns the mode, the selection, and the edits that place a selection.
+  - `MarkdownModeToggle.tsx` — the round `aria-pressed` toggle, shown only when `renderPreview` is given.
+  - `MarkdownToolbar.tsx` — the formatting buttons; one Tab stop with arrow-key movement.
+  - `MarkdownWritingArea.tsx` — the textarea: completion keys, formatting shortcuts, file paste and drop.
+  - `MarkdownSuggestionList.tsx` — the listbox portaled to the overlay container at the caret.
+- `useMarkdownCompletion.ts` — finds the trigger at the caret, debounces, aborts stale requests, and owns
+  the highlight and dismissal.
+- `useMarkdownUploads.ts` — placeholder-first uploads, resolved by value when each upload answers.
+- Pure text edits, each with specs: `applyMarkdownFormat.ts` (and `toggleInlineMarker.ts`,
+  `toggleLinePrefix.ts`, `toggleCodeBlock.ts`, `insertLink.ts`), `findCompletionMatch.ts`,
+  `replaceRange.ts`, `replacePlaceholder.ts`.
+
+## Architecture decisions
+
+- **No markdown renderer ships here.** Rendering and HTML sanitization are the host's security decision,
+  and every host already has a renderer for read-only markdown. `renderPreview` hands the preview to it,
+  which keeps this subpath free of markdown dependencies.
+- **Completion is generic.** A `MarkdownCompletion` names a string or pattern trigger and a `suggest`
+  callback; the editor owns recognition, debouncing, stale-answer dropping, rendering, keyboard handling
+  and insertion. What a trigger looks up stays with the host.
+- **One pane at a time.** The panes are absolutely positioned inside the body so a long document scrolls
+  inside the editor instead of growing it, and the root falls back to `height` as a `min-height`.
+- **Focus never leaves the writing area** while completing or formatting: suggestion and toolbar presses
+  prevent the mouse-down default, and the list is driven through `aria-activedescendant`.
+- **The suggestion list is a top layer.** It carries `data-react-aria-top-layer` so a React Aria modal
+  around the editor neither hides it nor treats a click on it as an outside interaction, and stacks above
+  the nearest dialog through the dialog stack.
+
+## Styling
+
+`MarkdownEditor.css`, imported through `Source/styles.css`, uses only `--cratis-*` tokens. It has no
+comments or transitions on purpose: every rule counts against the aggregate stylesheet budget.
diff --git a/Source/MarkdownEditor/applyMarkdownFormat.ts b/Source/MarkdownEditor/applyMarkdownFormat.ts
new file mode 100644
index 00000000..ad9e3e7d
--- /dev/null
+++ b/Source/MarkdownEditor/applyMarkdownFormat.ts
@@ -0,0 +1,59 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { MarkdownFormat } from './MarkdownFormat';
+import type { MarkdownTextEdit } from './MarkdownTextEdit';
+import { insertLink } from './insertLink';
+import { toggleCodeBlock } from './toggleCodeBlock';
+import { toggleInlineMarker } from './toggleInlineMarker';
+import { toggleLinePrefix } from './toggleLinePrefix';
+
+const heading = /^#{1,6} /u;
+const quote = /^> ?/u;
+const bullet = /^[-*+] (?!\[[ xX]\] )/u;
+const numbered = /^\d+\. /u;
+const task = /^[-*+] \[[ xX]\] /u;
+
+/**
+ * Applies a toolbar format to the selection in a piece of markdown. Every format is a toggle: applying
+ * it where it is already applied takes it off.
+ * @param value The markdown being edited.
+ * @param selectionStart Where the selection starts.
+ * @param selectionEnd Where the selection ends.
+ * @param format The {@link MarkdownFormat} to apply.
+ * @returns The edited markdown and the selection the writing area should show afterwards.
+ */
+export const applyMarkdownFormat = (
+    value: string,
+    selectionStart: number,
+    selectionEnd: number,
+    format: MarkdownFormat,
+): MarkdownTextEdit => {
+    const start = Math.min(selectionStart, selectionEnd);
+    const end = Math.max(selectionStart, selectionEnd);
+
+    switch (format) {
+        case MarkdownFormat.Bold:
+            return toggleInlineMarker(value, start, end, '**');
+        case MarkdownFormat.Italic:
+            return toggleInlineMarker(value, start, end, '_');
+        case MarkdownFormat.Strikethrough:
+            return toggleInlineMarker(value, start, end, '~~');
+        case MarkdownFormat.Code:
+            return toggleInlineMarker(value, start, end, '`');
+        case MarkdownFormat.CodeBlock:
+            return toggleCodeBlock(value, start, end);
+        case MarkdownFormat.Link:
+            return insertLink(value, start, end);
+        case MarkdownFormat.Heading:
+            return toggleLinePrefix(value, start, end, () => '## ', heading);
+        case MarkdownFormat.Quote:
+            return toggleLinePrefix(value, start, end, () => '> ', quote);
+        case MarkdownFormat.BulletList:
+            return toggleLinePrefix(value, start, end, () => '- ', bullet);
+        case MarkdownFormat.NumberedList:
+            return toggleLinePrefix(value, start, end, lineIndex => `${lineIndex + 1}. `, numbered);
+        case MarkdownFormat.TaskList:
+            return toggleLinePrefix(value, start, end, () => '- [ ] ', task);
+    }
+};
diff --git a/Source/MarkdownEditor/caretPositionIn.ts b/Source/MarkdownEditor/caretPositionIn.ts
new file mode 100644
index 00000000..fa5888cf
--- /dev/null
+++ b/Source/MarkdownEditor/caretPositionIn.ts
@@ -0,0 +1,71 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { CaretPosition } from './CaretPosition';
+
+const copiedStyles = [
+    'boxSizing',
+    'width',
+    'height',
+    'paddingTop',
+    'paddingRight',
+    'paddingBottom',
+    'paddingLeft',
+    'borderTopWidth',
+    'borderRightWidth',
+    'borderBottomWidth',
+    'borderLeftWidth',
+    'borderStyle',
+    'fontFamily',
+    'fontSize',
+    'fontStyle',
+    'fontWeight',
+    'fontVariant',
+    'letterSpacing',
+    'lineHeight',
+    'textTransform',
+    'textIndent',
+    'tabSize',
+    'wordSpacing',
+] as const;
+
+/**
+ * Measures where the caret of a textarea is on screen.
+ *
+ * A textarea exposes no caret coordinates, and counting lines fails on wrapped lines, proportional
+ * fonts and scrolling. So an invisible element takes the textarea's typography and box, holds the
+ * text up to the caret, and a zero-width marker after it is measured instead.
+ * @param textarea The textarea to measure in.
+ * @param caret The caret position within its value.
+ * @returns The caret's {@link CaretPosition}.
+ */
+export const caretPositionIn = (textarea: HTMLTextAreaElement, caret: number): CaretPosition => {
+    const computed = window.getComputedStyle(textarea);
+    const bounds = textarea.getBoundingClientRect();
+    const mirror = document.createElement('div');
+    const marker = document.createElement('span');
+
+    for (const property of copiedStyles) {
+        mirror.style[property] = computed[property];
+    }
+    mirror.style.position = 'fixed';
+    mirror.style.visibility = 'hidden';
+    mirror.style.pointerEvents = 'none';
+    mirror.style.overflow = 'hidden';
+    mirror.style.whiteSpace = 'pre-wrap';
+    mirror.style.overflowWrap = 'break-word';
+    mirror.style.left = `${bounds.left}px`;
+    mirror.style.top = `${bounds.top}px`;
+
+    mirror.textContent = textarea.value.slice(0, caret);
+    marker.textContent = '\u200b';
+    mirror.append(marker);
+    document.body.append(mirror);
+    mirror.scrollTop = textarea.scrollTop;
+    mirror.scrollLeft = textarea.scrollLeft;
+
+    const markerBounds = marker.getBoundingClientRect();
+    mirror.remove();
+
+    return { left: markerBounds.left, top: markerBounds.top, bottom: markerBounds.bottom };
+};
diff --git a/Source/MarkdownEditor/defaultMarkdownEditorLabels.ts b/Source/MarkdownEditor/defaultMarkdownEditorLabels.ts
new file mode 100644
index 00000000..0bf3d64e
--- /dev/null
+++ b/Source/MarkdownEditor/defaultMarkdownEditorLabels.ts
@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { MarkdownEditorLabels } from './MarkdownEditorLabels';
+
+/** The English labels a {@link MarkdownEditor} falls back to for every label the host leaves unset. */
+export const defaultMarkdownEditorLabels: Required<MarkdownEditorLabels> = {
+    editor: 'Markdown',
+    toolbar: 'Formatting',
+    bold: 'Bold',
+    italic: 'Italic',
+    strikethrough: 'Strikethrough',
+    heading: 'Heading',
+    quote: 'Quote',
+    code: 'Code',
+    codeBlock: 'Code block',
+    link: 'Link',
+    bulletList: 'Bulleted list',
+    numberedList: 'Numbered list',
+    taskList: 'Task list',
+    showPreview: 'Show preview',
+    showMarkdown: 'Show markdown',
+    emptyPreview: 'Nothing to preview',
+    suggestions: 'Suggestions',
+    uploading: fileNames => `Uploading ${fileNames.join(', ')}…`,
+};
diff --git a/Source/MarkdownEditor/defaultMarkdownFormats.ts b/Source/MarkdownEditor/defaultMarkdownFormats.ts
new file mode 100644
index 00000000..e7108a2e
--- /dev/null
+++ b/Source/MarkdownEditor/defaultMarkdownFormats.ts
@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { MarkdownFormat } from './MarkdownFormat';
+
+/**
+ * The toolbar a {@link MarkdownEditor} shows when the host does not choose one: text styles, then
+ * blocks and links, then lists. Each inner list is a group, drawn with a separator between groups.
+ */
+export const defaultMarkdownFormats: readonly (readonly MarkdownFormat[])[] = [
+    [MarkdownFormat.Heading, MarkdownFormat.Bold, MarkdownFormat.Italic, MarkdownFormat.Strikethrough],
+    [MarkdownFormat.Quote, MarkdownFormat.Code, MarkdownFormat.CodeBlock, MarkdownFormat.Link],
+    [MarkdownFormat.BulletList, MarkdownFormat.NumberedList, MarkdownFormat.TaskList],
+];
diff --git a/Source/MarkdownEditor/filesIn.ts b/Source/MarkdownEditor/filesIn.ts
new file mode 100644
index 00000000..13cfaf54
--- /dev/null
+++ b/Source/MarkdownEditor/filesIn.ts
@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Picks the files out of a paste or drop payload, ignoring everything that is not a file.
+ * @param items The items pasted or dropped.
+ * @returns The files among them, in order.
+ */
+export const filesIn = (items: DataTransferItemList): File[] =>
+    Array.from(items)
+        .filter(item => item.kind === 'file')
+        .map(item => item.getAsFile())
+        .filter((file): file is File => file !== null);
diff --git a/Source/MarkdownEditor/findCompletionMatch.ts b/Source/MarkdownEditor/findCompletionMatch.ts
new file mode 100644
index 00000000..b0aac75f
--- /dev/null
+++ b/Source/MarkdownEditor/findCompletionMatch.ts
@@ -0,0 +1,66 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { MarkdownCompletion } from './MarkdownCompletion';
+import type { MarkdownCompletionMatch } from './MarkdownCompletionMatch';
+
+interface TriggerMatch {
+    start: number;
+    query: string;
+}
+
+const whitespace = /\s/u;
+
+const matchStringTrigger = (line: string, completion: MarkdownCompletion, trigger: string): TriggerMatch | undefined => {
+    const triggerIndex = line.lastIndexOf(trigger);
+    if (triggerIndex === -1) return undefined;
+    if (triggerIndex > 0 && !whitespace.test(line[triggerIndex - 1])) return undefined;
+
+    const typed = line.slice(triggerIndex + trigger.length);
+    if (!completion.allowSpaces && whitespace.test(typed)) return undefined;
+
+    return { start: triggerIndex, query: completion.allowSpaces ? typed.trimStart() : typed };
+};
+
+const matchPatternTrigger = (line: string, trigger: RegExp): TriggerMatch | undefined => {
+    const pattern = new RegExp(trigger.source, trigger.flags.replace(/[gy]/gu, ''));
+    const match = pattern.exec(line);
+    if (!match || match.index + match[0].length !== line.length) return undefined;
+    return { start: match.index, query: match.groups?.query ?? match[1] ?? match[0] };
+};
+
+/**
+ * Finds the completion being typed at the caret. When several triggers match, the one that starts
+ * closest to the caret wins, because that is the one being typed.
+ * @param value The markdown being edited.
+ * @param caret The caret position.
+ * @param completions The configured completions.
+ * @returns The match, or undefined when the caret is not completing anything.
+ */
+export const findCompletionMatch = (
+    value: string,
+    caret: number,
+    completions: readonly MarkdownCompletion[],
+): MarkdownCompletionMatch | undefined => {
+    const beforeCaret = value.slice(0, caret);
+    const lineStart = beforeCaret.lastIndexOf('\n') + 1;
+    const line = beforeCaret.slice(lineStart);
+    let best: MarkdownCompletionMatch | undefined;
+
+    completions.forEach((completion, completionIndex) => {
+        const found =
+            typeof completion.trigger === 'string'
+                ? completion.trigger.length > 0
+                    ? matchStringTrigger(line, completion, completion.trigger)
+                    : undefined
+                : matchPatternTrigger(line, completion.trigger);
+        if (!found || found.query.length < (completion.minimumQueryLength ?? 0)) return;
+
+        const start = lineStart + found.start;
+        if (!best || start > best.start) {
+            best = { completion, completionIndex, start, end: caret, query: found.query };
+        }
+    });
+
+    return best;
+};
diff --git a/Source/MarkdownEditor/for_MarkdownEditor/given/an_editor_in_the_dom.ts b/Source/MarkdownEditor/for_MarkdownEditor/given/an_editor_in_the_dom.ts
new file mode 100644
index 00000000..95b179ed
--- /dev/null
+++ b/Source/MarkdownEditor/for_MarkdownEditor/given/an_editor_in_the_dom.ts
@@ -0,0 +1,136 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { act, createElement, useState } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { MarkdownEditor, type MarkdownEditorProps } from '../../MarkdownEditor';
+
+/**
+ * An editor mounted into a real document, holding its markdown the way a host does.
+ */
+export interface EditorInTheDom {
+    /** The element the editor is rendered into. */
+    container: HTMLDivElement;
+
+    /** The React root rendering it. */
+    root: Root;
+
+    /** Every value the editor reported through `onChange`, in order. */
+    changes: string[];
+
+    /** The editor's writing area, while the markdown is showing. */
+    textarea: () => HTMLTextAreaElement;
+}
+
+type HostProps = Omit<MarkdownEditorProps, 'value' | 'onChange'> & {
+    initialValue: string;
+    changes: string[];
+};
+
+const Host = ({ initialValue, changes, ...props }: HostProps) => {
+    const [value, setValue] = useState(initialValue);
+    return createElement(MarkdownEditor, {
+        ...props,
+        value,
+        onChange: (next: string) => {
+            changes.push(next);
+            setValue(next);
+        },
+    });
+};
+
+/**
+ * Renders a {@link MarkdownEditor} whose markdown is held by a host.
+ * @param initialValue The markdown to start with.
+ * @param props The rest of the editor's props.
+ * @returns The mounted editor.
+ */
+export const renderEditor = async (
+    initialValue: string,
+    props: Omit<MarkdownEditorProps, 'value' | 'onChange'> = {},
+): Promise<EditorInTheDom> => {
+    // SAFETY: React reads this process-wide test flag from globalThis.
+    (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    const changes: string[] = [];
+
+    await act(async () => {
+        root.render(createElement(Host, { ...props, initialValue, changes }));
+    });
+
+    return {
+        container,
+        root,
+        changes,
+        textarea: () => container.querySelector<HTMLTextAreaElement>('[data-cratis-part="textarea"]')!,
+    };
+};
+
+/**
+ * Unmounts an editor rendered with {@link renderEditor}.
+ * @param editor The mounted editor.
+ */
+export const unmount = async (editor: EditorInTheDom) => {
+    await act(async () => editor.root.unmount());
+    editor.container.remove();
+};
+
+/**
+ * Types markdown into a textarea the way the browser reports it to React, leaving the caret at the end.
+ * @param textarea The textarea to type into.
+ * @param value The markdown it should hold.
+ */
+export const typeInto = async (textarea: HTMLTextAreaElement, value: string) => {
+    const setter = Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value')!.set!;
+    await act(async () => {
+        setter.call(textarea, value);
+        textarea.setSelectionRange(value.length, value.length);
+        textarea.dispatchEvent(new Event('input', { bubbles: true }));
+    });
+};
+
+/**
+ * Selects a range in a textarea and lets React see the selection move.
+ * @param textarea The textarea.
+ * @param start Where the selection starts.
+ * @param end Where the selection ends.
+ */
+export const select = async (textarea: HTMLTextAreaElement, start: number, end: number) => {
+    await act(async () => {
+        textarea.focus();
+        textarea.setSelectionRange(start, end);
+        textarea.dispatchEvent(new Event('select', { bubbles: true }));
+    });
+};
+
+/**
+ * Presses a key in an element.
+ * @param element The element with focus.
+ * @param key The key.
+ * @param modifiers Modifier keys held down.
+ */
+export const press = async (element: HTMLElement, key: string, modifiers: KeyboardEventInit = {}) => {
+    await act(async () => {
+        element.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true, ...modifiers }));
+    });
+};
+
+/**
+ * Clicks an element.
+ * @param element The element to click.
+ */
+export const click = async (element: HTMLElement) => {
+    await act(async () => element.click());
+};
+
+/**
+ * Lets pending timers and promises settle, such as a completion's debounce.
+ * @param milliseconds How long to wait.
+ */
+export const settle = async (milliseconds = 10) => {
+    await act(async () => {
+        await new Promise(resolve => setTimeout(resolve, milliseconds));
+    });
+};
diff --git a/Source/MarkdownEditor/for_MarkdownEditor/when_completing_a_trigger.ts b/Source/MarkdownEditor/for_MarkdownEditor/when_completing_a_trigger.ts
new file mode 100644
index 00000000..6356abaa
--- /dev/null
+++ b/Source/MarkdownEditor/for_MarkdownEditor/when_completing_a_trigger.ts
@@ -0,0 +1,83 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+// @vitest-environment jsdom
+
+import type { MarkdownCompletion } from '../MarkdownCompletion';
+import type { MarkdownSuggestion } from '../MarkdownSuggestion';
+import { press, renderEditor, settle, typeInto, unmount, click, type EditorInTheDom } from './given/an_editor_in_the_dom';
+
+const suggestions: MarkdownSuggestion[] = [
+    { id: '12', insertText: 'sample/repository#12', label: 'Model discovery', detail: 'sample/repository#12', annotation: 'Issue' },
+    { id: '14', insertText: 'sample/repository#14', label: 'Model import', detail: 'sample/repository#14', annotation: 'Pull request' },
+];
+
+const list = () => document.querySelector<HTMLElement>('[data-cratis-part="suggestions"]');
+const options = () => Array.from(document.querySelectorAll<HTMLElement>('[data-cratis-part="suggestion"]'));
+
+describe('when completing a trigger', () => {
+    let editor: EditorInTheDom;
+    let queries: string[];
+
+    beforeEach(async () => {
+        queries = [];
+        const issues: MarkdownCompletion = {
+            trigger: '#',
+            allowSpaces: true,
+            debounce: 0,
+            label: 'Issues',
+            suggest: query => {
+                queries.push(query);
+                return Promise.resolve(suggestions);
+            },
+        };
+        editor = await renderEditor('', { completions: [issues] });
+        await typeInto(editor.textarea(), 'See #model');
+        await settle();
+    });
+
+    afterEach(async () => {
+        await unmount(editor);
+    });
+
+    it('should ask the completion with what was typed after the trigger', () => queries.should.contain('model'));
+    it('should open the list with the completion\'s name', () => list()!.getAttribute('aria-label')!.should.equal('Issues'));
+    it('should show every suggestion', () => options().should.have.lengthOf(2));
+    it('should render the default detail, label and annotation', () =>
+        options()[1].textContent!.should.equal('sample/repository#14Model importPull request'));
+    it('should highlight the first suggestion', () => options()[0].getAttribute('aria-selected')!.should.equal('true'));
+    it('should point the writing area at the highlighted suggestion', () =>
+        editor.textarea().getAttribute('aria-activedescendant')!.should.equal(options()[0].id));
+    it('should keep the list out of reach of a surrounding modal', () =>
+        list()!.getAttribute('data-react-aria-top-layer')!.should.equal('true'));
+
+    describe('and the next suggestion is picked with the keyboard', () => {
+        beforeEach(async () => {
+            await press(editor.textarea(), 'ArrowDown');
+            await press(editor.textarea(), 'Enter');
+        });
+
+        it('should replace the trigger and query with the suggestion', () =>
+            editor.changes[editor.changes.length - 1].should.equal('See sample/repository#14'));
+        it('should close the list', () => (list() === null).should.be.true);
+    });
+
+    describe('and a suggestion is clicked', () => {
+        beforeEach(async () => {
+            await click(options()[0]);
+        });
+
+        it('should replace the trigger and query with the suggestion', () =>
+            editor.changes[editor.changes.length - 1].should.equal('See sample/repository#12'));
+    });
+
+    describe('and the list is dismissed', () => {
+        beforeEach(async () => {
+            await press(editor.textarea(), 'Escape');
+            await typeInto(editor.textarea(), 'See #model d');
+            await settle();
+        });
+
+        it('should stay closed while the same trigger is typed on', () => (list() === null).should.be.true);
+    });
+});
diff --git a/Source/MarkdownEditor/for_MarkdownEditor/when_formatting.ts b/Source/MarkdownEditor/for_MarkdownEditor/when_formatting.ts
new file mode 100644
index 00000000..1991d18b
--- /dev/null
+++ b/Source/MarkdownEditor/for_MarkdownEditor/when_formatting.ts
@@ -0,0 +1,58 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+// @vitest-environment jsdom
+
+import { click, press, renderEditor, select, unmount, type EditorInTheDom } from './given/an_editor_in_the_dom';
+
+describe('when formatting', () => {
+    let editor: EditorInTheDom;
+
+    afterEach(async () => {
+        await unmount(editor);
+    });
+
+    describe('with a toolbar button', () => {
+        beforeEach(async () => {
+            editor = await renderEditor('make this loud');
+            await select(editor.textarea(), 5, 9);
+            await click(editor.container.querySelector<HTMLButtonElement>('[aria-label="Bold"]')!);
+        });
+
+        it('should format the selection', () => editor.changes[0].should.equal('make **this** loud'));
+        it('should keep the formatted text selected', () => {
+            editor.textarea().selectionStart.should.equal(7);
+            editor.textarea().selectionEnd.should.equal(11);
+        });
+    });
+
+    describe('with a keyboard shortcut', () => {
+        beforeEach(async () => {
+            editor = await renderEditor('lean');
+            await select(editor.textarea(), 0, 4);
+            await press(editor.textarea(), 'i', { ctrlKey: true });
+        });
+
+        it('should format the selection', () => editor.changes[0].should.equal('_lean_'));
+    });
+
+    describe('when read only', () => {
+        beforeEach(async () => {
+            editor = await renderEditor('fixed', { readOnly: true });
+        });
+
+        it('should disable every format', () =>
+            Array.from(editor.container.querySelectorAll<HTMLButtonElement>('[data-cratis-part="format"]'))
+                .every(button => button.disabled)
+                .should.be.true);
+    });
+
+    describe('with the toolbar turned off', () => {
+        beforeEach(async () => {
+            editor = await renderEditor('plain', { formats: false });
+        });
+
+        it('should render no toolbar', () =>
+            (editor.container.querySelector('[data-cratis-part="toolbar"]') === null).should.be.true);
+    });
+});
diff --git a/Source/MarkdownEditor/for_MarkdownEditor/when_toggling_the_preview.ts b/Source/MarkdownEditor/for_MarkdownEditor/when_toggling_the_preview.ts
new file mode 100644
index 00000000..24fa0ae9
--- /dev/null
+++ b/Source/MarkdownEditor/for_MarkdownEditor/when_toggling_the_preview.ts
@@ -0,0 +1,61 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+// @vitest-environment jsdom
+
+import { createElement } from 'react';
+import { click, renderEditor, unmount, type EditorInTheDom } from './given/an_editor_in_the_dom';
+
+const toggle = (editor: EditorInTheDom) =>
+    editor.container.querySelector<HTMLButtonElement>('[data-cratis-part="toggle"]');
+
+describe('when toggling the preview', () => {
+    let editor: EditorInTheDom;
+
+    afterEach(async () => {
+        await unmount(editor);
+    });
+
+    describe('with a preview renderer', () => {
+        beforeEach(async () => {
+            editor = await renderEditor('# Sample', {
+                renderPreview: markdown => createElement('article', { className: 'rendered' }, `rendered: ${markdown}`),
+            });
+            await click(toggle(editor)!);
+        });
+
+        it('should show the rendered markdown', () =>
+            editor.container.querySelector('.rendered')!.textContent!.should.equal('rendered: # Sample'));
+        it('should hide the writing area', () =>
+            (editor.container.querySelector('[data-cratis-part="textarea"]') === null).should.be.true);
+        it('should announce the toggle as pressed', () => toggle(editor)!.getAttribute('aria-pressed')!.should.equal('true'));
+        it('should name what pressing it does next', () =>
+            toggle(editor)!.getAttribute('aria-label')!.should.equal('Show markdown'));
+
+        describe('and it is toggled back', () => {
+            beforeEach(async () => {
+                await click(toggle(editor)!);
+            });
+
+            it('should show the markdown again', () => editor.textarea().value.should.equal('# Sample'));
+        });
+    });
+
+    describe('with nothing to preview', () => {
+        beforeEach(async () => {
+            editor = await renderEditor('', { renderPreview: () => 'never', labels: { emptyPreview: 'Empty' } });
+            await click(toggle(editor)!);
+        });
+
+        it('should show the empty label rather than rendering', () =>
+            editor.container.querySelector('[data-cratis-part="preview"]')!.textContent!.should.equal('Empty'));
+    });
+
+    describe('without a preview renderer', () => {
+        beforeEach(async () => {
+            editor = await renderEditor('# Sample');
+        });
+
+        it('should offer no toggle', () => (toggle(editor) === null).should.be.true);
+    });
+});
diff --git a/Source/MarkdownEditor/for_MarkdownEditor/when_uploading_a_pasted_file.ts b/Source/MarkdownEditor/for_MarkdownEditor/when_uploading_a_pasted_file.ts
new file mode 100644
index 00000000..16787872
--- /dev/null
+++ b/Source/MarkdownEditor/for_MarkdownEditor/when_uploading_a_pasted_file.ts
@@ -0,0 +1,72 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+// @vitest-environment jsdom
+
+import { act } from 'react';
+import { renderEditor, select, settle, unmount, type EditorInTheDom } from './given/an_editor_in_the_dom';
+
+const paste = async (textarea: HTMLTextAreaElement, file: File) => {
+    const event = new Event('paste', { bubbles: true, cancelable: true });
+    Object.defineProperty(event, 'clipboardData', {
+        value: { items: [{ kind: 'file', getAsFile: () => file }], files: [file], types: ['Files'] },
+    });
+    await act(async () => {
+        textarea.dispatchEvent(event);
+    });
+};
+
+describe('when uploading a pasted file', () => {
+    let editor: EditorInTheDom;
+    let resolveUpload: (markup: string) => void;
+    let rejectUpload: (reason: unknown) => void;
+    let failures: string[];
+    const file = new File(['pixels'], 'sample.png', { type: 'image/png' });
+
+    beforeEach(async () => {
+        failures = [];
+        editor = await renderEditor('Look: ', {
+            uploadFile: () =>
+                new Promise<string>((resolve, reject) => {
+                    resolveUpload = resolve;
+                    rejectUpload = reject;
+                }),
+            onUploadFailed: failed => failures.push(failed.name),
+        });
+        await select(editor.textarea(), 6, 6);
+        await paste(editor.textarea(), file);
+    });
+
+    afterEach(async () => {
+        await unmount(editor);
+    });
+
+    it('should put a placeholder in at the caret straight away', () =>
+        editor.textarea().value.should.equal('Look: ![Uploading sample.png…]()\n'));
+    it('should announce the upload', () =>
+        editor.container.querySelector('[data-cratis-part="status"]')!.textContent!.should.equal('Uploading sample.png…'));
+    it('should mark the editor busy', () =>
+        editor.container.querySelector('[data-cratis-part="root"]')!.hasAttribute('data-busy').should.be.true);
+
+    describe('and the upload succeeds', () => {
+        beforeEach(async () => {
+            resolveUpload('![sample](https://example.invalid/sample.png)');
+            await settle();
+        });
+
+        it('should replace the placeholder with the returned markdown', () =>
+            editor.textarea().value.should.equal('Look: ![sample](https://example.invalid/sample.png)\n'));
+        it('should stop announcing the upload', () =>
+            (editor.container.querySelector('[data-cratis-part="status"]') === null).should.be.true);
+    });
+
+    describe('and the upload fails', () => {
+        beforeEach(async () => {
+            rejectUpload(new Error('offline'));
+            await settle();
+        });
+
+        it('should take the placeholder out again', () => editor.textarea().value.should.equal('Look: '));
+        it('should report the failed file', () => failures.should.deep.equal(['sample.png']));
+    });
+});
diff --git a/Source/MarkdownEditor/for_applyMarkdownFormat/when_inserting_a_link.ts b/Source/MarkdownEditor/for_applyMarkdownFormat/when_inserting_a_link.ts
new file mode 100644
index 00000000..75f2d732
--- /dev/null
+++ b/Source/MarkdownEditor/for_applyMarkdownFormat/when_inserting_a_link.ts
@@ -0,0 +1,31 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { applyMarkdownFormat } from '../applyMarkdownFormat';
+import { MarkdownFormat } from '../MarkdownFormat';
+
+describe('when inserting a link', () => {
+    describe('around selected text', () => {
+        const result = applyMarkdownFormat('see the docs', 8, 12, MarkdownFormat.Link);
+
+        it('should link the text', () => result.value.should.equal('see the [docs](url)'));
+        it('should select the address to type over', () =>
+            result.value.slice(result.selectionStart, result.selectionEnd).should.equal('url'));
+    });
+
+    describe('around a selected address', () => {
+        const result = applyMarkdownFormat('https://example.invalid', 0, 23, MarkdownFormat.Link);
+
+        it('should use it as the address', () => result.value.should.equal('[text](https://example.invalid)'));
+        it('should select the link text to type over', () =>
+            result.value.slice(result.selectionStart, result.selectionEnd).should.equal('text'));
+    });
+
+    describe('at a plain caret', () => {
+        const result = applyMarkdownFormat('', 0, 0, MarkdownFormat.Link);
+
+        it('should put in an empty link', () => result.value.should.equal('[text](url)'));
+        it('should select the link text', () =>
+            result.value.slice(result.selectionStart, result.selectionEnd).should.equal('text'));
+    });
+});
diff --git a/Source/MarkdownEditor/for_applyMarkdownFormat/when_toggling_a_code_block.ts b/Source/MarkdownEditor/for_applyMarkdownFormat/when_toggling_a_code_block.ts
new file mode 100644
index 00000000..94120f1e
--- /dev/null
+++ b/Source/MarkdownEditor/for_applyMarkdownFormat/when_toggling_a_code_block.ts
@@ -0,0 +1,31 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { applyMarkdownFormat } from '../applyMarkdownFormat';
+import { MarkdownFormat } from '../MarkdownFormat';
+
+const fence = '```';
+
+describe('when toggling a code block', () => {
+    describe('around lines without one', () => {
+        const result = applyMarkdownFormat('before\nlet x = 1;\nafter', 7, 17, MarkdownFormat.CodeBlock);
+
+        it('should fence the lines', () => result.value.should.equal(`before\n${fence}\nlet x = 1;\n${fence}\nafter`));
+        it('should select the fenced content', () =>
+            result.value.slice(result.selectionStart, result.selectionEnd).should.equal('let x = 1;'));
+    });
+
+    describe('around lines that already are one', () => {
+        const markdown = `${fence}\nlet x = 1;\n${fence}`;
+        const result = applyMarkdownFormat(markdown, 0, markdown.length, MarkdownFormat.CodeBlock);
+
+        it('should take the fences off', () => result.value.should.equal('let x = 1;'));
+    });
+
+    describe('on an empty line', () => {
+        const result = applyMarkdownFormat('', 0, 0, MarkdownFormat.CodeBlock);
+
+        it('should put in an empty block', () => result.value.should.equal(`${fence}\n\n${fence}`));
+        it('should leave the caret inside it', () => result.selectionStart.should.equal(4));
+    });
+});
diff --git a/Source/MarkdownEditor/for_applyMarkdownFormat/when_toggling_a_line_format.ts b/Source/MarkdownEditor/for_applyMarkdownFormat/when_toggling_a_line_format.ts
new file mode 100644
index 00000000..d14aa3ee
--- /dev/null
+++ b/Source/MarkdownEditor/for_applyMarkdownFormat/when_toggling_a_line_format.ts
@@ -0,0 +1,47 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { applyMarkdownFormat } from '../applyMarkdownFormat';
+import { MarkdownFormat } from '../MarkdownFormat';
+
+describe('when toggling a line format', () => {
+    describe('on a selection across lines without it', () => {
+        const markdown = 'intro\nfirst\nsecond\noutro';
+        const result = applyMarkdownFormat(markdown, 8, 15, MarkdownFormat.BulletList);
+
+        it('should prefix every touched line', () => result.value.should.equal('intro\n- first\n- second\noutro'));
+        it('should select the edited lines', () =>
+            result.value.slice(result.selectionStart, result.selectionEnd).should.equal('- first\n- second'));
+    });
+
+    describe('on lines that all have it', () => {
+        const result = applyMarkdownFormat('> one\n> two', 0, 11, MarkdownFormat.Quote);
+
+        it('should take the prefix off every line', () => result.value.should.equal('one\ntwo'));
+    });
+
+    describe('as a numbered list', () => {
+        const result = applyMarkdownFormat('one\ntwo\nthree', 0, 13, MarkdownFormat.NumberedList);
+
+        it('should number the lines in order', () => result.value.should.equal('1. one\n2. two\n3. three'));
+    });
+
+    describe('as a heading at a caret', () => {
+        const result = applyMarkdownFormat('Title', 2, 2, MarkdownFormat.Heading);
+
+        it('should prefix the caret line', () => result.value.should.equal('## Title'));
+        it('should keep the caret on the same letter', () => result.selectionStart.should.equal(5));
+    });
+
+    describe('as a bullet list on a task list line', () => {
+        const result = applyMarkdownFormat('- [ ] chore', 0, 0, MarkdownFormat.BulletList);
+
+        it('should not mistake the task for a bullet', () => result.value.should.equal('- - [ ] chore'));
+    });
+
+    describe('with a selection ending at the start of the next line', () => {
+        const result = applyMarkdownFormat('one\ntwo', 0, 4, MarkdownFormat.TaskList);
+
+        it('should leave that next line alone', () => result.value.should.equal('- [ ] one\ntwo'));
+    });
+});
diff --git a/Source/MarkdownEditor/for_applyMarkdownFormat/when_toggling_an_inline_format.ts b/Source/MarkdownEditor/for_applyMarkdownFormat/when_toggling_an_inline_format.ts
new file mode 100644
index 00000000..ed8982a3
--- /dev/null
+++ b/Source/MarkdownEditor/for_applyMarkdownFormat/when_toggling_an_inline_format.ts
@@ -0,0 +1,47 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { applyMarkdownFormat } from '../applyMarkdownFormat';
+import { MarkdownFormat } from '../MarkdownFormat';
+
+describe('when toggling an inline format', () => {
+    describe('on a selection without it', () => {
+        const result = applyMarkdownFormat('make this loud', 5, 9, MarkdownFormat.Bold);
+
+        it('should wrap the selection in the marker', () => result.value.should.equal('make **this** loud'));
+        it('should keep the same text selected', () =>
+            result.value.slice(result.selectionStart, result.selectionEnd).should.equal('this'));
+    });
+
+    describe('on a selection wrapped just outside it', () => {
+        const result = applyMarkdownFormat('make **this** loud', 7, 11, MarkdownFormat.Bold);
+
+        it('should take the marker off', () => result.value.should.equal('make this loud'));
+        it('should keep the same text selected', () =>
+            result.value.slice(result.selectionStart, result.selectionEnd).should.equal('this'));
+    });
+
+    describe('on a selection that includes the markers', () => {
+        const result = applyMarkdownFormat('make ~~this~~ quiet', 5, 13, MarkdownFormat.Strikethrough);
+
+        it('should take the markers off', () => result.value.should.equal('make this quiet'));
+        it('should select the text that was inside them', () =>
+            result.value.slice(result.selectionStart, result.selectionEnd).should.equal('this'));
+    });
+
+    describe('at a plain caret', () => {
+        const result = applyMarkdownFormat('say ', 4, 4, MarkdownFormat.Code);
+
+        it('should put an empty pair of markers in', () => result.value.should.equal('say ``'));
+        it('should leave the caret between them', () => {
+            result.selectionStart.should.equal(5);
+            result.selectionEnd.should.equal(5);
+        });
+    });
+
+    describe('on a selection made backwards', () => {
+        const result = applyMarkdownFormat('lean', 4, 0, MarkdownFormat.Italic);
+
+        it('should format the selected text all the same', () => result.value.should.equal('_lean_'));
+    });
+});
diff --git a/Source/MarkdownEditor/for_findCompletionMatch/given.ts b/Source/MarkdownEditor/for_findCompletionMatch/given.ts
new file mode 100644
index 00000000..6730e8a1
--- /dev/null
+++ b/Source/MarkdownEditor/for_findCompletionMatch/given.ts
@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { MarkdownCompletion } from '../MarkdownCompletion';
+
+/**
+ * A completion that never answers, for specs that only look at what is matched.
+ * @param overrides What to change from a plain `#` completion.
+ * @returns The completion.
+ */
+export const aCompletion = (overrides: Partial<MarkdownCompletion> = {}): MarkdownCompletion => ({
+    trigger: '#',
+    suggest: () => [],
+    ...overrides,
+});
diff --git a/Source/MarkdownEditor/for_findCompletionMatch/when_a_pattern_trigger_is_typed.ts b/Source/MarkdownEditor/for_findCompletionMatch/when_a_pattern_trigger_is_typed.ts
new file mode 100644
index 00000000..738fa548
--- /dev/null
+++ b/Source/MarkdownEditor/for_findCompletionMatch/when_a_pattern_trigger_is_typed.ts
@@ -0,0 +1,34 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { findCompletionMatch } from '../findCompletionMatch';
+import { aCompletion } from './given';
+
+describe('when a pattern trigger is typed', () => {
+    const completion = aCompletion({ trigger: /(?<=^|\s)\[\[(?<query>[^\]]*)$/u });
+
+    describe('and its match ends at the caret', () => {
+        const markdown = 'link to [[Sample';
+        const result = findCompletionMatch(markdown, markdown.length, [completion]);
+
+        it('should take the named group as the query', () => result!.query.should.equal('Sample'));
+        it('should start where the match starts', () => result!.start.should.equal(8));
+    });
+
+    describe('and its match does not reach the caret', () => {
+        const markdown = 'link to [[Sample]] done';
+        const result = findCompletionMatch(markdown, markdown.length, [completion]);
+
+        it('should not match', () => (result === undefined).should.be.true);
+    });
+
+    describe('with a global flag', () => {
+        const global = aCompletion({ trigger: /:(\w*)$/gu });
+        const markdown = 'smile :sm';
+        findCompletionMatch(markdown, markdown.length, [global]);
+        const result = findCompletionMatch(markdown, markdown.length, [global]);
+
+        it('should match every time rather than resuming where the last match ended', () =>
+            result!.query.should.equal('sm'));
+    });
+});
diff --git a/Source/MarkdownEditor/for_findCompletionMatch/when_a_string_trigger_is_typed.ts b/Source/MarkdownEditor/for_findCompletionMatch/when_a_string_trigger_is_typed.ts
new file mode 100644
index 00000000..cefe161e
--- /dev/null
+++ b/Source/MarkdownEditor/for_findCompletionMatch/when_a_string_trigger_is_typed.ts
@@ -0,0 +1,61 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { findCompletionMatch } from '../findCompletionMatch';
+import { aCompletion } from './given';
+
+describe('when a string trigger is typed', () => {
+    describe('after whitespace', () => {
+        const markdown = 'Related to #12';
+        const result = findCompletionMatch(markdown, markdown.length, [aCompletion()]);
+
+        it('should find the query after it', () => result!.query.should.equal('12'));
+        it('should start at the trigger', () => result!.start.should.equal(11));
+        it('should end at the caret', () => result!.end.should.equal(markdown.length));
+    });
+
+    describe('at the start of a line', () => {
+        const markdown = 'first line\n#';
+        const result = findCompletionMatch(markdown, markdown.length, [aCompletion()]);
+
+        it('should match with an empty query', () => result!.query.should.equal(''));
+    });
+
+    describe('inside a word', () => {
+        const markdown = 'C#';
+        const result = findCompletionMatch(markdown, markdown.length, [aCompletion()]);
+
+        it('should not match', () => (result === undefined).should.be.true);
+    });
+
+    describe('followed by a space when spaces are not allowed', () => {
+        const markdown = '@sample user';
+        const result = findCompletionMatch(markdown, markdown.length, [aCompletion({ trigger: '@' })]);
+
+        it('should not match', () => (result === undefined).should.be.true);
+    });
+
+    describe('followed by a title when spaces are allowed', () => {
+        const markdown = 'see # model discovery';
+        const result = findCompletionMatch(markdown, markdown.length, [aCompletion({ allowSpaces: true })]);
+
+        it('should take the title as the query without its leading space', () =>
+            result!.query.should.equal('model discovery'));
+    });
+
+    describe('with fewer characters than the minimum', () => {
+        const markdown = 'ask :s';
+        const result = findCompletionMatch(markdown, markdown.length, [
+            aCompletion({ trigger: ':', minimumQueryLength: 2 }),
+        ]);
+
+        it('should not match', () => (result === undefined).should.be.true);
+    });
+
+    describe('on an earlier line only', () => {
+        const markdown = '#12\nnext';
+        const result = findCompletionMatch(markdown, markdown.length, [aCompletion({ allowSpaces: true })]);
+
+        it('should not match', () => (result === undefined).should.be.true);
+    });
+});
diff --git a/Source/MarkdownEditor/for_findCompletionMatch/when_several_triggers_match.ts b/Source/MarkdownEditor/for_findCompletionMatch/when_several_triggers_match.ts
new file mode 100644
index 00000000..2aef4a01
--- /dev/null
+++ b/Source/MarkdownEditor/for_findCompletionMatch/when_several_triggers_match.ts
@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { findCompletionMatch } from '../findCompletionMatch';
+import { aCompletion } from './given';
+
+describe('when several triggers match', () => {
+    const issues = aCompletion({ trigger: '#', allowSpaces: true });
+    const people = aCompletion({ trigger: '@' });
+    const markdown = '#12 asks @sam';
+    const result = findCompletionMatch(markdown, markdown.length, [issues, people]);
+
+    it('should pick the one closest to the caret', () => result!.completion.should.equal(people));
+    it('should report where it sits in the configured list', () => result!.completionIndex.should.equal(1));
+});
diff --git a/Source/MarkdownEditor/for_nextMarkdownEditorMode/when_toggling.ts b/Source/MarkdownEditor/for_nextMarkdownEditorMode/when_toggling.ts
new file mode 100644
index 00000000..b59c9c25
--- /dev/null
+++ b/Source/MarkdownEditor/for_nextMarkdownEditorMode/when_toggling.ts
@@ -0,0 +1,12 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { MarkdownEditorMode } from '../MarkdownEditorMode';
+import { nextMarkdownEditorMode } from '../nextMarkdownEditorMode';
+
+describe('when toggling the mode', () => {
+    it('should go from writing to the preview', () =>
+        nextMarkdownEditorMode(MarkdownEditorMode.Write).should.equal(MarkdownEditorMode.Preview));
+    it('should go from the preview back to writing', () =>
+        nextMarkdownEditorMode(MarkdownEditorMode.Preview).should.equal(MarkdownEditorMode.Write));
+});
diff --git a/Source/MarkdownEditor/for_replacePlaceholder/when_resolving_an_upload_placeholder.ts b/Source/MarkdownEditor/for_replacePlaceholder/when_resolving_an_upload_placeholder.ts
new file mode 100644
index 00000000..8caf6913
--- /dev/null
+++ b/Source/MarkdownEditor/for_replacePlaceholder/when_resolving_an_upload_placeholder.ts
@@ -0,0 +1,28 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { replacePlaceholder } from '../replacePlaceholder';
+import { uploadPlaceholderFor } from '../uploadPlaceholderFor';
+
+describe('when resolving an upload placeholder', () => {
+    const placeholder = uploadPlaceholderFor('sample.png');
+
+    describe('that is still there', () => {
+        const result = replacePlaceholder(`before ${placeholder} after`, placeholder, '![sample](https://example.invalid/sample.png)');
+
+        it('should put the markup in its place', () =>
+            result.should.equal('before ![sample](https://example.invalid/sample.png) after'));
+    });
+
+    describe('that was deleted while uploading', () => {
+        const result = replacePlaceholder('nothing here', placeholder, 'markup');
+
+        it('should leave the markdown untouched', () => result.should.equal('nothing here'));
+    });
+
+    describe('with markup holding replacement patterns', () => {
+        const result = replacePlaceholder(placeholder, placeholder, 'cost $& more');
+
+        it('should put the markup in literally', () => result.should.equal('cost $& more'));
+    });
+});
diff --git a/Source/MarkdownEditor/for_replaceRange/when_replacing_a_range.ts b/Source/MarkdownEditor/for_replaceRange/when_replacing_a_range.ts
new file mode 100644
index 00000000..da53f4b6
--- /dev/null
+++ b/Source/MarkdownEditor/for_replaceRange/when_replacing_a_range.ts
@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { replaceRange } from '../replaceRange';
+
+describe('when replacing a range', () => {
+    const result = replaceRange('see #mod here', 4, 8, 'sample/repository#12');
+
+    it('should put the text in place of the range', () => result.value.should.equal('see sample/repository#12 here'));
+    it('should leave the caret after what was put in', () => {
+        result.selectionStart.should.equal(24);
+        result.selectionEnd.should.equal(24);
+    });
+});
diff --git a/Source/MarkdownEditor/formatIcons.tsx b/Source/MarkdownEditor/formatIcons.tsx
new file mode 100644
index 00000000..a8f28a64
--- /dev/null
+++ b/Source/MarkdownEditor/formatIcons.tsx
@@ -0,0 +1,33 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { ReactNode } from 'react';
+import {
+    FaBold,
+    FaCode,
+    FaFileCode,
+    FaHeading,
+    FaItalic,
+    FaLink,
+    FaListCheck,
+    FaListOl,
+    FaListUl,
+    FaQuoteRight,
+    FaStrikethrough,
+} from 'react-icons/fa6';
+import { MarkdownFormat } from './MarkdownFormat';
+
+/** The glyph drawn on each formatting button. */
+export const formatIcons: Record<MarkdownFormat, ReactNode> = {
+    [MarkdownFormat.Heading]: <FaHeading />,
+    [MarkdownFormat.Bold]: <FaBold />,
+    [MarkdownFormat.Italic]: <FaItalic />,
+    [MarkdownFormat.Strikethrough]: <FaStrikethrough />,
+    [MarkdownFormat.Quote]: <FaQuoteRight />,
+    [MarkdownFormat.Code]: <FaCode />,
+    [MarkdownFormat.CodeBlock]: <FaFileCode />,
+    [MarkdownFormat.Link]: <FaLink />,
+    [MarkdownFormat.BulletList]: <FaListUl />,
+    [MarkdownFormat.NumberedList]: <FaListOl />,
+    [MarkdownFormat.TaskList]: <FaListCheck />,
+};
diff --git a/Source/MarkdownEditor/formatShortcuts.ts b/Source/MarkdownEditor/formatShortcuts.ts
new file mode 100644
index 00000000..f99a5139
--- /dev/null
+++ b/Source/MarkdownEditor/formatShortcuts.ts
@@ -0,0 +1,11 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { MarkdownFormat } from './MarkdownFormat';
+
+/** The formats reachable with Control (Command on macOS) and a letter, keyed by the lowercase letter. */
+export const formatShortcuts: ReadonlyMap<string, MarkdownFormat> = new Map([
+    ['b', MarkdownFormat.Bold],
+    ['i', MarkdownFormat.Italic],
+    ['k', MarkdownFormat.Link],
+]);
diff --git a/Source/MarkdownEditor/index.ts b/Source/MarkdownEditor/index.ts
new file mode 100644
index 00000000..f24ea42a
--- /dev/null
+++ b/Source/MarkdownEditor/index.ts
@@ -0,0 +1,16 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export { MarkdownEditor } from './MarkdownEditor';
+export type { MarkdownEditorProps } from './MarkdownEditor';
+export type { MarkdownEditorParts, MarkdownEditorPartAttributes } from './MarkdownEditorParts';
+export type { MarkdownEditorLabels } from './MarkdownEditorLabels';
+export { MarkdownEditorMode } from './MarkdownEditorMode';
+export { MarkdownFormat } from './MarkdownFormat';
+export type { MarkdownCompletion } from './MarkdownCompletion';
+export type { MarkdownCompletionContext } from './MarkdownCompletionContext';
+export type { MarkdownSuggestion } from './MarkdownSuggestion';
+export type { MarkdownTextEdit } from './MarkdownTextEdit';
+export { applyMarkdownFormat } from './applyMarkdownFormat';
+export { defaultMarkdownFormats } from './defaultMarkdownFormats';
+export { defaultMarkdownEditorLabels } from './defaultMarkdownEditorLabels';
diff --git a/Source/MarkdownEditor/insertLink.ts b/Source/MarkdownEditor/insertLink.ts
new file mode 100644
index 00000000..95afe86a
--- /dev/null
+++ b/Source/MarkdownEditor/insertLink.ts
@@ -0,0 +1,40 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { MarkdownTextEdit } from './MarkdownTextEdit';
+
+const addressPlaceholder = 'url';
+const textPlaceholder = 'text';
+const looksLikeAnAddress = /^(https?:\/\/|mailto:)\S+$/iu;
+
+/**
+ * Turns the selection into a markdown link and selects the part still to be written: the address when
+ * text was selected, the link text when an address was selected, and the link text of an empty link
+ * when nothing was.
+ * @param value The markdown being edited.
+ * @param start Where the selection starts.
+ * @param end Where the selection ends.
+ * @returns The edited markdown and the selection after it.
+ */
+export const insertLink = (value: string, start: number, end: number): MarkdownTextEdit => {
+    const selected = value.slice(start, end);
+    const before = value.slice(0, start);
+    const after = value.slice(end);
+
+    if (looksLikeAnAddress.test(selected)) {
+        return {
+            value: `${before}[${textPlaceholder}](${selected})${after}`,
+            selectionStart: start + 1,
+            selectionEnd: start + 1 + textPlaceholder.length,
+        };
+    }
+
+    const text = selected.length > 0 ? selected : textPlaceholder;
+    const link = `[${text}](${addressPlaceholder})`;
+    const addressStart = start + text.length + 3;
+    return {
+        value: `${before}${link}${after}`,
+        selectionStart: selected.length > 0 ? addressStart : start + 1,
+        selectionEnd: selected.length > 0 ? addressStart + addressPlaceholder.length : start + 1 + text.length,
+    };
+};
diff --git a/Source/MarkdownEditor/lineBlockAround.ts b/Source/MarkdownEditor/lineBlockAround.ts
new file mode 100644
index 00000000..5c874281
--- /dev/null
+++ b/Source/MarkdownEditor/lineBlockAround.ts
@@ -0,0 +1,24 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { MarkdownLineBlock } from './MarkdownLineBlock';
+
+/**
+ * Finds the whole lines a selection touches. A selection that ends right at the start of a line -
+ * what selecting whole lines with the keyboard produces - does not count that line as touched.
+ * @param value The markdown being edited.
+ * @param start Where the selection starts.
+ * @param end Where the selection ends.
+ * @returns The touched lines and where they sit in the markdown.
+ */
+export const lineBlockAround = (value: string, start: number, end: number): MarkdownLineBlock => {
+    const effectiveEnd = end > start && value[end - 1] === '\n' ? end - 1 : end;
+    const blockStart = value.lastIndexOf('\n', start - 1) + 1;
+    const lineBreakAfter = value.indexOf('\n', effectiveEnd);
+    const blockEnd = lineBreakAfter === -1 ? value.length : lineBreakAfter;
+    return {
+        start: blockStart,
+        end: blockEnd,
+        lines: value.slice(blockStart, blockEnd).split('\n'),
+    };
+};
diff --git a/Source/MarkdownEditor/nextMarkdownEditorMode.ts b/Source/MarkdownEditor/nextMarkdownEditorMode.ts
new file mode 100644
index 00000000..404bf021
--- /dev/null
+++ b/Source/MarkdownEditor/nextMarkdownEditorMode.ts
@@ -0,0 +1,12 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { MarkdownEditorMode } from './MarkdownEditorMode';
+
+/**
+ * Works out the mode the mode toggle moves to from the one being shown.
+ * @param mode The {@link MarkdownEditorMode} currently on screen.
+ * @returns The mode to show next.
+ */
+export const nextMarkdownEditorMode = (mode: MarkdownEditorMode): MarkdownEditorMode =>
+    mode === MarkdownEditorMode.Preview ? MarkdownEditorMode.Write : MarkdownEditorMode.Preview;
diff --git a/Source/MarkdownEditor/replacePlaceholder.ts b/Source/MarkdownEditor/replacePlaceholder.ts
new file mode 100644
index 00000000..35a1a0ec
--- /dev/null
+++ b/Source/MarkdownEditor/replacePlaceholder.ts
@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Replaces an upload placeholder with what it stood for, wherever it ended up.
+ *
+ * By value rather than by remembered position: the caret moves and other uploads finish while this one
+ * is in flight, so the offset the placeholder went in at is stale by the time it comes back. A
+ * placeholder that is no longer there - deleted while uploading - leaves the markdown untouched rather
+ * than putting the result somewhere arbitrary.
+ * @param value The markdown as it is now.
+ * @param placeholder The placeholder that was inserted.
+ * @param replacement What to put in its place - empty to drop it, as on a failed upload.
+ * @returns The markdown with the placeholder resolved.
+ */
+export const replacePlaceholder = (value: string, placeholder: string, replacement: string): string =>
+    value.includes(placeholder) ? value.replace(placeholder, () => replacement) : value;
diff --git a/Source/MarkdownEditor/replaceRange.ts b/Source/MarkdownEditor/replaceRange.ts
new file mode 100644
index 00000000..76705a2f
--- /dev/null
+++ b/Source/MarkdownEditor/replaceRange.ts
@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { MarkdownTextEdit } from './MarkdownTextEdit';
+
+/**
+ * Replaces the text between two positions, leaving the caret right after what was put in.
+ * An empty range (`start === end`) is a plain insert at the caret.
+ * @param value The markdown being edited.
+ * @param start Where the replaced range starts.
+ * @param end Where the replaced range ends.
+ * @param text The text to put in its place.
+ * @returns The edited markdown and the caret position after it.
+ */
+export const replaceRange = (value: string, start: number, end: number, text: string): MarkdownTextEdit => {
+    const caret = start + text.length;
+    return {
+        value: `${value.slice(0, start)}${text}${value.slice(end)}`,
+        selectionStart: caret,
+        selectionEnd: caret,
+    };
+};
diff --git a/Source/MarkdownEditor/toggleCodeBlock.ts b/Source/MarkdownEditor/toggleCodeBlock.ts
new file mode 100644
index 00000000..41e34dbf
--- /dev/null
+++ b/Source/MarkdownEditor/toggleCodeBlock.ts
@@ -0,0 +1,42 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { MarkdownTextEdit } from './MarkdownTextEdit';
+import { lineBlockAround } from './lineBlockAround';
+
+const fence = '```';
+
+/**
+ * Fences the lines the selection touches in a code block, or takes the fences off when those lines
+ * already open and close one.
+ * @param value The markdown being edited.
+ * @param start Where the selection starts.
+ * @param end Where the selection ends.
+ * @returns The edited markdown and the selection after it.
+ */
+export const toggleCodeBlock = (value: string, start: number, end: number): MarkdownTextEdit => {
+    const block = lineBlockAround(value, start, end);
+    const before = value.slice(0, block.start);
+    const after = value.slice(block.end);
+    const lines = block.lines;
+    const fenced = lines.length >= 2 && lines[0].startsWith(fence) && lines[lines.length - 1].trim() === fence;
+
+    if (fenced) {
+        const inner = lines.slice(1, -1).join('\n');
+        return {
+            value: `${before}${inner}${after}`,
+            selectionStart: block.start,
+            selectionEnd: block.start + inner.length,
+        };
+    }
+
+    const inner = lines.join('\n');
+    const opening = `${fence}\n`;
+    const contentStart = block.start + opening.length;
+    const caretOffset = start === end ? start - block.start : 0;
+    return {
+        value: `${before}${opening}${inner}\n${fence}${after}`,
+        selectionStart: contentStart + caretOffset,
+        selectionEnd: start === end ? contentStart + caretOffset : contentStart + inner.length,
+    };
+};
diff --git a/Source/MarkdownEditor/toggleInlineMarker.ts b/Source/MarkdownEditor/toggleInlineMarker.ts
new file mode 100644
index 00000000..c86b61db
--- /dev/null
+++ b/Source/MarkdownEditor/toggleInlineMarker.ts
@@ -0,0 +1,46 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { MarkdownTextEdit } from './MarkdownTextEdit';
+
+/**
+ * Wraps the selection in an inline marker such as `**` or a backtick, or takes the marker off when
+ * the selection already carries it - either just outside the selection or as its first and last
+ * characters. The selection stays on the same text, so a second format can be applied straight after.
+ * @param value The markdown being edited.
+ * @param start Where the selection starts.
+ * @param end Where the selection ends.
+ * @param marker The marker to toggle.
+ * @returns The edited markdown and the selection after it.
+ */
+export const toggleInlineMarker = (value: string, start: number, end: number, marker: string): MarkdownTextEdit => {
+    const length = marker.length;
+    const selected = value.slice(start, end);
+
+    const markedOutside =
+        value.slice(start - length, start) === marker && value.slice(end, end + length) === marker;
+    if (markedOutside) {
+        return {
+            value: `${value.slice(0, start - length)}${selected}${value.slice(end + length)}`,
+            selectionStart: start - length,
+            selectionEnd: end - length,
+        };
+    }
+
+    const markedInside =
+        selected.length >= length * 2 && selected.startsWith(marker) && selected.endsWith(marker);
+    if (markedInside) {
+        const inner = selected.slice(length, selected.length - length);
+        return {
+            value: `${value.slice(0, start)}${inner}${value.slice(end)}`,
+            selectionStart: start,
+            selectionEnd: start + inner.length,
+        };
+    }
+
+    return {
+        value: `${value.slice(0, start)}${marker}${selected}${marker}${value.slice(end)}`,
+        selectionStart: start + length,
+        selectionEnd: end + length,
+    };
+};
diff --git a/Source/MarkdownEditor/toggleLinePrefix.ts b/Source/MarkdownEditor/toggleLinePrefix.ts
new file mode 100644
index 00000000..d6aed07b
--- /dev/null
+++ b/Source/MarkdownEditor/toggleLinePrefix.ts
@@ -0,0 +1,44 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { MarkdownTextEdit } from './MarkdownTextEdit';
+import { lineBlockAround } from './lineBlockAround';
+
+/**
+ * Puts a prefix such as `> ` or `- ` in front of every line the selection touches, or takes it off
+ * when every one of those lines already has it. A caret keeps its place in the text; a selection grows
+ * to cover the edited lines.
+ * @param value The markdown being edited.
+ * @param start Where the selection starts.
+ * @param end Where the selection ends.
+ * @param prefixFor Gives the prefix for the line at a position within the touched lines.
+ * @param existing Recognizes a line that already carries the prefix, and matches the prefix itself.
+ * @returns The edited markdown and the selection after it.
+ */
+export const toggleLinePrefix = (
+    value: string,
+    start: number,
+    end: number,
+    prefixFor: (lineIndex: number) => string,
+    existing: RegExp,
+): MarkdownTextEdit => {
+    const block = lineBlockAround(value, start, end);
+    const everyLinePrefixed = block.lines.every(line => existing.test(line));
+    const edited = everyLinePrefixed
+        ? block.lines.map(line => line.replace(existing, ''))
+        : block.lines.map((line, lineIndex) => `${prefixFor(lineIndex)}${line}`);
+    const editedBlock = edited.join('\n');
+    const result = `${value.slice(0, block.start)}${editedBlock}${value.slice(block.end)}`;
+
+    if (start === end) {
+        const shift = edited[0].length - block.lines[0].length;
+        const caret = Math.max(block.start, start + shift);
+        return { value: result, selectionStart: caret, selectionEnd: caret };
+    }
+
+    return {
+        value: result,
+        selectionStart: block.start,
+        selectionEnd: block.start + editedBlock.length,
+    };
+};
diff --git a/Source/MarkdownEditor/uploadPlaceholderFor.ts b/Source/MarkdownEditor/uploadPlaceholderFor.ts
new file mode 100644
index 00000000..179feb1e
--- /dev/null
+++ b/Source/MarkdownEditor/uploadPlaceholderFor.ts
@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The placeholder that stands where a file is going while it uploads.
+ *
+ * The text lands at the caret the moment a file is pasted or dropped, so the editor shows it took the
+ * file, keeps the position while several upload at once, and leaves something to point at when one
+ * fails.
+ * @param fileName The name of the file being uploaded.
+ * @returns The placeholder text.
+ */
+export const uploadPlaceholderFor = (fileName: string): string => `![Uploading ${fileName}…]()`;
diff --git a/Source/MarkdownEditor/useMarkdownCompletion.ts b/Source/MarkdownEditor/useMarkdownCompletion.ts
new file mode 100644
index 00000000..7f2e3f48
--- /dev/null
+++ b/Source/MarkdownEditor/useMarkdownCompletion.ts
@@ -0,0 +1,165 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useEffect, useRef, useState, type KeyboardEvent } from 'react';
+import type { MarkdownCompletion } from './MarkdownCompletion';
+import type { MarkdownCompletionMatch } from './MarkdownCompletionMatch';
+import type { MarkdownSuggestion } from './MarkdownSuggestion';
+import type { MarkdownTextEdit } from './MarkdownTextEdit';
+import { findCompletionMatch } from './findCompletionMatch';
+import { replaceRange } from './replaceRange';
+
+const defaultDebounce = 150;
+
+interface Answer {
+    session: string;
+    suggestions: readonly MarkdownSuggestion[];
+}
+
+/**
+ * The state of the completion being typed at the caret, as {@link useMarkdownCompletion} reports it.
+ */
+export interface MarkdownCompletionState {
+    /** The completion being typed, when there is one and it has not been dismissed. */
+    match?: MarkdownCompletionMatch;
+
+    /** The suggestions on offer. Empty while none are known. */
+    suggestions: readonly MarkdownSuggestion[];
+
+    /** Whether the suggestion list is open. */
+    isOpen: boolean;
+
+    /** The index of the highlighted suggestion, which Enter or Tab picks. */
+    activeIndex: number;
+
+    /** Highlights a suggestion, as the pointer moving onto it does. */
+    highlight: (index: number) => void;
+
+    /**
+     * Works out the markdown after picking a suggestion, and closes the list.
+     * @param suggestion The picked suggestion.
+     * @returns The edit to apply, or undefined when nothing is being completed.
+     */
+    choose: (suggestion: MarkdownSuggestion) => MarkdownTextEdit | undefined;
+
+    /**
+     * Handles the keys the open list owns: the arrows move the highlight, Enter and Tab pick, Escape
+     * dismisses the list until the person starts another completion.
+     * @param event The key event from the writing area.
+     * @returns The edit to apply when a suggestion was picked.
+     */
+    handleKeyDown: (event: KeyboardEvent<HTMLTextAreaElement>) => MarkdownTextEdit | undefined;
+}
+
+const sessionOf = (match: MarkdownCompletionMatch) => `${match.completionIndex}:${match.start}`;
+
+/**
+ * Tracks the completion being typed at the caret, asks it for suggestions once typing pauses, and
+ * drops answers that arrive for a query the person has already typed past.
+ * @param value The markdown being edited.
+ * @param selectionStart Where the selection starts.
+ * @param selectionEnd Where the selection ends. Completion only runs on a plain caret.
+ * @param completions The configured completions.
+ * @returns The {@link MarkdownCompletionState}.
+ */
+export const useMarkdownCompletion = (
+    value: string,
+    selectionStart: number,
+    selectionEnd: number,
+    completions: readonly MarkdownCompletion[],
+): MarkdownCompletionState => {
+    const [answer, setAnswer] = useState<Answer>();
+    const [activeIndex, setActiveIndex] = useState(0);
+    const [dismissedSession, setDismissedSession] = useState<string>();
+
+    const found =
+        completions.length > 0 && selectionStart === selectionEnd
+            ? findCompletionMatch(value, selectionStart, completions)
+            : undefined;
+    const session = found ? sessionOf(found) : undefined;
+    const match = found && session !== dismissedSession ? found : undefined;
+    const request = match ? `${sessionOf(match)}:${match.query}` : undefined;
+
+    // The completions are usually recreated on every render of the host; only the request decides
+    // when to ask again, and the ask reads whichever completion is current.
+    const matchRef = useRef(match);
+    matchRef.current = match;
+
+    useEffect(() => {
+        const current = matchRef.current;
+        if (!current) return;
+        const controller = new AbortController();
+        const requestSession = sessionOf(current);
+        const timeout = window.setTimeout(() => {
+            Promise.resolve()
+                .then(() => current.completion.suggest(current.query, { signal: controller.signal }))
+                .then(
+                    suggestions => {
+                        if (!controller.signal.aborted) setAnswer({ session: requestSession, suggestions });
+                    },
+                    () => {
+                        if (!controller.signal.aborted) setAnswer({ session: requestSession, suggestions: [] });
+                    },
+                );
+        }, current.completion.debounce ?? defaultDebounce);
+
+        return () => {
+            window.clearTimeout(timeout);
+            controller.abort();
+        };
+    }, [request]);
+
+    // A dismissal lasts until the trigger it dismissed is gone - typing it again starts afresh.
+    useEffect(() => {
+        if (session === undefined) setDismissedSession(undefined);
+    }, [session]);
+
+    // An answer from the same session stays on screen while the next one is asked for, so the list
+    // does not flicker on every keystroke.
+    const suggestions = match && answer?.session === sessionOf(match) ? answer.suggestions : [];
+    const isOpen = suggestions.length > 0;
+    const highlighted = Math.min(activeIndex, Math.max(suggestions.length - 1, 0));
+
+    useEffect(() => setActiveIndex(0), [answer]);
+
+    const choose = (suggestion: MarkdownSuggestion) => {
+        if (!match) return undefined;
+        setAnswer(undefined);
+        return replaceRange(value, match.start, match.end, suggestion.insertText);
+    };
+
+    const handleKeyDown = (event: KeyboardEvent<HTMLTextAreaElement>) => {
+        if (!isOpen || !match) return undefined;
+        switch (event.key) {
+            case 'ArrowDown':
+                event.preventDefault();
+                setActiveIndex((highlighted + 1) % suggestions.length);
+                return undefined;
+            case 'ArrowUp':
+                event.preventDefault();
+                setActiveIndex((highlighted - 1 + suggestions.length) % suggestions.length);
+                return undefined;
+            case 'Enter':
+            case 'Tab':
+                event.preventDefault();
+                return choose(suggestions[highlighted]);
+            case 'Escape':
+                event.preventDefault();
+                event.stopPropagation();
+                setDismissedSession(sessionOf(match));
+                return undefined;
+            default:
+                return undefined;
+        }
+    };
+
+    return {
+        match,
+        suggestions,
+        isOpen,
+        activeIndex: highlighted,
+        highlight: setActiveIndex,
+        choose,
+        handleKeyDown,
+    };
+};
diff --git a/Source/MarkdownEditor/useMarkdownUploads.ts b/Source/MarkdownEditor/useMarkdownUploads.ts
new file mode 100644
index 00000000..4033fa5f
--- /dev/null
+++ b/Source/MarkdownEditor/useMarkdownUploads.ts
@@ -0,0 +1,102 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useEffect, useRef, useState } from 'react';
+import { replacePlaceholder } from './replacePlaceholder';
+import { uploadPlaceholderFor } from './uploadPlaceholderFor';
+
+/**
+ * What {@link useMarkdownUploads} needs from the editor it uploads for.
+ */
+export interface MarkdownUploadsOptions {
+    /** Uploads one file and returns the markdown that stands for it. Omit to turn uploads off. */
+    uploadFile?: (file: File) => Promise<string>;
+
+    /** Told about a file whose upload failed; its placeholder has already been taken out again. */
+    onUploadFailed?: (file: File, error: unknown) => void;
+
+    /** Reads the markdown as it is right now, not as it was when an upload started. */
+    currentValue: () => string;
+
+    /** Puts text in at the caret. */
+    insertAtCaret: (text: string) => void;
+
+    /** Replaces the whole markdown. */
+    replaceValue: (value: string) => void;
+}
+
+/**
+ * The state of the uploads started from an editor, as {@link useMarkdownUploads} reports it.
+ */
+export interface MarkdownUploadsState {
+    /** Whether files can be uploaded at all. */
+    isEnabled: boolean;
+
+    /** The names of the files uploading right now, in the order they were added. */
+    uploading: readonly string[];
+
+    /**
+     * Uploads files, each behind a placeholder put in at the caret straight away.
+     * @param files The files to upload.
+     */
+    upload: (files: readonly File[]) => void;
+}
+
+/**
+ * Uploads pasted and dropped files. Every file gets its placeholder at the caret first, so several
+ * added at once keep their order wherever the caret wanders, and each placeholder is resolved by value
+ * when its upload answers - replaced by the returned markdown, or taken out when the upload fails.
+ * @param options The {@link MarkdownUploadsOptions}.
+ * @returns The {@link MarkdownUploadsState}.
+ */
+export const useMarkdownUploads = (options: MarkdownUploadsOptions): MarkdownUploadsState => {
+    const [uploading, setUploading] = useState<readonly string[]>([]);
+    const optionsRef = useRef(options);
+    const mounted = useRef(true);
+
+    useEffect(() => {
+        optionsRef.current = options;
+    });
+
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+        };
+    }, []);
+
+    const uploadOne = async (file: File, uploadFile: (file: File) => Promise<string>) => {
+        const placeholder = uploadPlaceholderFor(file.name);
+        optionsRef.current.insertAtCaret(`${placeholder}\n`);
+        setUploading(current => [...current, file.name]);
+
+        try {
+            const markup = await uploadFile(file);
+            if (mounted.current) {
+                optionsRef.current.replaceValue(replacePlaceholder(optionsRef.current.currentValue(), placeholder, markup));
+            }
+        } catch (error) {
+            if (mounted.current) {
+                const current = optionsRef.current.currentValue();
+                const inserted = current.includes(`${placeholder}\n`) ? `${placeholder}\n` : placeholder;
+                optionsRef.current.replaceValue(replacePlaceholder(current, inserted, ''));
+            }
+            optionsRef.current.onUploadFailed?.(file, error);
+        } finally {
+            if (mounted.current) {
+                setUploading(current => {
+                    const index = current.indexOf(file.name);
+                    return index === -1 ? current : [...current.slice(0, index), ...current.slice(index + 1)];
+                });
+            }
+        }
+    };
+
+    const upload = (files: readonly File[]) => {
+        const uploadFile = optionsRef.current.uploadFile;
+        if (!uploadFile) return;
+        void Promise.all(files.map(file => uploadOne(file, uploadFile)));
+    };
+
+    return { isEnabled: options.uploadFile !== undefined, uploading, upload };
+};
diff --git a/Source/api-surface.json b/Source/api-surface.json
index 6e8164d4..7cda5c1a 100644
--- a/Source/api-surface.json
+++ b/Source/api-surface.json
@@ -482,6 +482,22 @@
     "buildHistogram": "export declare function buildHistogram(values: number[], min: number, max: number, bucketCount: number, provided?: HistogramBucket[]): RenderedHistogramBucket[];",
     "useFilterState": "export declare function useFilterState(filters: FilterDefinition[] | undefined): UseFilterStateResult;"
   },
+  "./MarkdownEditor": {
+    "MarkdownCompletion": "export interface MarkdownCompletion { trigger: string | RegExp; allowSpaces?: boolean; minimumQueryLength?: number; debounce?: number; suggest: (query: string, context: MarkdownCompletionContext) => readonly MarkdownSuggestion[] | Promise<readonly MarkdownSuggestion[]>; label?: string; renderSuggestion?: (suggestion: MarkdownSuggestion) => ReactNode; }",
+    "MarkdownCompletionContext": "export interface MarkdownCompletionContext { signal: AbortSignal; }",
+    "MarkdownEditor": "MarkdownEditor: (props: MarkdownEditorProps) => import(\"react\").JSX.Element",
+    "MarkdownEditorLabels": "export interface MarkdownEditorLabels { editor?: string; toolbar?: string; bold?: string; italic?: string; strikethrough?: string; heading?: string; quote?: string; code?: string; codeBlock?: string; link?: string; bulletList?: string; numberedList?: string; taskList?: string; showPreview?: string; showMarkdown?: string; emptyPreview?: string; suggestions?: string; uploading?: (fileNames: readonly string[]) => string; }",
+    "MarkdownEditorMode": "export declare enum MarkdownEditorMode { Write = \"write\", Preview = \"preview\" }",
+    "MarkdownEditorPartAttributes": "export type MarkdownEditorPartAttributes<TElement> = HTMLAttributes<TElement> & { [attribute: `data-${string}`]: string | number | boolean | undefined; };",
+    "MarkdownEditorParts": "export interface MarkdownEditorParts { root?: MarkdownEditorPartAttributes<HTMLDivElement>; toolbar?: MarkdownEditorPartAttributes<HTMLDivElement>; format?: MarkdownEditorPartAttributes<HTMLButtonElement>; toggle?: MarkdownEditorPartAttributes<HTMLButtonElement>; textarea?: Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'value' | 'defaultValue' | 'onChange'> & { [attribute: `data-${string}`]: string | number | boolean | undefined; }; preview?: MarkdownEditorPartAttributes<HTMLDivElement>; status?: MarkdownEditorPartAttributes<HTMLDivElement>; suggestions?: MarkdownEditorPartAttributes<HTMLDivElement>; suggestion?: MarkdownEditorPartAttributes<HTMLDivElement>; }",
+    "MarkdownEditorProps": "export interface MarkdownEditorProps { value: string; onChange: (value: string) => void; onBlur?: () => void; placeholder?: string; height?: number | string; initialMode?: MarkdownEditorMode; autoFocus?: boolean; disabled?: boolean; readOnly?: boolean; invalid?: boolean; formats?: readonly (readonly MarkdownFormat[])[] | false; renderPreview?: (markdown: string) => ReactNode; completions?: readonly MarkdownCompletion[]; uploadFile?: (file: File) => Promise<string>; onUploadFailed?: (file: File, error: unknown) => void; labels?: MarkdownEditorLabels; id?: string; 'aria-label'?: string; 'aria-labelledby'?: string; 'aria-describedby'?: string; className?: string; pt?: MarkdownEditorParts; }",
+    "MarkdownFormat": "export declare enum MarkdownFormat { Bold = \"bold\", Italic = \"italic\", Strikethrough = \"strikethrough\", Heading = \"heading\", Quote = \"quote\", Code = \"code\", CodeBlock = \"codeBlock\", Link = \"link\", BulletList = \"bulletList\", NumberedList = \"numberedList\", TaskList = \"taskList\" }",
+    "MarkdownSuggestion": "export interface MarkdownSuggestion { id: string; insertText: string; label: string; detail?: string; annotation?: string; }",
+    "MarkdownTextEdit": "export interface MarkdownTextEdit { value: string; selectionStart: number; selectionEnd: number; }",
+    "applyMarkdownFormat": "applyMarkdownFormat: (value: string, selectionStart: number, selectionEnd: number, format: MarkdownFormat) => MarkdownTextEdit",
+    "defaultMarkdownEditorLabels": "defaultMarkdownEditorLabels: Required<MarkdownEditorLabels>",
+    "defaultMarkdownFormats": "defaultMarkdownFormats: readonly (readonly MarkdownFormat[])[]"
+  },
   "./Notifications": {
     "ToastCommandResultOptions": "export interface ToastCommandResultOptions { successTitle?: string; successDescription?: string; unauthorizedTitle?: string; validationTitle?: string; exceptionTitle?: string; showSuccess?: boolean; }",
     "ToastDispatch": "export interface ToastDispatch { show(options: ToastOptions): ToastId; update(id: ToastId, updates: Partial<ToastOptions>): ToastId; dismiss(id?: ToastId): void; promise<T>(promise: Promise<T>, options: ToastPromiseOptions<T>): Promise<T>; success(options: ToastOptions): ToastId; info(options: ToastOptions): ToastId; warn(options: ToastOptions): ToastId; error(options: ToastOptions): ToastId; secondary(options: ToastOptions): ToastId; contrast(options: ToastOptions): ToastId; }",
@@ -649,7 +665,7 @@
     "PartsOf": "export type PartsOf<K extends keyof CratisPartsManifest> = CratisPartsManifest[K][number];",
     "TypeFormat": "export interface TypeFormat { jsonType: string; format: string; }",
     "cratisCanonicalPartStates": "cratisCanonicalPartStates: readonly [ 'disabled', 'loading', 'selected', 'open', 'invalid', 'readonly', 'busy', 'focused', 'pressed' ]",
-    "cratisPartStates": "cratisPartStates: { readonly CheckboxField: { readonly root: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly input: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly box: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly indicator: readonly [ \"disabled\", \"selected\", \"invalid\" ]; }; readonly RatingField: { readonly root: readonly [ \"disabled\", \"invalid\" ]; readonly option: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly input: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly star: readonly [ \"disabled\", \"selected\", \"invalid\" ]; }; readonly RadioButtonField: { readonly root: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly input: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly box: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly indicator: readonly [ \"disabled\", \"selected\", \"invalid\" ]; }; readonly RadioGroupField: { readonly root: readonly [ \"disabled\", \"invalid\" ]; readonly option: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly input: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly box: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly indicator: readonly [ \"disabled\", \"selected\", \"invalid\" ]; }; readonly ChipsField: { readonly root: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly item: readonly [ \"selected\" ]; readonly remove: readonly [ \"disabled\", \"selected\" ]; readonly input: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; }; readonly ToggleSwitchField: { readonly root: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly input: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly control: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly handle: readonly [ \"disabled\", \"selected\", \"invalid\" ]; }; readonly SliderField: { readonly root: readonly [ \"disabled\", \"invalid\" ]; readonly input: readonly [ \"disabled\", \"invalid\" ]; readonly value: readonly [ \"invalid\" ]; }; readonly NumberField: { readonly root: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly input: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; }; readonly ComboBox: { readonly root: readonly [ \"disabled\", \"invalid\", \"readonly\", \"loading\" ]; readonly input: readonly [ \"disabled\", \"invalid\", \"readonly\", \"open\" ]; readonly trigger: readonly [ \"disabled\", \"open\" ]; readonly popover: readonly [ \"open\" ]; readonly listbox: readonly [ ]; readonly option: readonly [ \"disabled\", \"selected\" ]; readonly optionLabel: readonly [ ]; readonly optionDescription: readonly [ ]; readonly loading: readonly [ ]; readonly empty: readonly [ ]; readonly failure: readonly [ ]; readonly action: readonly [ ]; readonly description: readonly [ ]; readonly error: readonly [ \"invalid\" ]; }; readonly NumberInput: { readonly root: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly group: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly input: readonly [ \"disabled\", \"invalid\", \"readonly\", \"focused\" ]; readonly prefix: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly suffix: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly step: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly description: readonly [ ]; readonly error: readonly [ \"invalid\" ]; }; readonly NumberInputField: { readonly root: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly group: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly input: readonly [ \"disabled\", \"invalid\", \"readonly\", \"focused\" ]; readonly prefix: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly suffix: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly step: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly description: readonly [ ]; readonly error: readonly [ \"invalid\" ]; }; readonly ColorPickerField: { readonly root: readonly [ \"disabled\", \"invalid\" ]; readonly input: readonly [ \"disabled\", \"invalid\" ]; readonly value: readonly [ \"invalid\" ]; }; readonly PasswordField: { readonly root: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly input: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly toggle: readonly [ \"disabled\" ]; }; readonly InputTextField: { readonly input: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; }; readonly TextAreaField: { readonly textarea: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; }; readonly Dropdown: { readonly root: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\" ]; readonly value: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\" ]; readonly filter: readonly [ \"disabled\", \"open\", \"invalid\" ]; readonly trigger: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\" ]; readonly clear: readonly [ \"disabled\" ]; readonly popover: readonly [ \"open\" ]; readonly listbox: readonly [ \"open\" ]; readonly option: readonly [ \"disabled\", \"selected\" ]; readonly multiple: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly indicator: readonly [ \"disabled\", \"open\", \"invalid\" ]; }; readonly DropdownField: { readonly root: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\" ]; readonly value: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\" ]; readonly filter: readonly [ \"disabled\", \"open\", \"invalid\" ]; readonly trigger: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\" ]; readonly clear: readonly [ \"disabled\" ]; readonly popover: readonly [ \"open\" ]; readonly listbox: readonly [ \"open\" ]; readonly option: readonly [ \"disabled\", \"selected\" ]; readonly multiple: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly indicator: readonly [ \"disabled\", \"open\", \"invalid\" ]; }; readonly MultiSelectField: { readonly root: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\" ]; readonly value: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\" ]; readonly filter: readonly [ \"disabled\", \"open\", \"invalid\" ]; readonly trigger: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\" ]; readonly clear: readonly [ \"disabled\" ]; readonly popover: readonly [ \"open\" ]; readonly listbox: readonly [ \"open\" ]; readonly option: readonly [ \"disabled\", \"selected\" ]; readonly multiple: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly indicator: readonly [ \"disabled\", \"open\", \"invalid\" ]; }; readonly DatePickerInput: { readonly root: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\", \"readonly\" ]; readonly group: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\", \"readonly\" ]; readonly input: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\", \"readonly\" ]; readonly segment: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly placeholder: readonly [ ]; readonly trigger: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\", \"readonly\" ]; readonly popover: readonly [ \"open\" ]; readonly dialog: readonly [ \"open\" ]; readonly calendar: readonly [ \"open\" ]; readonly header: readonly [ ]; readonly previous: readonly [ ]; readonly heading: readonly [ ]; readonly next: readonly [ ]; readonly grid: readonly [ ]; readonly cell: readonly [ \"selected\" ]; readonly 'button-bar': readonly [ ]; readonly today: readonly [ \"disabled\" ]; readonly clear: readonly [ \"disabled\" ]; }; readonly CalendarField: { readonly root: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\", \"readonly\" ]; readonly group: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\", \"readonly\" ]; readonly input: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\", \"readonly\" ]; readonly segment: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly placeholder: readonly [ ]; readonly trigger: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\", \"readonly\" ]; readonly popover: readonly [ \"open\" ]; readonly dialog: readonly [ \"open\" ]; readonly calendar: readonly [ \"open\" ]; readonly header: readonly [ ]; readonly previous: readonly [ ]; readonly heading: readonly [ ]; readonly next: readonly [ ]; readonly grid: readonly [ ]; readonly cell: readonly [ \"selected\" ]; readonly 'button-bar': readonly [ ]; readonly today: readonly [ \"disabled\" ]; readonly clear: readonly [ \"disabled\" ]; }; readonly Button: { readonly root: readonly [ \"disabled\", \"loading\" ]; readonly spinner: readonly [ ]; readonly icon: readonly [ ]; readonly label: readonly [ ]; }; readonly ActionMenubar: { readonly root: readonly [ \"disabled\", \"loading\" ]; readonly spinner: readonly [ ]; readonly icon: readonly [ ]; readonly label: readonly [ ]; }; readonly IconButton: { readonly root: readonly [ \"disabled\", \"loading\" ]; readonly spinner: readonly [ ]; readonly icon: readonly [ ]; readonly label: readonly [ ]; }; readonly TextInput: { readonly root: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; }; readonly TextArea: { readonly root: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; }; readonly Checkbox: { readonly root: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; readonly input: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; readonly box: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; readonly indicator: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; readonly label: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; }; readonly Radio: { readonly root: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; readonly input: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; readonly box: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; readonly indicator: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; readonly label: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; }; readonly Switch: { readonly root: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; readonly input: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; readonly control: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; readonly handle: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; readonly label: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; }; readonly Surface: { readonly root: readonly [ ]; }; readonly Tooltip: { readonly trigger: readonly [ ]; readonly popup: readonly [ \"open\" ]; }; readonly ToggleGroup: { readonly root: readonly [ \"disabled\", \"invalid\" ]; readonly option: readonly [ \"selected\", \"disabled\", \"invalid\" ]; readonly icon: readonly [ ]; readonly label: readonly [ ]; }; readonly Tabs: { readonly root: readonly [ \"disabled\" ]; readonly list: readonly [ ]; readonly tab: readonly [ \"selected\", \"disabled\" ]; readonly panel: readonly [ \"selected\" ]; }; readonly TagGroup: { readonly root: readonly [ \"disabled\", \"invalid\" ]; readonly list: readonly [ ]; readonly tag: readonly [ \"disabled\" ]; readonly remove: readonly [ ]; readonly input: readonly [ \"invalid\" ]; }; readonly Breadcrumbs: { readonly root: readonly [ ]; readonly item: readonly [ \"selected\" ]; readonly link: readonly [ \"selected\" ]; readonly separator: readonly [ ]; }; readonly Dialog: { readonly backdrop: readonly [ \"open\", \"busy\" ]; readonly positioner: readonly [ \"open\", \"busy\" ]; readonly root: readonly [ \"open\", \"busy\" ]; readonly header: readonly [ ]; readonly title: readonly [ ]; readonly subtitle: readonly [ ]; readonly close: readonly [ \"disabled\", \"busy\" ]; readonly content: readonly [ \"open\", \"busy\" ]; readonly 'busy-scope': readonly [ \"busy\" ]; readonly footer: readonly [ ]; readonly confirm: readonly [ \"disabled\", \"busy\" ]; readonly cancel: readonly [ \"disabled\", \"busy\" ]; }; readonly CommandDialog: { readonly backdrop: readonly [ \"open\", \"busy\" ]; readonly positioner: readonly [ \"open\", \"busy\" ]; readonly root: readonly [ \"open\", \"busy\" ]; readonly header: readonly [ ]; readonly title: readonly [ ]; readonly subtitle: readonly [ ]; readonly close: readonly [ \"disabled\", \"busy\" ]; readonly content: readonly [ \"open\", \"busy\" ]; readonly 'busy-scope': readonly [ \"busy\" ]; readonly footer: readonly [ ]; readonly confirm: readonly [ \"disabled\", \"busy\" ]; readonly cancel: readonly [ \"disabled\", \"busy\" ]; }; readonly CommandStepper: { readonly root: readonly [ \"invalid\", \"busy\" ]; readonly list: readonly [ \"invalid\", \"busy\" ]; readonly step: readonly [ \"selected\", \"invalid\", \"busy\" ]; readonly header: readonly [ \"disabled\", \"selected\", \"invalid\", \"busy\" ]; readonly number: readonly [ \"selected\", \"invalid\", \"busy\" ]; readonly title: readonly [ \"selected\", \"invalid\", \"busy\" ]; readonly separator: readonly [ \"invalid\", \"busy\" ]; readonly panels: readonly [ \"invalid\", \"busy\" ]; readonly panel: readonly [ \"selected\", \"invalid\", \"busy\" ]; }; readonly DataTableCore: { readonly root: readonly [ \"busy\" ]; readonly search: readonly [ ]; readonly 'search-input': readonly [ ]; readonly 'table-container': readonly [ ]; readonly table: readonly [ ]; readonly head: readonly [ ]; readonly 'header-row': readonly [ ]; readonly 'header-cell': readonly [ \"selected\" ]; readonly 'header-content': readonly [ \"selected\" ]; readonly sort: readonly [ \"pressed\" ]; readonly 'select-all': readonly [ ]; readonly body: readonly [ ]; readonly 'empty-row': readonly [ ]; readonly 'empty-cell': readonly [ ]; readonly 'loading-row': readonly [ ]; readonly 'loading-cell': readonly [ ]; readonly 'failure-row': readonly [ ]; readonly 'failure-cell': readonly [ ]; readonly row: readonly [ \"selected\" ]; readonly cell: readonly [ \"selected\" ]; }; readonly DataTableForObservableQuery: { readonly root: readonly [ \"busy\" ]; readonly search: readonly [ ]; readonly 'search-input': readonly [ ]; readonly 'table-container': readonly [ ]; readonly table: readonly [ ]; readonly head: readonly [ ]; readonly 'header-row': readonly [ ]; readonly 'header-cell': readonly [ \"selected\" ]; readonly 'header-content': readonly [ \"selected\" ]; readonly sort: readonly [ \"pressed\" ]; readonly 'select-all': readonly [ ]; readonly body: readonly [ ]; readonly 'empty-row': readonly [ ]; readonly 'empty-cell': readonly [ ]; readonly 'loading-row': readonly [ ]; readonly 'loading-cell': readonly [ ]; readonly 'failure-row': readonly [ ]; readonly 'failure-cell': readonly [ ]; readonly row: readonly [ \"selected\" ]; readonly cell: readonly [ \"selected\" ]; }; readonly DataTableForQuery: { readonly root: readonly [ \"busy\" ]; readonly search: readonly [ ]; readonly 'search-input': readonly [ ]; readonly 'table-container': readonly [ ]; readonly table: readonly [ ]; readonly head: readonly [ ]; readonly 'header-row': readonly [ ]; readonly 'header-cell': readonly [ \"selected\" ]; readonly 'header-content': readonly [ \"selected\" ]; readonly sort: readonly [ \"pressed\" ]; readonly 'select-all': readonly [ ]; readonly body: readonly [ ]; readonly 'empty-row': readonly [ ]; readonly 'empty-cell': readonly [ ]; readonly 'loading-row': readonly [ ]; readonly 'loading-cell': readonly [ ]; readonly 'failure-row': readonly [ ]; readonly 'failure-cell': readonly [ ]; readonly row: readonly [ \"selected\" ]; readonly cell: readonly [ \"selected\" ]; }; readonly ColumnFilterMenu: { readonly 'filter-trigger': readonly [ \"selected\", \"open\", \"pressed\" ]; readonly 'filter-popover': readonly [ \"open\" ]; readonly 'filter-menu': readonly [ \"open\" ]; readonly 'filter-actions': readonly [ ]; }; readonly TablePaginator: { readonly root: readonly [ ]; readonly range: readonly [ ]; readonly info: readonly [ ]; }; readonly Toaster: { readonly region: readonly [ ]; readonly toast: readonly [ \"loading\", \"busy\" ]; readonly icon: readonly [ ]; readonly content: readonly [ \"loading\", \"busy\" ]; readonly title: readonly [ ]; readonly description: readonly [ ]; readonly close: readonly [ ]; readonly action: readonly [ ]; }; readonly EventsView: { readonly timeline: readonly [ ]; readonly event: readonly [ \"selected\" ]; readonly separator: readonly [ ]; readonly marker: readonly [ \"selected\" ]; readonly connector: readonly [ ]; readonly content: readonly [ ]; }; readonly ChatSidebar: { readonly backdrop: readonly [ \"selected\", \"open\" ]; readonly root: readonly [ \"selected\", \"open\" ]; readonly header: readonly [ ]; readonly back: readonly [ ]; readonly title: readonly [ ]; readonly close: readonly [ ]; readonly content: readonly [ ]; }; readonly Toolbar: { readonly root: readonly [ ]; }; readonly ToolbarButton: { readonly button: readonly [ \"selected\" ]; readonly icon: readonly [ ]; readonly label: readonly [ ]; }; readonly ToolbarFolder: { readonly 'toolbar-folder': readonly [ \"open\" ]; readonly 'toolbar-folder-trigger': readonly [ \"open\" ]; readonly 'toolbar-folder-panel': readonly [ \"open\" ]; }; readonly ToolbarFanOutItem: { readonly 'fanout-root': readonly [ \"open\" ]; readonly 'fanout-trigger': readonly [ \"open\" ]; readonly 'fanout-panel': readonly [ \"open\" ]; }; readonly ToolbarSeparator: { readonly 'toolbar-separator': readonly [ ]; }; readonly ToolbarSection: { readonly 'toolbar-section': readonly [ ]; readonly 'toolbar-context': readonly [ \"selected\" ]; }; readonly ToolbarGroup: { readonly 'toolbar-group': readonly [ ]; readonly 'toolbar-slot': readonly [ ]; readonly 'toolbar-slot-incoming': readonly [ ]; readonly 'toolbar-slot-outgoing': readonly [ ]; }; readonly ToolbarLayout: { readonly 'toolbar-layout': readonly [ ]; readonly 'toolbar-slot': readonly [ ]; readonly 'toolbar-slot-incoming': readonly [ ]; readonly 'toolbar-slot-outgoing': readonly [ ]; }; readonly Skeleton: { readonly root: readonly [ ]; }; readonly Message: { readonly root: readonly [ ]; readonly icon: readonly [ ]; readonly text: readonly [ ]; }; readonly Badge: { readonly root: readonly [ ]; }; readonly ProgressSpinner: { readonly root: readonly [ \"loading\", \"busy\" ]; readonly svg: readonly [ ]; readonly track: readonly [ ]; readonly range: readonly [ ]; }; readonly Avatar: { readonly root: readonly [ ]; readonly image: readonly [ ]; readonly fallback: readonly [ ]; }; readonly Tag: { readonly root: readonly [ ]; readonly icon: readonly [ ]; readonly label: readonly [ ]; }; readonly ProgressBar: { readonly root: readonly [ \"loading\", \"busy\" ]; readonly indicator: readonly [ ]; readonly label: readonly [ ]; }; readonly Chip: { readonly root: readonly [ ]; readonly icon: readonly [ ]; readonly label: readonly [ ]; readonly remove: readonly [ ]; }; }",
-    "cratisParts": "cratisParts: { readonly CheckboxField: readonly [ 'root', 'input', 'box', 'indicator' ]; readonly RatingField: readonly [ 'root', 'option', 'input', 'star' ]; readonly RadioButtonField: readonly [ 'root', 'input', 'box', 'indicator' ]; readonly RadioGroupField: readonly [ 'root', 'option', 'input', 'box', 'indicator' ]; readonly ChipsField: readonly [ 'root', 'item', 'remove', 'input' ]; readonly ToggleSwitchField: readonly [ 'root', 'input', 'control', 'handle' ]; readonly SliderField: readonly [ 'root', 'input', 'value' ]; readonly NumberField: readonly [ 'root', 'input' ]; readonly ComboBox: readonly [ 'root', 'input', 'trigger', 'popover', 'listbox', 'option', 'optionLabel', 'optionDescription', 'loading', 'empty', 'failure', 'action', 'description', 'error' ]; readonly NumberInput: readonly [ 'root', 'group', 'input', 'prefix', 'suffix', 'step', 'description', 'error' ]; readonly NumberInputField: readonly [ 'root', 'group', 'input', 'prefix', 'suffix', 'step', 'description', 'error' ]; readonly ColorPickerField: readonly [ 'root', 'input', 'value' ]; readonly PasswordField: readonly [ 'root', 'input', 'toggle' ]; readonly InputTextField: readonly [ 'input' ]; readonly TextAreaField: readonly [ 'textarea' ]; readonly Dropdown: readonly [ 'root', 'value', 'filter', 'trigger', 'clear', 'popover', 'listbox', 'option', 'multiple', 'indicator' ]; readonly DropdownField: readonly [ 'root', 'value', 'filter', 'trigger', 'clear', 'popover', 'listbox', 'option', 'multiple', 'indicator' ]; readonly MultiSelectField: readonly [ 'root', 'value', 'filter', 'trigger', 'clear', 'popover', 'listbox', 'option', 'multiple', 'indicator' ]; readonly DatePickerInput: readonly [ 'root', 'group', 'input', 'segment', 'placeholder', 'trigger', 'popover', 'dialog', 'calendar', 'header', 'previous', 'heading', 'next', 'grid', 'cell', 'button-bar', 'today', 'clear' ]; readonly CalendarField: readonly [ 'root', 'group', 'input', 'segment', 'placeholder', 'trigger', 'popover', 'dialog', 'calendar', 'header', 'previous', 'heading', 'next', 'grid', 'cell', 'button-bar', 'today', 'clear' ]; readonly Button: readonly [ 'root', 'spinner', 'icon', 'label' ]; readonly ActionMenubar: readonly [ 'root', 'spinner', 'icon', 'label' ]; readonly IconButton: readonly [ 'root', 'spinner', 'icon', 'label' ]; readonly TextInput: readonly [ 'root' ]; readonly TextArea: readonly [ 'root' ]; readonly Checkbox: readonly [ 'root', 'input', 'box', 'indicator', 'label' ]; readonly Radio: readonly [ 'root', 'input', 'box', 'indicator', 'label' ]; readonly Switch: readonly [ 'root', 'input', 'control', 'handle', 'label' ]; readonly Surface: readonly [ 'root' ]; readonly Tooltip: readonly [ 'trigger', 'popup' ]; readonly ToggleGroup: readonly [ 'root', 'option', 'icon', 'label' ]; readonly Tabs: readonly [ 'root', 'list', 'tab', 'panel' ]; readonly TagGroup: readonly [ 'root', 'list', 'tag', 'remove', 'input' ]; readonly Breadcrumbs: readonly [ 'root', 'item', 'link', 'separator' ]; readonly Dialog: readonly [ 'backdrop', 'positioner', 'root', 'header', 'title', 'subtitle', 'close', 'content', 'busy-scope', 'footer', 'confirm', 'cancel' ]; readonly CommandDialog: readonly [ 'backdrop', 'positioner', 'root', 'header', 'title', 'subtitle', 'close', 'content', 'busy-scope', 'footer', 'confirm', 'cancel' ]; readonly CommandStepper: readonly [ 'root', 'list', 'step', 'header', 'number', 'title', 'separator', 'panels', 'panel' ]; readonly DataTableCore: readonly [ 'root', 'search', 'search-input', 'table-container', 'table', 'head', 'header-row', 'header-cell', 'header-content', 'sort', 'select-all', 'body', 'empty-row', 'empty-cell', 'loading-row', 'loading-cell', 'failure-row', 'failure-cell', 'row', 'cell' ]; readonly DataTableForObservableQuery: readonly [ 'root', 'search', 'search-input', 'table-container', 'table', 'head', 'header-row', 'header-cell', 'header-content', 'sort', 'select-all', 'body', 'empty-row', 'empty-cell', 'loading-row', 'loading-cell', 'failure-row', 'failure-cell', 'row', 'cell' ]; readonly DataTableForQuery: readonly [ 'root', 'search', 'search-input', 'table-container', 'table', 'head', 'header-row', 'header-cell', 'header-content', 'sort', 'select-all', 'body', 'empty-row', 'empty-cell', 'loading-row', 'loading-cell', 'failure-row', 'failure-cell', 'row', 'cell' ]; readonly ColumnFilterMenu: readonly [ 'filter-trigger', 'filter-popover', 'filter-menu', 'filter-actions' ]; readonly TablePaginator: readonly [ 'root', 'range', 'info' ]; readonly Toaster: readonly [ 'region', 'toast', 'icon', 'content', 'title', 'description', 'close', 'action' ]; readonly EventsView: readonly [ 'timeline', 'event', 'separator', 'marker', 'connector', 'content' ]; readonly ChatSidebar: readonly [ 'backdrop', 'root', 'header', 'back', 'title', 'close', 'content' ]; readonly Toolbar: readonly [ 'root' ]; readonly ToolbarButton: readonly [ 'button', 'icon', 'label' ]; readonly ToolbarFolder: readonly [ 'toolbar-folder', 'toolbar-folder-trigger', 'toolbar-folder-panel' ]; readonly ToolbarFanOutItem: readonly [ 'fanout-root', 'fanout-trigger', 'fanout-panel' ]; readonly ToolbarSeparator: readonly [ 'toolbar-separator' ]; readonly ToolbarSection: readonly [ 'toolbar-section', 'toolbar-context' ]; readonly ToolbarGroup: readonly [ 'toolbar-group', 'toolbar-slot', 'toolbar-slot-incoming', 'toolbar-slot-outgoing' ]; readonly ToolbarLayout: readonly [ 'toolbar-layout', 'toolbar-slot', 'toolbar-slot-incoming', 'toolbar-slot-outgoing' ]; readonly Skeleton: readonly [ 'root' ]; readonly Message: readonly [ 'root', 'icon', 'text' ]; readonly Badge: readonly [ 'root' ]; readonly ProgressSpinner: readonly [ 'root', 'svg', 'track', 'range' ]; readonly Avatar: readonly [ 'root', 'image', 'fallback' ]; readonly Tag: readonly [ 'root', 'icon', 'label' ]; readonly ProgressBar: readonly [ 'root', 'indicator', 'label' ]; readonly Chip: readonly [ 'root', 'icon', 'label', 'remove' ]; }"
+    "cratisPartStates": "cratisPartStates: { readonly CheckboxField: { readonly root: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly input: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly box: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly indicator: readonly [ \"disabled\", \"selected\", \"invalid\" ]; }; readonly RatingField: { readonly root: readonly [ \"disabled\", \"invalid\" ]; readonly option: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly input: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly star: readonly [ \"disabled\", \"selected\", \"invalid\" ]; }; readonly RadioButtonField: { readonly root: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly input: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly box: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly indicator: readonly [ \"disabled\", \"selected\", \"invalid\" ]; }; readonly RadioGroupField: { readonly root: readonly [ \"disabled\", \"invalid\" ]; readonly option: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly input: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly box: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly indicator: readonly [ \"disabled\", \"selected\", \"invalid\" ]; }; readonly ChipsField: { readonly root: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly item: readonly [ \"selected\" ]; readonly remove: readonly [ \"disabled\", \"selected\" ]; readonly input: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; }; readonly ToggleSwitchField: { readonly root: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly input: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly control: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly handle: readonly [ \"disabled\", \"selected\", \"invalid\" ]; }; readonly SliderField: { readonly root: readonly [ \"disabled\", \"invalid\" ]; readonly input: readonly [ \"disabled\", \"invalid\" ]; readonly value: readonly [ \"invalid\" ]; }; readonly NumberField: { readonly root: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly input: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; }; readonly ComboBox: { readonly root: readonly [ \"disabled\", \"invalid\", \"readonly\", \"loading\" ]; readonly input: readonly [ \"disabled\", \"invalid\", \"readonly\", \"open\" ]; readonly trigger: readonly [ \"disabled\", \"open\" ]; readonly popover: readonly [ \"open\" ]; readonly listbox: readonly [ ]; readonly option: readonly [ \"disabled\", \"selected\" ]; readonly optionLabel: readonly [ ]; readonly optionDescription: readonly [ ]; readonly loading: readonly [ ]; readonly empty: readonly [ ]; readonly failure: readonly [ ]; readonly action: readonly [ ]; readonly description: readonly [ ]; readonly error: readonly [ \"invalid\" ]; }; readonly NumberInput: { readonly root: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly group: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly input: readonly [ \"disabled\", \"invalid\", \"readonly\", \"focused\" ]; readonly prefix: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly suffix: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly step: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly description: readonly [ ]; readonly error: readonly [ \"invalid\" ]; }; readonly NumberInputField: { readonly root: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly group: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly input: readonly [ \"disabled\", \"invalid\", \"readonly\", \"focused\" ]; readonly prefix: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly suffix: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly step: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly description: readonly [ ]; readonly error: readonly [ \"invalid\" ]; }; readonly ColorPickerField: { readonly root: readonly [ \"disabled\", \"invalid\" ]; readonly input: readonly [ \"disabled\", \"invalid\" ]; readonly value: readonly [ \"invalid\" ]; }; readonly PasswordField: { readonly root: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly input: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly toggle: readonly [ \"disabled\" ]; }; readonly InputTextField: { readonly input: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; }; readonly TextAreaField: { readonly textarea: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; }; readonly Dropdown: { readonly root: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\" ]; readonly value: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\" ]; readonly filter: readonly [ \"disabled\", \"open\", \"invalid\" ]; readonly trigger: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\" ]; readonly clear: readonly [ \"disabled\" ]; readonly popover: readonly [ \"open\" ]; readonly listbox: readonly [ \"open\" ]; readonly option: readonly [ \"disabled\", \"selected\" ]; readonly multiple: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly indicator: readonly [ \"disabled\", \"open\", \"invalid\" ]; }; readonly DropdownField: { readonly root: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\" ]; readonly value: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\" ]; readonly filter: readonly [ \"disabled\", \"open\", \"invalid\" ]; readonly trigger: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\" ]; readonly clear: readonly [ \"disabled\" ]; readonly popover: readonly [ \"open\" ]; readonly listbox: readonly [ \"open\" ]; readonly option: readonly [ \"disabled\", \"selected\" ]; readonly multiple: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly indicator: readonly [ \"disabled\", \"open\", \"invalid\" ]; }; readonly MultiSelectField: { readonly root: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\" ]; readonly value: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\" ]; readonly filter: readonly [ \"disabled\", \"open\", \"invalid\" ]; readonly trigger: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\" ]; readonly clear: readonly [ \"disabled\" ]; readonly popover: readonly [ \"open\" ]; readonly listbox: readonly [ \"open\" ]; readonly option: readonly [ \"disabled\", \"selected\" ]; readonly multiple: readonly [ \"disabled\", \"selected\", \"invalid\" ]; readonly indicator: readonly [ \"disabled\", \"open\", \"invalid\" ]; }; readonly DatePickerInput: { readonly root: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\", \"readonly\" ]; readonly group: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\", \"readonly\" ]; readonly input: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\", \"readonly\" ]; readonly segment: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly placeholder: readonly [ ]; readonly trigger: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\", \"readonly\" ]; readonly popover: readonly [ \"open\" ]; readonly dialog: readonly [ \"open\" ]; readonly calendar: readonly [ \"open\" ]; readonly header: readonly [ ]; readonly previous: readonly [ ]; readonly heading: readonly [ ]; readonly next: readonly [ ]; readonly grid: readonly [ ]; readonly cell: readonly [ \"selected\" ]; readonly 'button-bar': readonly [ ]; readonly today: readonly [ \"disabled\" ]; readonly clear: readonly [ \"disabled\" ]; }; readonly CalendarField: { readonly root: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\", \"readonly\" ]; readonly group: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\", \"readonly\" ]; readonly input: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\", \"readonly\" ]; readonly segment: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly placeholder: readonly [ ]; readonly trigger: readonly [ \"disabled\", \"selected\", \"open\", \"invalid\", \"readonly\" ]; readonly popover: readonly [ \"open\" ]; readonly dialog: readonly [ \"open\" ]; readonly calendar: readonly [ \"open\" ]; readonly header: readonly [ ]; readonly previous: readonly [ ]; readonly heading: readonly [ ]; readonly next: readonly [ ]; readonly grid: readonly [ ]; readonly cell: readonly [ \"selected\" ]; readonly 'button-bar': readonly [ ]; readonly today: readonly [ \"disabled\" ]; readonly clear: readonly [ \"disabled\" ]; }; readonly Button: { readonly root: readonly [ \"disabled\", \"loading\" ]; readonly spinner: readonly [ ]; readonly icon: readonly [ ]; readonly label: readonly [ ]; }; readonly ActionMenubar: { readonly root: readonly [ \"disabled\", \"loading\" ]; readonly spinner: readonly [ ]; readonly icon: readonly [ ]; readonly label: readonly [ ]; }; readonly IconButton: { readonly root: readonly [ \"disabled\", \"loading\" ]; readonly spinner: readonly [ ]; readonly icon: readonly [ ]; readonly label: readonly [ ]; }; readonly TextInput: { readonly root: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; }; readonly TextArea: { readonly root: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; }; readonly Checkbox: { readonly root: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; readonly input: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; readonly box: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; readonly indicator: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; readonly label: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; }; readonly Radio: { readonly root: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; readonly input: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; readonly box: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; readonly indicator: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; readonly label: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; }; readonly Switch: { readonly root: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; readonly input: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; readonly control: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; readonly handle: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; readonly label: readonly [ \"disabled\", \"selected\", \"invalid\", \"readonly\" ]; }; readonly Surface: { readonly root: readonly [ ]; }; readonly Tooltip: { readonly trigger: readonly [ ]; readonly popup: readonly [ \"open\" ]; }; readonly ToggleGroup: { readonly root: readonly [ \"disabled\", \"invalid\" ]; readonly option: readonly [ \"selected\", \"disabled\", \"invalid\" ]; readonly icon: readonly [ ]; readonly label: readonly [ ]; }; readonly Tabs: { readonly root: readonly [ \"disabled\" ]; readonly list: readonly [ ]; readonly tab: readonly [ \"selected\", \"disabled\" ]; readonly panel: readonly [ \"selected\" ]; }; readonly TagGroup: { readonly root: readonly [ \"disabled\", \"invalid\" ]; readonly list: readonly [ ]; readonly tag: readonly [ \"disabled\" ]; readonly remove: readonly [ ]; readonly input: readonly [ \"invalid\" ]; }; readonly Breadcrumbs: { readonly root: readonly [ ]; readonly item: readonly [ \"selected\" ]; readonly link: readonly [ \"selected\" ]; readonly separator: readonly [ ]; }; readonly Dialog: { readonly backdrop: readonly [ \"open\", \"busy\" ]; readonly positioner: readonly [ \"open\", \"busy\" ]; readonly root: readonly [ \"open\", \"busy\" ]; readonly header: readonly [ ]; readonly title: readonly [ ]; readonly subtitle: readonly [ ]; readonly close: readonly [ \"disabled\", \"busy\" ]; readonly content: readonly [ \"open\", \"busy\" ]; readonly 'busy-scope': readonly [ \"busy\" ]; readonly footer: readonly [ ]; readonly confirm: readonly [ \"disabled\", \"busy\" ]; readonly cancel: readonly [ \"disabled\", \"busy\" ]; }; readonly CommandDialog: { readonly backdrop: readonly [ \"open\", \"busy\" ]; readonly positioner: readonly [ \"open\", \"busy\" ]; readonly root: readonly [ \"open\", \"busy\" ]; readonly header: readonly [ ]; readonly title: readonly [ ]; readonly subtitle: readonly [ ]; readonly close: readonly [ \"disabled\", \"busy\" ]; readonly content: readonly [ \"open\", \"busy\" ]; readonly 'busy-scope': readonly [ \"busy\" ]; readonly footer: readonly [ ]; readonly confirm: readonly [ \"disabled\", \"busy\" ]; readonly cancel: readonly [ \"disabled\", \"busy\" ]; }; readonly CommandStepper: { readonly root: readonly [ \"invalid\", \"busy\" ]; readonly list: readonly [ \"invalid\", \"busy\" ]; readonly step: readonly [ \"selected\", \"invalid\", \"busy\" ]; readonly header: readonly [ \"disabled\", \"selected\", \"invalid\", \"busy\" ]; readonly number: readonly [ \"selected\", \"invalid\", \"busy\" ]; readonly title: readonly [ \"selected\", \"invalid\", \"busy\" ]; readonly separator: readonly [ \"invalid\", \"busy\" ]; readonly panels: readonly [ \"invalid\", \"busy\" ]; readonly panel: readonly [ \"selected\", \"invalid\", \"busy\" ]; }; readonly DataTableCore: { readonly root: readonly [ \"busy\" ]; readonly search: readonly [ ]; readonly 'search-input': readonly [ ]; readonly 'table-container': readonly [ ]; readonly table: readonly [ ]; readonly head: readonly [ ]; readonly 'header-row': readonly [ ]; readonly 'header-cell': readonly [ \"selected\" ]; readonly 'header-content': readonly [ \"selected\" ]; readonly sort: readonly [ \"pressed\" ]; readonly 'select-all': readonly [ ]; readonly body: readonly [ ]; readonly 'empty-row': readonly [ ]; readonly 'empty-cell': readonly [ ]; readonly 'loading-row': readonly [ ]; readonly 'loading-cell': readonly [ ]; readonly 'failure-row': readonly [ ]; readonly 'failure-cell': readonly [ ]; readonly row: readonly [ \"selected\" ]; readonly cell: readonly [ \"selected\" ]; }; readonly DataTableForObservableQuery: { readonly root: readonly [ \"busy\" ]; readonly search: readonly [ ]; readonly 'search-input': readonly [ ]; readonly 'table-container': readonly [ ]; readonly table: readonly [ ]; readonly head: readonly [ ]; readonly 'header-row': readonly [ ]; readonly 'header-cell': readonly [ \"selected\" ]; readonly 'header-content': readonly [ \"selected\" ]; readonly sort: readonly [ \"pressed\" ]; readonly 'select-all': readonly [ ]; readonly body: readonly [ ]; readonly 'empty-row': readonly [ ]; readonly 'empty-cell': readonly [ ]; readonly 'loading-row': readonly [ ]; readonly 'loading-cell': readonly [ ]; readonly 'failure-row': readonly [ ]; readonly 'failure-cell': readonly [ ]; readonly row: readonly [ \"selected\" ]; readonly cell: readonly [ \"selected\" ]; }; readonly DataTableForQuery: { readonly root: readonly [ \"busy\" ]; readonly search: readonly [ ]; readonly 'search-input': readonly [ ]; readonly 'table-container': readonly [ ]; readonly table: readonly [ ]; readonly head: readonly [ ]; readonly 'header-row': readonly [ ]; readonly 'header-cell': readonly [ \"selected\" ]; readonly 'header-content': readonly [ \"selected\" ]; readonly sort: readonly [ \"pressed\" ]; readonly 'select-all': readonly [ ]; readonly body: readonly [ ]; readonly 'empty-row': readonly [ ]; readonly 'empty-cell': readonly [ ]; readonly 'loading-row': readonly [ ]; readonly 'loading-cell': readonly [ ]; readonly 'failure-row': readonly [ ]; readonly 'failure-cell': readonly [ ]; readonly row: readonly [ \"selected\" ]; readonly cell: readonly [ \"selected\" ]; }; readonly ColumnFilterMenu: { readonly 'filter-trigger': readonly [ \"selected\", \"open\", \"pressed\" ]; readonly 'filter-popover': readonly [ \"open\" ]; readonly 'filter-menu': readonly [ \"open\" ]; readonly 'filter-actions': readonly [ ]; }; readonly TablePaginator: { readonly root: readonly [ ]; readonly range: readonly [ ]; readonly info: readonly [ ]; }; readonly Toaster: { readonly region: readonly [ ]; readonly toast: readonly [ \"loading\", \"busy\" ]; readonly icon: readonly [ ]; readonly content: readonly [ \"loading\", \"busy\" ]; readonly title: readonly [ ]; readonly description: readonly [ ]; readonly close: readonly [ ]; readonly action: readonly [ ]; }; readonly EventsView: { readonly timeline: readonly [ ]; readonly event: readonly [ \"selected\" ]; readonly separator: readonly [ ]; readonly marker: readonly [ \"selected\" ]; readonly connector: readonly [ ]; readonly content: readonly [ ]; }; readonly ChatSidebar: { readonly backdrop: readonly [ \"selected\", \"open\" ]; readonly root: readonly [ \"selected\", \"open\" ]; readonly header: readonly [ ]; readonly back: readonly [ ]; readonly title: readonly [ ]; readonly close: readonly [ ]; readonly content: readonly [ ]; }; readonly Toolbar: { readonly root: readonly [ ]; }; readonly ToolbarButton: { readonly button: readonly [ \"selected\" ]; readonly icon: readonly [ ]; readonly label: readonly [ ]; }; readonly ToolbarFolder: { readonly 'toolbar-folder': readonly [ \"open\" ]; readonly 'toolbar-folder-trigger': readonly [ \"open\" ]; readonly 'toolbar-folder-panel': readonly [ \"open\" ]; }; readonly ToolbarFanOutItem: { readonly 'fanout-root': readonly [ \"open\" ]; readonly 'fanout-trigger': readonly [ \"open\" ]; readonly 'fanout-panel': readonly [ \"open\" ]; }; readonly ToolbarSeparator: { readonly 'toolbar-separator': readonly [ ]; }; readonly ToolbarSection: { readonly 'toolbar-section': readonly [ ]; readonly 'toolbar-context': readonly [ \"selected\" ]; }; readonly ToolbarGroup: { readonly 'toolbar-group': readonly [ ]; readonly 'toolbar-slot': readonly [ ]; readonly 'toolbar-slot-incoming': readonly [ ]; readonly 'toolbar-slot-outgoing': readonly [ ]; }; readonly ToolbarLayout: { readonly 'toolbar-layout': readonly [ ]; readonly 'toolbar-slot': readonly [ ]; readonly 'toolbar-slot-incoming': readonly [ ]; readonly 'toolbar-slot-outgoing': readonly [ ]; }; readonly Skeleton: { readonly root: readonly [ ]; }; readonly Message: { readonly root: readonly [ ]; readonly icon: readonly [ ]; readonly text: readonly [ ]; }; readonly Badge: { readonly root: readonly [ ]; }; readonly ProgressSpinner: { readonly root: readonly [ \"loading\", \"busy\" ]; readonly svg: readonly [ ]; readonly track: readonly [ ]; readonly range: readonly [ ]; }; readonly Avatar: { readonly root: readonly [ ]; readonly image: readonly [ ]; readonly fallback: readonly [ ]; }; readonly Tag: { readonly root: readonly [ ]; readonly icon: readonly [ ]; readonly label: readonly [ ]; }; readonly ProgressBar: { readonly root: readonly [ \"loading\", \"busy\" ]; readonly indicator: readonly [ ]; readonly label: readonly [ ]; }; readonly Chip: { readonly root: readonly [ ]; readonly icon: readonly [ ]; readonly label: readonly [ ]; readonly remove: readonly [ ]; }; readonly MarkdownEditor: { readonly root: readonly [ \"disabled\", \"invalid\", \"readonly\", \"busy\" ]; readonly toolbar: readonly [ ]; readonly format: readonly [ \"disabled\" ]; readonly toggle: readonly [ \"pressed\" ]; readonly textarea: readonly [ \"disabled\", \"invalid\", \"readonly\" ]; readonly preview: readonly [ ]; readonly status: readonly [ ]; readonly suggestions: readonly [ ]; readonly suggestion: readonly [ \"selected\" ]; }; }",
+    "cratisParts": "cratisParts: { readonly CheckboxField: readonly [ 'root', 'input', 'box', 'indicator' ]; readonly RatingField: readonly [ 'root', 'option', 'input', 'star' ]; readonly RadioButtonField: readonly [ 'root', 'input', 'box', 'indicator' ]; readonly RadioGroupField: readonly [ 'root', 'option', 'input', 'box', 'indicator' ]; readonly ChipsField: readonly [ 'root', 'item', 'remove', 'input' ]; readonly ToggleSwitchField: readonly [ 'root', 'input', 'control', 'handle' ]; readonly SliderField: readonly [ 'root', 'input', 'value' ]; readonly NumberField: readonly [ 'root', 'input' ]; readonly ComboBox: readonly [ 'root', 'input', 'trigger', 'popover', 'listbox', 'option', 'optionLabel', 'optionDescription', 'loading', 'empty', 'failure', 'action', 'description', 'error' ]; readonly NumberInput: readonly [ 'root', 'group', 'input', 'prefix', 'suffix', 'step', 'description', 'error' ]; readonly NumberInputField: readonly [ 'root', 'group', 'input', 'prefix', 'suffix', 'step', 'description', 'error' ]; readonly ColorPickerField: readonly [ 'root', 'input', 'value' ]; readonly PasswordField: readonly [ 'root', 'input', 'toggle' ]; readonly InputTextField: readonly [ 'input' ]; readonly TextAreaField: readonly [ 'textarea' ]; readonly Dropdown: readonly [ 'root', 'value', 'filter', 'trigger', 'clear', 'popover', 'listbox', 'option', 'multiple', 'indicator' ]; readonly DropdownField: readonly [ 'root', 'value', 'filter', 'trigger', 'clear', 'popover', 'listbox', 'option', 'multiple', 'indicator' ]; readonly MultiSelectField: readonly [ 'root', 'value', 'filter', 'trigger', 'clear', 'popover', 'listbox', 'option', 'multiple', 'indicator' ]; readonly DatePickerInput: readonly [ 'root', 'group', 'input', 'segment', 'placeholder', 'trigger', 'popover', 'dialog', 'calendar', 'header', 'previous', 'heading', 'next', 'grid', 'cell', 'button-bar', 'today', 'clear' ]; readonly CalendarField: readonly [ 'root', 'group', 'input', 'segment', 'placeholder', 'trigger', 'popover', 'dialog', 'calendar', 'header', 'previous', 'heading', 'next', 'grid', 'cell', 'button-bar', 'today', 'clear' ]; readonly Button: readonly [ 'root', 'spinner', 'icon', 'label' ]; readonly ActionMenubar: readonly [ 'root', 'spinner', 'icon', 'label' ]; readonly IconButton: readonly [ 'root', 'spinner', 'icon', 'label' ]; readonly TextInput: readonly [ 'root' ]; readonly TextArea: readonly [ 'root' ]; readonly Checkbox: readonly [ 'root', 'input', 'box', 'indicator', 'label' ]; readonly Radio: readonly [ 'root', 'input', 'box', 'indicator', 'label' ]; readonly Switch: readonly [ 'root', 'input', 'control', 'handle', 'label' ]; readonly Surface: readonly [ 'root' ]; readonly Tooltip: readonly [ 'trigger', 'popup' ]; readonly ToggleGroup: readonly [ 'root', 'option', 'icon', 'label' ]; readonly Tabs: readonly [ 'root', 'list', 'tab', 'panel' ]; readonly TagGroup: readonly [ 'root', 'list', 'tag', 'remove', 'input' ]; readonly Breadcrumbs: readonly [ 'root', 'item', 'link', 'separator' ]; readonly Dialog: readonly [ 'backdrop', 'positioner', 'root', 'header', 'title', 'subtitle', 'close', 'content', 'busy-scope', 'footer', 'confirm', 'cancel' ]; readonly CommandDialog: readonly [ 'backdrop', 'positioner', 'root', 'header', 'title', 'subtitle', 'close', 'content', 'busy-scope', 'footer', 'confirm', 'cancel' ]; readonly CommandStepper: readonly [ 'root', 'list', 'step', 'header', 'number', 'title', 'separator', 'panels', 'panel' ]; readonly DataTableCore: readonly [ 'root', 'search', 'search-input', 'table-container', 'table', 'head', 'header-row', 'header-cell', 'header-content', 'sort', 'select-all', 'body', 'empty-row', 'empty-cell', 'loading-row', 'loading-cell', 'failure-row', 'failure-cell', 'row', 'cell' ]; readonly DataTableForObservableQuery: readonly [ 'root', 'search', 'search-input', 'table-container', 'table', 'head', 'header-row', 'header-cell', 'header-content', 'sort', 'select-all', 'body', 'empty-row', 'empty-cell', 'loading-row', 'loading-cell', 'failure-row', 'failure-cell', 'row', 'cell' ]; readonly DataTableForQuery: readonly [ 'root', 'search', 'search-input', 'table-container', 'table', 'head', 'header-row', 'header-cell', 'header-content', 'sort', 'select-all', 'body', 'empty-row', 'empty-cell', 'loading-row', 'loading-cell', 'failure-row', 'failure-cell', 'row', 'cell' ]; readonly ColumnFilterMenu: readonly [ 'filter-trigger', 'filter-popover', 'filter-menu', 'filter-actions' ]; readonly TablePaginator: readonly [ 'root', 'range', 'info' ]; readonly Toaster: readonly [ 'region', 'toast', 'icon', 'content', 'title', 'description', 'close', 'action' ]; readonly EventsView: readonly [ 'timeline', 'event', 'separator', 'marker', 'connector', 'content' ]; readonly ChatSidebar: readonly [ 'backdrop', 'root', 'header', 'back', 'title', 'close', 'content' ]; readonly Toolbar: readonly [ 'root' ]; readonly ToolbarButton: readonly [ 'button', 'icon', 'label' ]; readonly ToolbarFolder: readonly [ 'toolbar-folder', 'toolbar-folder-trigger', 'toolbar-folder-panel' ]; readonly ToolbarFanOutItem: readonly [ 'fanout-root', 'fanout-trigger', 'fanout-panel' ]; readonly ToolbarSeparator: readonly [ 'toolbar-separator' ]; readonly ToolbarSection: readonly [ 'toolbar-section', 'toolbar-context' ]; readonly ToolbarGroup: readonly [ 'toolbar-group', 'toolbar-slot', 'toolbar-slot-incoming', 'toolbar-slot-outgoing' ]; readonly ToolbarLayout: readonly [ 'toolbar-layout', 'toolbar-slot', 'toolbar-slot-incoming', 'toolbar-slot-outgoing' ]; readonly Skeleton: readonly [ 'root' ]; readonly Message: readonly [ 'root', 'icon', 'text' ]; readonly Badge: readonly [ 'root' ]; readonly ProgressSpinner: readonly [ 'root', 'svg', 'track', 'range' ]; readonly Avatar: readonly [ 'root', 'image', 'fallback' ]; readonly Tag: readonly [ 'root', 'icon', 'label' ]; readonly ProgressBar: readonly [ 'root', 'indicator', 'label' ]; readonly Chip: readonly [ 'root', 'icon', 'label', 'remove' ]; readonly MarkdownEditor: readonly [ 'root', 'toolbar', 'format', 'toggle', 'textarea', 'preview', 'status', 'suggestions', 'suggestion' ]; }"
   }
 }
diff --git a/Source/package.json b/Source/package.json
index 22192f09..a8fbb1b9 100644
--- a/Source/package.json
+++ b/Source/package.json
@@ -122,6 +122,11 @@
             "import": "./dist/esm/Filter/index.js"
         },
         "./Filter/styles": "./dist/esm/styles.Filter.css",
+        "./MarkdownEditor": {
+            "types": "./dist/esm/MarkdownEditor/index.d.ts",
+            "import": "./dist/esm/MarkdownEditor/index.js"
+        },
+        "./MarkdownEditor/styles": "./dist/esm/styles.MarkdownEditor.css",
         "./Notifications": {
             "types": "./dist/esm/Notifications/index.d.ts",
             "import": "./dist/esm/Notifications/index.js"
diff --git a/Source/scripts/export-inventory.json b/Source/scripts/export-inventory.json
index 04a12299..76045d3b 100644
--- a/Source/scripts/export-inventory.json
+++ b/Source/scripts/export-inventory.json
@@ -27,6 +27,8 @@
         "./Dropdown/styles",
         "./Filter",
         "./Filter/styles",
+        "./MarkdownEditor",
+        "./MarkdownEditor/styles",
         "./Notifications",
         "./Notifications/styles",
         "./ObjectContentEditor",
diff --git a/Source/scripts/generate-parts.mjs b/Source/scripts/generate-parts.mjs
index 4bb68918..4b05517e 100644
--- a/Source/scripts/generate-parts.mjs
+++ b/Source/scripts/generate-parts.mjs
@@ -555,6 +555,37 @@ export const partDefinitions = {
         parts: ['root', 'icon', 'label', 'remove'],
         sources: ['Display/Chip.tsx'],
     },
+    MarkdownEditor: {
+        parts: [
+            'root',
+            'toolbar',
+            'format',
+            'toggle',
+            'textarea',
+            'preview',
+            'status',
+            'suggestions',
+            'suggestion',
+        ],
+        sources: [
+            'MarkdownEditor/MarkdownEditor.tsx',
+            'MarkdownEditor/MarkdownToolbar.tsx',
+            'MarkdownEditor/MarkdownModeToggle.tsx',
+            'MarkdownEditor/MarkdownWritingArea.tsx',
+            'MarkdownEditor/MarkdownSuggestionList.tsx',
+        ],
+        ptKeys: [
+            'root',
+            'toolbar',
+            'format',
+            'toggle',
+            'textarea',
+            'preview',
+            'status',
+            'suggestions',
+            'suggestion',
+        ],
+    },
 };
 
 /** Canonical boolean state attributes supported by the stable-parts contract. */
@@ -921,6 +952,17 @@ export const partStateDefinitions = {
         label: [],
         remove: [],
     },
+    MarkdownEditor: {
+        root: ['disabled', 'invalid', 'readonly', 'busy'],
+        toolbar: [],
+        format: ['disabled'],
+        toggle: ['pressed'],
+        textarea: ['disabled', 'invalid', 'readonly'],
+        preview: [],
+        status: [],
+        suggestions: [],
+        suggestion: ['selected'],
+    },
 };
 
 /**
diff --git a/Source/scripts/parts-inventory.json b/Source/scripts/parts-inventory.json
index 14642fbf..c9a6b8e2 100644
--- a/Source/scripts/parts-inventory.json
+++ b/Source/scripts/parts-inventory.json
@@ -221,6 +221,15 @@
         "IconButton.root",
         "IconButton.spinner",
         "InputTextField.input",
+        "MarkdownEditor.format",
+        "MarkdownEditor.preview",
+        "MarkdownEditor.root",
+        "MarkdownEditor.status",
+        "MarkdownEditor.suggestion",
+        "MarkdownEditor.suggestions",
+        "MarkdownEditor.textarea",
+        "MarkdownEditor.toggle",
+        "MarkdownEditor.toolbar",
         "Message.icon",
         "Message.root",
         "Message.text",
@@ -613,6 +622,16 @@
         "InputTextField.input.disabled",
         "InputTextField.input.invalid",
         "InputTextField.input.readonly",
+        "MarkdownEditor.format.disabled",
+        "MarkdownEditor.root.busy",
+        "MarkdownEditor.root.disabled",
+        "MarkdownEditor.root.invalid",
+        "MarkdownEditor.root.readonly",
+        "MarkdownEditor.suggestion.selected",
+        "MarkdownEditor.textarea.disabled",
+        "MarkdownEditor.textarea.invalid",
+        "MarkdownEditor.textarea.readonly",
+        "MarkdownEditor.toggle.pressed",
         "MultiSelectField.clear.disabled",
         "MultiSelectField.filter.disabled",
         "MultiSelectField.filter.invalid",
@@ -867,6 +886,7 @@
         "DataTables/TablePaginator.tsx#TablePaginatorProps",
         "Dialogs/Dialog.tsx#DialogProps",
         "Dropdown/Dropdown.tsx#DropdownProps",
+        "MarkdownEditor/MarkdownEditor.tsx#MarkdownEditorProps",
         "Notifications/Toaster.tsx#ToastFrameProps",
         "Notifications/Toaster.tsx#ToasterProps",
         "TimeMachine/EventsView.tsx#EventsViewProps",
diff --git a/Source/styles.css b/Source/styles.css
index f2f0bfe5..0bfd674a 100644
--- a/Source/styles.css
+++ b/Source/styles.css
@@ -66,6 +66,7 @@
 @import './Display/Display.css';
 @import './Dropdown/Dropdown.css';
 @import './Filter/FilterPanel.css';
+@import './MarkdownEditor/MarkdownEditor.css';
 @import './Notifications/Toaster.css';
 @import './ObjectNavigationalBar/ObjectNavigationalBar.css';
 @import './PivotViewer/PivotViewer.css';
diff --git a/Source/types/parts.ts b/Source/types/parts.ts
index a3eb53e4..25589922 100644
--- a/Source/types/parts.ts
+++ b/Source/types/parts.ts
@@ -66,6 +66,7 @@ export const cratisParts = {
     Tag: ['root', 'icon', 'label'],
     ProgressBar: ['root', 'indicator', 'label'],
     Chip: ['root', 'icon', 'label', 'remove'],
+    MarkdownEditor: ['root', 'toolbar', 'format', 'toggle', 'textarea', 'preview', 'status', 'suggestions', 'suggestion'],
 } as const;
 
 /** The canonical Components part-name manifest. */
@@ -554,6 +555,17 @@ export const cratisPartStates = {
         'label': [],
         'remove': [],
     },
+    MarkdownEditor: {
+        'root': ['disabled', 'invalid', 'readonly', 'busy'],
+        'toolbar': [],
+        'format': ['disabled'],
+        'toggle': ['pressed'],
+        'textarea': ['disabled', 'invalid', 'readonly'],
+        'preview': [],
+        'status': [],
+        'suggestions': [],
+        'suggestion': ['selected'],
+    },
 } as const satisfies {
     readonly [Component in keyof CratisPartsManifest]: {
         readonly [Part in PartsOf<Component>]: readonly CratisCanonicalPartState[];

From db2d38452226599c9608bc7e3296a1e947282b49 Mon Sep 17 00:00:00 2001
From: Einar <einari@me.com>
Date: Wed, 30 Sep 2026 20:00:15 +0200
Subject: [PATCH 2/4] Budget the MarkdownEditor stylesheet in the packed CSS
 gate

Give styles.MarkdownEditor.css its measured per-area ceiling, and move
the aggregate ceilings by what the editor's rules measured: raw to
210 KiB and gzip to 33 KiB. The aggregate had 54 gzip bytes of
headroom before the editor, whose rules were already cut to what they
need.
---
 Source/scripts/verify-package-archive.mjs | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/Source/scripts/verify-package-archive.mjs b/Source/scripts/verify-package-archive.mjs
index c7740e84..44cfa4da 100644
--- a/Source/scripts/verify-package-archive.mjs
+++ b/Source/scripts/verify-package-archive.mjs
@@ -277,10 +277,15 @@ const declarationBlocks = styles.match(/\{/gu)?.length ?? 0;
 // Measured after the query-state styles and grouping identical declarations within Canvas,
 // CommandForm, Common, Filter, PivotViewer, and Toolbar: raw 206066, gzip 32428, 1156
 // declaration blocks. The aggregate ceiling is unchanged; all per-area ceilings still hold.
+// Measured when MarkdownEditor's stylesheet joined: raw 213566, gzip 33398, 1196 declaration
+// blocks. The aggregate had 54 gzip bytes of headroom left before it, and the editor's rules had
+// already been cut to what they need (no comments, no transitions), so both ceilings move by the
+// measured amount - raw to 210 KiB, gzip to 33 KiB - rather than one stylesheet ending another's
+// ability to ship. A consumer that does not mount an editor imports per-area sheets and pays nothing.
 // Never group a :has() selector with others: a browser without :has() drops the whole list.
 const styleBudget = {
-    rawBytes: 205 * 1024,
-    gzipBytes: 32 * 1024,
+    rawBytes: 210 * 1024,
+    gzipBytes: 33 * 1024,
     declarationBlocks: 1200,
 };
 const exceeded = [
@@ -331,6 +336,7 @@ const areaStyleBudgets = new Map([
     ['styles.Display.css', 6144], // measured 5398
     ['styles.Dropdown.css', 6144], // measured 5481
     ['styles.Filter.css', 3584], // measured 2742
+    ['styles.MarkdownEditor.css', 2048], // measured 1377
     ['styles.Notifications.css', 5632], // measured 1099 (4988 before the configuration seam left Common/)
     ['styles.ObjectContentEditor.css', 5632], // measured 5049
     ['styles.ObjectNavigationalBar.css', 5120], // measured 4576

From 0db34ea46af783d827b440085cc193754a0602c6 Mon Sep 17 00:00:00 2001
From: Einar <einari@me.com>
Date: Wed, 30 Sep 2026 20:00:15 +0200
Subject: [PATCH 3/4] Add MarkdownEditor stories to the Storybook inventory

---
 .../MarkdownEditor/MarkdownEditor.stories.tsx | 140 ++++++++++++++++++
 Storybook/scripts/storybook-inventory.json    |   9 ++
 2 files changed, 149 insertions(+)
 create mode 100644 Source/MarkdownEditor/MarkdownEditor.stories.tsx

diff --git a/Source/MarkdownEditor/MarkdownEditor.stories.tsx b/Source/MarkdownEditor/MarkdownEditor.stories.tsx
new file mode 100644
index 00000000..27962eec
--- /dev/null
+++ b/Source/MarkdownEditor/MarkdownEditor.stories.tsx
@@ -0,0 +1,140 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useState, type ReactNode } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { expect, userEvent, waitFor, within } from 'storybook/test';
+import { MarkdownEditor, type MarkdownEditorProps } from './MarkdownEditor';
+import type { MarkdownCompletion } from './MarkdownCompletion';
+import type { MarkdownSuggestion } from './MarkdownSuggestion';
+import { MarkdownFormat } from './MarkdownFormat';
+
+const sampleMarkdown = `## Example Project
+
+Write **markdown** here and press the round button to see it rendered.
+
+- Paste or drop a file to upload it
+- Type \`#\` to reference an issue
+`;
+
+/**
+ * A deliberately small renderer for the stories: headings, list items and paragraphs as plain text.
+ * The editor ships no renderer - a host passes its own, sanitized one through `renderPreview`.
+ */
+const renderSample = (markdown: string): ReactNode => (
+    <div className='story-markdown-preview'>
+        {markdown.split('\n').filter(line => line.trim().length > 0).map((line, index) => {
+            const key = `${index}-${line}`;
+            if (line.startsWith('## ')) return <h3 key={key}>{line.slice(3)}</h3>;
+            if (line.startsWith('# ')) return <h2 key={key}>{line.slice(2)}</h2>;
+            if (line.startsWith('- ')) return <p key={key}>• {line.slice(2)}</p>;
+            return <p key={key}>{line}</p>;
+        })}
+    </div>
+);
+
+const sampleIssues: MarkdownSuggestion[] = [
+    { id: '101', insertText: 'example/project#101', label: 'Add sample export', detail: 'example/project#101', annotation: 'Issue' },
+    { id: '102', insertText: 'example/project#102', label: 'Fix sample import', detail: 'example/project#102', annotation: 'Pull request' },
+    { id: '103', insertText: 'example/project#103', label: 'Document sample settings', detail: 'example/project#103', annotation: 'Issue' },
+];
+
+const issueCompletion: MarkdownCompletion = {
+    trigger: '#',
+    allowSpaces: true,
+    label: 'Issues and pull requests',
+    suggest: query =>
+        new Promise(resolve =>
+            setTimeout(
+                () => resolve(sampleIssues.filter(issue => `${issue.id} ${issue.label}`.toLowerCase().includes(query.toLowerCase()))),
+                100,
+            ),
+        ),
+};
+
+const Editor = (props: Omit<MarkdownEditorProps, 'value' | 'onChange'> & { initialValue?: string }) => {
+    const { initialValue = sampleMarkdown, ...rest } = props;
+    const [value, setValue] = useState(initialValue);
+    return (
+        <div style={{ width: 'min(40rem, 90vw)' }}>
+            <MarkdownEditor {...rest} value={value} onChange={setValue} />
+        </div>
+    );
+};
+
+const meta = {
+    title: 'MarkdownEditor/MarkdownEditor',
+    component: Editor,
+    args: {
+        renderPreview: renderSample,
+        placeholder: 'Write markdown…',
+        'aria-label': 'Description',
+    },
+    parameters: { layout: 'centered' },
+} satisfies Meta<typeof Editor>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        await userEvent.click(canvas.getByRole('button', { name: 'Show preview' }));
+        await expect(await canvas.findByText('Example Project')).toBeTruthy();
+        await userEvent.click(canvas.getByRole('button', { name: 'Show markdown' }));
+        await expect(canvas.getByRole('textbox', { name: 'Description' })).toBeTruthy();
+    },
+};
+
+export const WithCompletion: Story = {
+    args: {
+        initialValue: 'Related to ',
+        completions: [issueCompletion],
+    },
+    play: async ({ canvasElement }) => {
+        const canvas = within(canvasElement);
+        const textbox = canvas.getByRole('textbox', { name: 'Description' });
+        await userEvent.click(textbox);
+        await userEvent.keyboard('{End}#export');
+        const body = within(canvasElement.ownerDocument.body);
+        await waitFor(() => expect(body.getByRole('listbox', { name: 'Issues and pull requests' })).toBeTruthy());
+        await userEvent.keyboard('{Enter}');
+        await waitFor(() => expect((textbox as HTMLTextAreaElement).value).toBe('Related to example/project#101'));
+    },
+};
+
+export const WithUploads: Story = {
+    args: {
+        initialValue: 'Paste or drop a file here.\n',
+        uploadFile: (file: File) =>
+            new Promise<string>(resolve =>
+                setTimeout(() => resolve(`[${file.name}](https://example.invalid/files/${encodeURIComponent(file.name)})`), 1500),
+            ),
+    },
+};
+
+export const WithSelectedFormats: Story = {
+    args: {
+        formats: [[MarkdownFormat.Bold, MarkdownFormat.Italic], [MarkdownFormat.Link]],
+    },
+};
+
+export const WithoutToolbar: Story = {
+    args: {
+        formats: false,
+        height: 160,
+    },
+};
+
+export const Invalid: Story = {
+    args: {
+        invalid: true,
+        initialValue: '',
+    },
+};
+
+export const ReadOnly: Story = {
+    args: {
+        readOnly: true,
+    },
+};
diff --git a/Storybook/scripts/storybook-inventory.json b/Storybook/scripts/storybook-inventory.json
index e54ecdc0..cc8334bc 100644
--- a/Storybook/scripts/storybook-inventory.json
+++ b/Storybook/scripts/storybook-inventory.json
@@ -65,6 +65,7 @@
         "filter-filterpanel--docs",
         "filter-filterpanel-in-dialog--docs",
         "filter-rangehistogramfilter--docs",
+        "markdowneditor-markdowneditor--docs",
         "notifications-toaster--docs",
         "objectcontenteditor-objectcontenteditor--docs",
         "objectnavigationalbar-objectnavigationalbar--docs",
@@ -579,6 +580,13 @@
         "filter-filterpanel-in-dialog--transformed-positioner",
         "filter-rangehistogramfilter--currency",
         "filter-rangehistogramfilter--interactive",
+        "markdowneditor-markdowneditor--default",
+        "markdowneditor-markdowneditor--invalid",
+        "markdowneditor-markdowneditor--read-only",
+        "markdowneditor-markdowneditor--with-completion",
+        "markdowneditor-markdowneditor--with-selected-formats",
+        "markdowneditor-markdowneditor--with-uploads",
+        "markdowneditor-markdowneditor--without-toolbar",
         "notifications-toaster--playground",
         "objectcontenteditor-objectcontenteditor--default",
         "objectcontenteditor-objectcontenteditor--edit-mode",
@@ -706,6 +714,7 @@
         "Source/Filter/FilterPanel.stories.tsx",
         "Source/Filter/FilterPanelInDialog.stories.tsx",
         "Source/Filter/RangeHistogramFilter.stories.tsx",
+        "Source/MarkdownEditor/MarkdownEditor.stories.tsx",
         "Source/Notifications/Toaster.stories.tsx",
         "Source/ObjectContentEditor/ObjectContentEditor.stories.tsx",
         "Source/ObjectNavigationalBar/ObjectNavigationalBar.stories.tsx",

From c0726b383a4ff14bda1fdcf6f1fc19524c376a66 Mon Sep 17 00:00:00 2001
From: Einar <einari@me.com>
Date: Wed, 30 Sep 2026 20:00:15 +0200
Subject: [PATCH 4/4] Document the MarkdownEditor

---
 Documentation/MarkdownEditor/index.md | 126 ++++++++++++++++++++++++++
 Documentation/MarkdownEditor/toc.yml  |   2 +
 Documentation/choosing-a-component.md |   1 +
 Documentation/toc.yml                 |   2 +
 4 files changed, 131 insertions(+)
 create mode 100644 Documentation/MarkdownEditor/index.md
 create mode 100644 Documentation/MarkdownEditor/toc.yml

diff --git a/Documentation/MarkdownEditor/index.md b/Documentation/MarkdownEditor/index.md
new file mode 100644
index 00000000..15358ec2
--- /dev/null
+++ b/Documentation/MarkdownEditor/index.md
@@ -0,0 +1,126 @@
+---
+title: MarkdownEditor
+description: Write markdown in one bordered box with a formatting toolbar, a preview toggle, configurable autocompletion, and file uploads.
+---
+
+`MarkdownEditor` is a controlled markdown editor: a formatting toolbar above the writing area, and a round toggle in the corner that swaps the whole box to the rendered preview. It fills the container it is given, completes whatever triggers you configure, and uploads pasted or dropped files through a callback you supply.
+
+## Basic usage
+
+```tsx
+import { useState } from 'react';
+import { MarkdownEditor } from '@cratis/components/MarkdownEditor';
+
+export function DescriptionEditor() {
+    const [description, setDescription] = useState('');
+
+    return (
+        <MarkdownEditor
+            value={description}
+            onChange={setDescription}
+            placeholder='Describe the change'
+            aria-label='Description'
+        />
+    );
+}
+```
+
+Import the stylesheet once, either the aggregate `@cratis/components/styles` or the area sheet `@cratis/components/MarkdownEditor/styles`.
+
+## Show a preview
+
+The editor ships no markdown renderer. Rendering, and which HTML is allowed through, belongs to your application, so pass the renderer you already use for read-only markdown through `renderPreview`. The toggle appears only when a renderer is given:
+
+```tsx
+<MarkdownEditor
+    value={description}
+    onChange={setDescription}
+    renderPreview={markdown => <MarkdownView source={markdown} />}
+/>
+```
+
+`renderPreview` is never called with empty markdown; the editor shows its `emptyPreview` label instead. Use `initialMode={MarkdownEditorMode.Preview}` to open on the preview.
+
+## Autocomplete a trigger
+
+A completion names what starts it and where its suggestions come from. The editor recognizes the trigger at the caret, waits for typing to pause, calls `suggest`, renders the list at the caret, and writes the picked suggestion's `insertText` over the trigger and the query:
+
+```tsx
+import type { MarkdownCompletion } from '@cratis/components/MarkdownEditor';
+
+const issues: MarkdownCompletion = {
+    trigger: '#',
+    allowSpaces: true,
+    label: 'Issues',
+    suggest: async (query, { signal }) => {
+        const response = await fetch(`/api/issues?search=${encodeURIComponent(query)}`, { signal });
+        const found: { number: number; title: string }[] = await response.json();
+        return found.map(issue => ({
+            id: String(issue.number),
+            insertText: `#${issue.number}`,
+            label: issue.title,
+            detail: `#${issue.number}`,
+        }));
+    },
+};
+
+<MarkdownEditor value={body} onChange={setBody} completions={[issues]} />;
+```
+
+- A string `trigger` starts a completion at the start of a line or after whitespace. The query is what follows it on the same line; set `allowSpaces` to search by title rather than a single word.
+- A `RegExp` trigger is matched against the current line up to the caret. The whole match is replaced, and the query is the named group `query`, the first group, or the whole match. For example, `/(?<=^|\s)\[\[(?<query>[^\]]*)$/u` completes `[[` wiki links.
+- `suggest` may answer synchronously or with a promise. An answer for a query the person has typed past is dropped, the `signal` is aborted when the answer is no longer wanted, and a rejected answer closes the list.
+- `debounce` (default `150` milliseconds) and `minimumQueryLength` (default `0`) decide when to ask.
+- Each suggestion shows its `detail`, `label` and `annotation`. Use `renderSuggestion` to draw your own content.
+
+The arrow keys move the highlight, Enter or Tab picks it, and Escape dismisses the list until the trigger is typed again. Focus stays in the writing area throughout. The list opens above any dialog the editor sits in and is not hidden or dismissed by it.
+
+## Upload pasted and dropped files
+
+Give `uploadFile` to take over pasted and dropped files. The editor puts a placeholder at the caret straight away, calls `uploadFile`, and replaces the placeholder with the markdown it returns:
+
+```tsx
+<MarkdownEditor
+    value={body}
+    onChange={setBody}
+    uploadFile={async file => {
+        const response = await fetch('/api/files', { method: 'POST', body: file });
+        if (!response.ok) throw new Error(response.statusText);
+        const { url } = await response.json();
+        return file.type.startsWith('image/') ? `![${file.name}](${url})` : `[${file.name}](${url})`;
+    }}
+    onUploadFailed={file => notify(`Could not upload ${file.name}`)}
+/>
+```
+
+When the upload rejects, the placeholder is taken out again and `onUploadFailed` is told. A status line announces the files that are uploading, and the root carries `data-busy` while it shows.
+
+## Formatting
+
+The toolbar offers headings, bold, italic, strikethrough, quotes, inline code, code blocks, links, and bulleted, numbered and task lists. Every format is a toggle: applying it where it is already applied takes it off. Control+B, Control+I and Control+K (Command on macOS) apply bold, italic and a link. The toolbar is one Tab stop; the arrow keys, Home and End move between its buttons.
+
+Choose the formats, in groups, with `formats`, or pass `formats={false}` for no toolbar:
+
+```tsx
+import { MarkdownFormat } from '@cratis/components/MarkdownEditor';
+
+<MarkdownEditor
+    value={note}
+    onChange={setNote}
+    formats={[[MarkdownFormat.Bold, MarkdownFormat.Italic], [MarkdownFormat.Link]]}
+/>
+```
+
+The same edits are available without the editor through `applyMarkdownFormat(value, selectionStart, selectionEnd, format)`.
+
+## Size
+
+The editor fills the height of its container. When the container leaves its height to its content, the editor falls back to `height`, which is 320 pixels unless you pass another number of pixels or a CSS length. A long document scrolls inside the editor rather than growing it.
+
+## Labels and accessibility
+
+Every label has an English default and can be replaced through `labels`, including the toolbar buttons, the toggle, the empty preview, the suggestion list and the upload status. Name the writing area with `aria-label`, `aria-labelledby`, or a `<label htmlFor>` pointing at `id`. `invalid` sets `aria-invalid`, and `aria-describedby` can point at a validation message.
+
+## Styling
+
+Style the stable parts through `pt` or the `data-cratis-part` attributes: `root`, `toolbar`, `format`, `toggle`, `textarea`, `preview`, `status`, `suggestions` and `suggestion`. The root carries `data-disabled`, `data-invalid`, `data-readonly` and `data-busy`; the toggle carries `data-pressed` while the preview shows; the highlighted suggestion carries `data-selected`. Colors come from the `--cratis-*` tokens.
diff --git a/Documentation/MarkdownEditor/toc.yml b/Documentation/MarkdownEditor/toc.yml
new file mode 100644
index 00000000..a63055a0
--- /dev/null
+++ b/Documentation/MarkdownEditor/toc.yml
@@ -0,0 +1,2 @@
+- name: MarkdownEditor
+  href: index.md
diff --git a/Documentation/choosing-a-component.md b/Documentation/choosing-a-component.md
index 75dacf12..10d95d0d 100644
--- a/Documentation/choosing-a-component.md
+++ b/Documentation/choosing-a-component.md
@@ -20,6 +20,7 @@ The question is whether confirming the form **runs a command**, and whether it's
 | Collect data and return it **without** running a command   | [`Dialog`](./Dialogs/dialog.md)                           | A confirmation or data-entry dialog that hands values back to the caller. No command involved.        |
 | Edit ordinary local React state                            | [`Common` basic controls](./Common/basic-controls.md)      | Native text and choice controls expose semantic values without binding an Arc command.                 |
 | Select one or more values in ordinary local React state    | [`Dropdown`](./Dropdown/index.md)                         | Binds a value or array to local options without binding an Arc command.                               |
+| Write markdown with formatting, a preview, and completion   | [`MarkdownEditor`](./MarkdownEditor/index.md)             | A controlled editor with a toolbar, host-rendered preview, configurable triggers, and file uploads.   |
 
 Rule of thumb: **if confirming the dialog executes a generated command, it's a `CommandDialog`** (or its
 stepper variant). If it just gathers values and returns them, it's a `Dialog`. Never reach for
diff --git a/Documentation/toc.yml b/Documentation/toc.yml
index 0d82c424..223970e9 100644
--- a/Documentation/toc.yml
+++ b/Documentation/toc.yml
@@ -50,6 +50,8 @@
   href: Filter/toc.yml
 - name: Dropdown
   href: Dropdown/toc.yml
+- name: MarkdownEditor
+  href: MarkdownEditor/toc.yml
 - name: Display
   href: Display/toc.yml
 - name: Notifications