@charcuterie/ui 3.2.0 → 3.4.0

package/src/MarkdownEditor/markdownCommands.test.ts

@@ -7,12 +7,14 @@ import {
   insertImage,
   insertLink,
   insertText,
+  isLinkPaste,
   MARKDOWN_LINE_PREFIXES,
   outdentLines,
   toggleHeading,
   toggleInlineMarker,
   toggleLinePrefix,
   toMarkdownImage,
+  wrapSelectionInLink,
 } from "./markdownCommands.ts"
 
 const at = (text: string, marker = "|") => {
@@ -382,3 +384,56 @@ test("the minimal edit is the smallest range that explains the change", () => {
     text: "",
   })
 })
+
+/**
+ * Pasting a URL over selected text is what every editor the owner
+ * uses already does, and its absence is why a link pasted into a
+ * Docket description stayed flat text.
+ */
+test("a URL pasted over a selection wraps it", () => {
+  expect(
+    wrapSelectionInLink(
+      at("see |the docs| now"),
+      "https://example.com",
+    ),
+  ).toEqual({
+    // After the whole insertion, not inside the destination: the
+    // URL is already known, so parking the caret in it would ask
+    // the user to replace what they just pasted.
+    selectionEnd: 35,
+    selectionStart: 35,
+    text: "see [the docs](https://example.com) now",
+  })
+})
+
+test("a URL pasted with no selection is inserted plainly", () => {
+  // Autolink renders a bare URL as a link anyway, so wrapping it
+  // with no text would produce `[](url)` — an empty link.
+  expect(
+    wrapSelectionInLink(
+      at("see | now"),
+      "https://example.com",
+    ),
+  ).toEqual({
+    selectionEnd: 23,
+    selectionStart: 23,
+    text: "see https://example.com now",
+  })
+})
+
+test.each([
+  ["https://example.com", true],
+  ["http://example.com/a?b=c#d", true],
+  ["  https://example.com  ", true],
+  ["not a url", false],
+  ["", false],
+  // Deliberately strict: a paste that is only *mostly* a URL is
+  // left alone, because mangling a literal paste is worse than
+  // not linkifying one.
+  ["see https://example.com", false],
+  ["https://a.com https://b.com", false],
+  ["mailto:someone@example.com", false],
+  ["www.example.com", false],
+])("isLinkPaste(%j) is %s", (pasted, isExpected) => {
+  expect(isLinkPaste(pasted)).toBe(isExpected)
+})

package/src/MarkdownEditor/markdownCommands.ts

@@ -394,6 +394,66 @@ export const insertLink = (
   })
 }
 
+/**
+ * Does this pasted string want to become a link?
+ *
+ * Deliberately strict. A paste that is *mostly* a URL — a sentence
+ * with one in it, two URLs on two lines — is left alone, because
+ * the cost of guessing wrong is silently mangling something the
+ * user meant to paste literally. One absolute `http(s)` URL, no
+ * inner whitespace, nothing either side of it.
+ *
+ * `mailto:` and bare `www.` are excluded on the same principle:
+ * they are the cases where "did they mean a link?" genuinely has
+ * two answers.
+ */
+export const isLinkPaste = (pasted: string): boolean =>
+  /^https?:\/\/[^\s<>]+$/.test(pasted.trim())
+
+/**
+ * Paste a URL over selected text and get `[selected](url)`.
+ *
+ * Every editor the owner uses does this — Outline, Notion, Slack,
+ * GitHub — and its absence is why a link pasted into Docket stayed
+ * flat text nobody could click. It is the one paste behaviour worth
+ * intercepting, and it is still markdown in and markdown out.
+ *
+ * Unlike `insertLink`, the caret lands **after** the whole
+ * insertion rather than inside the destination: the URL is already
+ * known, so parking the selection in it would ask the user to
+ * replace what they just pasted.
+ *
+ * With an empty selection this is a plain insertion of the URL —
+ * autolink renders a bare URL as a link anyway, so wrapping it in
+ * `[](…)` with no text would produce an empty link instead.
+ */
+export const wrapSelectionInLink = (
+  state: MarkdownSelection,
+  url: string,
+): MarkdownSelection => {
+  const selected = state.text.slice(
+    state.selectionStart,
+    state.selectionEnd,
+  )
+
+  if (selected === "") {
+    return insertText(state, url)
+  }
+
+  const insertion = `[${selected}](${url})`
+
+  const caret = state.selectionStart + insertion.length
+
+  return replaceRange({
+    end: state.selectionEnd,
+    insertion,
+    selectionEnd: caret,
+    selectionStart: caret,
+    start: state.selectionStart,
+    text: state.text,
+  })
+}
+
 /**
  * What Enter should do inside a list, a task list or a blockquote —
  * or `null` when it should do the ordinary thing and the component

package/src/MarkdownEditor/markdownSpans.test.ts

@@ -215,3 +215,68 @@ test("the caret's line is found from its offset", () => {
 
   expect(toLineIndex(text, 9999)).toBe(2)
 })
+
+/**
+ * Gap 2 of Docket's markdown handoff. A URL pasted into a
+ * description used to tokenize as prose — no `url` span, nothing to
+ * paint, and indistinguishable from the words around it.
+ */
+test("a bare URL paints as a URL without being marked up", () => {
+  expect(
+    toInlineSpans("see https://example.com now"),
+  ).toEqual([
+    { kind: "plain", text: "see " },
+    { kind: "url", text: "https://example.com" },
+    { kind: "plain", text: " now" },
+  ])
+})
+
+test("a sentence's full stop is not part of the URL", () => {
+  expect(
+    toInlineSpans("read https://example.com/a."),
+  ).toEqual([
+    { kind: "plain", text: "read " },
+    { kind: "url", text: "https://example.com/a" },
+    { kind: "plain", text: "." },
+  ])
+})
+
+test("a parenthesised URL does not swallow the paren", () => {
+  expect(
+    toInlineSpans("(see https://example.com)"),
+  ).toEqual([
+    { kind: "plain", text: "(see " },
+    { kind: "url", text: "https://example.com" },
+    { kind: "plain", text: ")" },
+  ])
+})
+
+/**
+ * The destination inside an explicit link is already a `url` span
+ * emitted by the link rule, and the link rule runs first. If
+ * autolink won here, the `](` and `)` would stop being markers.
+ */
+test("an explicit link still tokenizes as a link", () => {
+  expect(
+    toInlineSpans("[docs](https://example.com)"),
+  ).toEqual([
+    { kind: "marker", text: "[" },
+    { kind: "link", text: "docs" },
+    { kind: "marker", text: "](" },
+    { kind: "url", text: "https://example.com" },
+    { kind: "marker", text: ")" },
+  ])
+})
+
+/**
+ * Autolink runs before emphasis, which fixes a bug that predates
+ * it: the stretch between two underscores in a URL used to paint
+ * as italic text.
+ */
+test("underscores inside a URL are not emphasis", () => {
+  expect(
+    toInlineSpans("https://example.com/a_b_c"),
+  ).toEqual([
+    { kind: "url", text: "https://example.com/a_b_c" },
+  ])
+})

package/src/MarkdownEditor/markdownSpans.ts

@@ -121,8 +121,22 @@ const TASK_MARKER_PATTERN = /^\[[ xX]\][ \t]*/
  *  - **Image before link**, because `![alt](url)` starts with a
  *    valid link at index 1.
  *  - **Strong before emphasis**, because `**` starts with `*`.
+ *  - **Link before autolink**, because the `https://…` inside
+ *    `[text](https://…)` is a destination, not a bare URL, and
+ *    matching it as one would paint the parentheses as link text.
  */
 const INLINE_PATTERNS = {
+  /**
+   * A bare URL, as GFM autolinks it.
+   *
+   * Trailing punctuation is excluded from the match rather than
+   * trimmed after: `see https://example.com.` ends a sentence, and
+   * the full stop belongs to the prose. The closing paren is
+   * likewise left out so `(see https://example.com)` does not
+   * swallow it — at the cost of clipping a URL that genuinely ends
+   * in one, which is the rarer and less annoying failure.
+   */
+  autolink: /https?:\/\/[^\s<>[\]()]+[^\s<>[\]().,;:!?'"]/y,
   code: /(`+)([^\n]*?)\1/y,
   emphasis: /([*_])(?=[^\s*_])([^\n*_]*?[^\s*_])\1/y,
   escape: /\\([\\`*_{}[\]()#+\-.!>~|])/y,
@@ -243,6 +257,27 @@ export const toInlineSpans = (
       continue
     }
 
+    INLINE_PATTERNS.autolink.lastIndex = index
+
+    const autolinked = INLINE_PATTERNS.autolink.exec(text)
+
+    if (autolinked) {
+      // One span, no markers — there is no syntax to dim, because
+      // the user typed none. It paints as a URL so that a pasted
+      // link reads as a link, which is the whole complaint this
+      // answers: a URL dropped into a description used to be
+      // indistinguishable from prose.
+      //
+      // Running before `emphasis` also fixes a bug nobody filed:
+      // a URL with two underscores in it used to italicise the
+      // stretch between them.
+      pushSpan(spans, "url", autolinked[0])
+
+      index += autolinked[0].length
+
+      continue
+    }
+
     INLINE_PATTERNS.strong.lastIndex = index
 
     const strong = INLINE_PATTERNS.strong.exec(text)

package/src/Select/Select.mdx

@@ -4,7 +4,33 @@ import * as SelectStories from "./Select.stories";
 
 <Meta of={SelectStories} />
 
-# Select
+# Select (deprecated)
+
+> **Deprecated 2026-08-20. Nothing new gets a native `Select`.**
+>
+> Use **`Picker`** — a `Listbox` with the trigger already attached, and a near drop-in for
+> this component — or **`Combobox`** when the list is long enough to want typing.
+>
+> ```tsx
+> // Before.
+> <Select label="Quality" onChange={setQuality} options={QUALITY_OPTIONS} value={quality} />
+>
+> // After.
+> <Picker label="Quality" onChange={setQuality} options={QUALITY_OPTIONS} value={quality} />
+> ```
+>
+> The [2026-08-10 demotion](https://github.com/Sawtaytoes/charcuterie/blob/master/docs/decisions/2026-08-10-listbox-and-combobox-are-the-default-and-select-is-demoted.md)
+> left four platform cases where native was still the right call — the mobile wheel picker,
+> autofill, `:invalid`, and a form that posts with no JS. **Not one of them has ever applied
+> to an app in this fleet**, and the exception is what agents kept reading as permission. It
+> is closed: a new native `Select` is a new decision with the reason written down, not a
+> call-site choice. `Listbox` has no `<optgroup>` equivalent, and that gap is a change to
+> `Listbox` rather than a reason to keep this.
+>
+> It stays exported so existing call sites keep compiling while they convert, and it will be
+> removed in the next major of `@charcuterie/ui`.
+
+Everything below is how the component works, for the call sites still on it.
 
 Eighteen sites in the fleet, and they split cleanly in two: **twelve native `<select>`s**
 that differ only in their Tailwind classes, and **six hand-rolled `role="listbox"`

package/src/Select/Select.stories.tsx

@@ -41,7 +41,12 @@ const GROUPED: SelectItem[] = [
 ]
 
 const meta = {
-  title: "Components/Select",
+  // `Deprecated/`, not `Components/`, and that is the whole point of
+  // moving it: the sidebar is the first place an agent looks for a
+  // picker, and a `Select` sitting between `Rail` and `Shell` reads
+  // as a component in good standing. Nothing new gets one — `Picker`
+  // is the drop-in. See the 2026-08-20 deprecation record.
+  title: "Deprecated/Select",
   component: Select,
   parameters: { layout: "padded" },
   argTypes: { size: controlSizeArgType },

package/src/Select/Select.tsx

@@ -12,20 +12,36 @@ import {
 } from "../intentStyles.ts"
 import { toClassName } from "../toClassName.ts"
 
+/**
+ * @deprecated Part of the deprecated native `Select`. The
+ * replacement shape is `PickerOption` / `ListboxItem`, whose
+ * `label` is a `ReactNode` rather than a `string`.
+ */
 export type SelectOption = {
   isDisabled?: boolean
   label: string
   value: string
 }
 
+/**
+ * @deprecated Part of the deprecated native `Select`. `Listbox`
+ * has **no `<optgroup>` equivalent**, so a grouped picker is the
+ * one shape this deprecation has no replacement for — an app that
+ * needs one is a change to `Listbox`, not a reason to keep
+ * reaching for the native control.
+ */
 export type SelectOptionGroup = {
   label: string
   options: readonly SelectOption[]
 }
 
+/** @deprecated Part of the deprecated native `Select`. */
 export type SelectItem = SelectOption | SelectOptionGroup
 
 /**
+ * @deprecated Part of the deprecated native `Select` — see the
+ * component's docblock. `PickerProps` is the replacement.
+ *
  * The HTML attributes are passed through, and that is not
  * convenience — it is what makes the `Field` slot work at all.
  *
@@ -95,8 +111,33 @@ const getIsGroup = (
 ): item is SelectOptionGroup => "options" in item
 
 /**
- * A styled native `<select>`, and the fleet's fourteen hand-rolled
- * ones collapse onto it.
+ * @deprecated Reach for `Picker` — a `Listbox` with the trigger
+ * already attached, and a near drop-in for this component
+ * (`label`, `options`, `value`, `onChange`) — or `Combobox` when
+ * the list is long enough to want typing.
+ *
+ * A styled native `<select>`, kept only so the call sites that
+ * already have one keep compiling while they are converted.
+ *
+ * ### Deprecated 2026-08-20, and the platform hatch is closed
+ *
+ * The 2026-08-10 record demoted this to a stated-reason exception
+ * and named four cases where the platform behaviour is the
+ * feature: the mobile wheel picker, autofill, `:invalid`, and a
+ * form that posts with no JS. **None of them has ever applied to
+ * an app in this fleet**, and the exception is what agents kept
+ * reading as permission — so the exception is gone. A new native
+ * `Select` is a new decision with the reason written down, not a
+ * call-site choice.
+ *
+ * The objection is that the popup is painted by the OS. No token,
+ * no class and no amount of `appearance-none` reaches inside it,
+ * so a fleet with any of these in it has two focus treatments, two
+ * hover treatments and two keyboard feels — which is the thing the
+ * library exists to stop.
+ *
+ * Everything below is how the component works, for the call sites
+ * still on it. It is not a reason to add one.
  *
  * ### Sizing: `className` is the wrapper, `controlClassName` is the select
  *

package/src/index.ts

@@ -298,6 +298,11 @@ export type {
   SegmentedItem,
 } from "./SegmentedControl/SegmentedControl.tsx"
 export { SegmentedControl } from "./SegmentedControl/SegmentedControl.tsx"
+// DEPRECATED 2026-08-20. `Select` is the native `<select>` and
+// nothing new gets one — `Picker` is the drop-in, `Combobox` when
+// the list wants typing. It stays exported so the fleet's existing
+// call sites keep compiling while they convert, and for no other
+// reason; see the decision record next to the component.
 export type {
   SelectItem,
   SelectOption,

package/src/markdownEditorCodeMirror/MarkdownEditorCodeMirror.mdx

@@ -0,0 +1,144 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as MarkdownEditorCodeMirrorStories from "./MarkdownEditorCodeMirror.stories";
+
+<Meta of={MarkdownEditorCodeMirrorStories} />
+
+# MarkdownEditorCodeMirror
+
+Obsidian-style live preview: markers conceal themselves once the caret leaves, headings are
+genuinely larger, images render in place, task boxes are real checkboxes — and the stored
+value is still markdown, byte for byte.
+
+It is **opt-in**, from a subpath:
+
+```tsx
+import { MarkdownEditorCodeMirror } from "@charcuterie/ui/markdown-editor-codemirror"
+```
+
+<Canvas of={MarkdownEditorCodeMirrorStories.Default} />
+
+## Props
+
+<Controls />
+
+## Which of the two editors you want
+
+`MarkdownEditor` is still the default, and most consumers should keep it.
+
+| | `MarkdownEditor` | `MarkdownEditorCodeMirror` |
+| --- | --- | --- |
+| Surface | `<textarea>` + painted layer | CodeMirror 6 |
+| New dependency | **none** | ~176 KB gz, optional peer |
+| Markers | dimmed, never hidden | **concealed** until the caret arrives |
+| Headings | weight and colour only | **actually larger** |
+| Images | shown as `![alt](url)` | **rendered in place** |
+| Tasks | shown as `- [ ]` | **checkbox you can click** |
+| Bare URLs | painted as a URL | **clickable link** |
+| Undo, IME, spellcheck | the platform's own | CodeMirror's |
+
+Take the subpath when the description field is a **primary** surface of the app and the
+bundle has room. Keep the default when it is one field on a form — a component library that
+makes every consumer install an editor core to render a description has made the wrong
+trade, and `castkit/packages/slatecast` has 60 KB gz of total budget to prove it.
+
+## Markdown is still the stored value
+
+This is the part worth being exact about, because "WYSIWYG" usually means the opposite.
+
+There is **no document model here and no serialiser**. CodeMirror's state holds the markdown
+*text*. Live preview is a set of decorations *over* that text: concealing `**` hides two
+characters that are still in the document, still in `onChange`, and still in whatever you
+save. Replacing `![alt](url)` with an image does not rewrite the line — move the caret into
+it and the markup is simply there again.
+
+That is why this is not TipTap or Lexical. An editor core inverts the relationship: its
+document model becomes authoritative and markdown becomes a lossy *export*, so any construct
+the serialiser does not know about is silently dropped or silently becomes HTML. Docket
+exists partly because HTML in a description field destroyed a previous tracker's data, and
+an editor core would have been the easier build and the one thing that could not be allowed.
+
+The [decision record][decision] has the measured bundle table and the full argument.
+
+[decision]: https://github.com/Sawtaytoes/charcuterie/blob/master/docs/decisions/2026-08-19-the-markdown-editor-is-a-textarea-with-a-painted-layer.md
+
+## Concealment is the caret's answer, not the parser's
+
+<Canvas of={MarkdownEditorCodeMirrorStories.CaretReveal} />
+
+A construct reveals its markers when the selection **touches** it, and hides them again when
+the selection leaves. Two consequences that are easy to mistake for bugs:
+
+- **An unfocused editor reveals nothing.** There is no caret in a document nobody is editing,
+  so the resting offset of `0` deliberately does not count as "inside" the first construct.
+  Without this, a description that opens with a heading rendered its `#` on load and no other
+  heading's.
+- **Reveal is per-construct, not per-line.** Two bold runs on one line reveal independently.
+
+## The "Markdown source" toggle
+
+<Canvas of={MarkdownEditorCodeMirrorStories.RawMode} />
+
+Nothing is concealed, nothing is replaced by a widget, no line is rescaled, and the surface
+switches to monospace — because a source view is code. The syntax stays **coloured**: the
+point of the toggle is to see the markup, not to lose the highlighting.
+
+It is a `Switch` rather than a toolbar button because it is state, not a verb, and a
+`ToolbarAction` renders a `Button` that announces nothing about being on.
+
+## What a mark does when it is hidden
+
+Not every marker conceals, and the rule is narrower than "block marks stay":
+
+> **A mark persists unless something else already says what it said.**
+
+A blockquote gets an accent bar down its inline start, so its `>` is redundant and hides. A
+fenced code block keeps its ` ``` ` and its language tag, because concealing them leaves a
+blank line at the top and bottom of the block that reads as a rendering bug. A list bullet
+stays, because hiding `-` turns an unordered list into indented prose — Obsidian substitutes
+a `•`, which means choosing a width, and this component has no business choosing one.
+
+## Clicking a link opens it
+
+Obsidian's behaviour, not VS Code's: where the markup is hidden, a link that looks like a
+link should act like one. Bare URLs count — GFM autolinks them, so a URL pasted into a
+description is clickable with nothing typed around it.
+
+The trade is real and worth stating: **you cannot click into link text to edit it.** Arrow in
+from either edge, or flip the Markdown source toggle, which is exactly what it is for.
+
+## Pasting
+
+- **An image** (or a drop) runs `onUploadImage` and inserts `![alt](url)` at the caret, then
+  renders it in place. The component does not own storage — it hands you a `File`.
+- **A URL over selected text** becomes `[selection](url)`, the way it does in every other
+  editor. Deliberately strict: one absolute `http(s)` URL and nothing else, because mangling
+  a literal paste is worse than not linkifying one.
+- **Anything else** is left to the browser.
+
+## Accessibility, and the honest cost
+
+The `<textarea>` sibling gets caret movement, IME composition, spellcheck, the platform undo
+stack and `role="textbox"` from the browser, tested by the vendors. A `contenteditable`
+re-earns every one of those, and CodeMirror is the reason that is acceptable rather than
+reckless — it is the most heavily exercised implementation of that re-earning there is. It is
+still a re-implementation, and that is what this subpath costs beyond its bytes.
+
+`Tab` is **never** captured, at any time. Indenting a list with Tab is the convention in
+editors that own the whole page, and inside a form it is a keyboard trap — WCAG 2.1.2 wants
+focus to leave every component with the standard gesture. Indent and outdent are `Ctrl+]` and
+`Ctrl+[`. `indentWithTab` is the extension that would change this, and it is deliberately not
+installed.
+
+<Canvas of={MarkdownEditorCodeMirrorStories.AllStates} />
+
+## It is uncontrolled
+
+`defaultValue` in, `onChange` out — the same contract as `Select` and as the sibling editor.
+An `EditorView` owns the caret, the selection, the scroll position and the undo history, and
+rebuilding it throws all four away, so the view is built exactly **once**. Props that can
+legitimately change afterwards reach it through a compartment (`isReadOnly`, `isDisabled`) or
+through a ref (the callbacks); the rest are frozen at mount.
+
+To swap documents — Docket opening a different task — remount with a `key`. That is one line,
+and it is honest about the old undo history belonging to the old document.

package/src/markdownEditorCodeMirror/MarkdownEditorCodeMirror.stories.tsx

@@ -0,0 +1,147 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import {
+  StoryCell,
+  StoryGrid,
+} from "../board.storyHelpers.tsx"
+import { Field } from "../Field/Field.tsx"
+import { MarkdownEditorCodeMirror } from "./MarkdownEditorCodeMirror.tsx"
+
+/**
+ * Invented, like every fixture in this repo — a task in a made-up
+ * homelab project, exercising each construct the live-preview layer
+ * knows about.
+ *
+ * The bare URL on the last line is the point of the whole exercise:
+ * nobody typed `[](…)` around it, and it is a link anyway.
+ */
+const SAMPLE = `# Rack move, phase two
+
+The **short** version: pull the _old_ switch, land the new one, and
+keep the ~~three~~ two uplinks live throughout.
+
+## Before the window
+
+- [x] Label every patch lead
+- [ ] Photograph the current cabling
+- [ ] Cut over at 02:00
+
+1. Power down the shelf
+2. Swap the rails
+3. Bring it back up
+
+> Nothing here touches the storage pool.
+
+Run \`ping -c 3 gateway.invalid\` before and after, and read
+[the runbook](https://example.invalid/runbook) first.
+
+| Port | Goes to |
+| --- | --- |
+| 1 | uplink |
+| 2 | shelf |
+
+\`\`\`sh
+ip -br addr show
+\`\`\`
+
+Replacement rails ordered from https://example.invalid/product?id=1234
+`
+
+const meta = {
+  title: "Components/MarkdownEditorCodeMirror",
+  component: MarkdownEditorCodeMirror,
+  parameters: { layout: "padded" },
+  args: {
+    isDisabled: false,
+    isReadOnly: false,
+    label: "Description",
+    placeholder: "Write it in markdown…",
+  },
+} satisfies Meta<typeof MarkdownEditorCodeMirror>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * The whole argument for this subpath, in one frame: the heading is
+ * genuinely larger, `**` is nowhere on screen, the checkboxes are
+ * checkboxes, and the bare URL is a link.
+ */
+export const Default: Story = {
+  args: {
+    defaultValue: SAMPLE,
+    label: "Description",
+  },
+}
+
+/**
+ * The "edit Markdown" toggle, flipped.
+ *
+ * Nothing is concealed and no line is rescaled — but the syntax is
+ * still coloured, because the point of the toggle is to see the
+ * markup, not to lose the highlighting.
+ */
+export const RawMode: Story = {
+  args: {
+    defaultValue: SAMPLE,
+    isRawModeDefault: true,
+    label: "Description",
+  },
+}
+
+export const AllStates: Story = {
+  args: { label: "Description" },
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell align="stretch" label="empty">
+        <MarkdownEditorCodeMirror
+          label="Empty description"
+          placeholder="Write it in markdown…"
+        />
+      </StoryCell>
+
+      <StoryCell align="stretch" label="read only">
+        <MarkdownEditorCodeMirror
+          defaultValue={
+            "A **done** description.\n\n- [x] shipped"
+          }
+          isReadOnly
+          label="Read-only description"
+        />
+      </StoryCell>
+
+      <StoryCell align="stretch" label="disabled">
+        <MarkdownEditorCodeMirror
+          defaultValue={"You cannot edit _this_ one."}
+          isDisabled
+          label="Disabled description"
+        />
+      </StoryCell>
+
+      <StoryCell align="stretch" label="in a Field">
+        <Field
+          description="Markdown. Paste a screenshot straight in."
+          label="Description"
+        >
+          <MarkdownEditorCodeMirror defaultValue="Wired through `SlotProps`." />
+        </Field>
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * Concealment is per-construct, and the caret is what reveals it.
+ *
+ * This story exists because the behaviour is invisible in a static
+ * frame: click into the bold run and the `**` comes back, in the
+ * flow, without the line reflowing around it.
+ */
+export const CaretReveal: Story = {
+  args: {
+    defaultValue:
+      "Click into the **bold run** and its markers come back.\n\nLeave, and they go again.",
+    label: "Description",
+  },
+}