@lotics/ui 45.2.0 → 45.4.0

package/AGENTS.md

@@ -15,7 +15,7 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 | Doc | Read it for |
 |---|---|
 | [docs/catalog.md](./docs/catalog.md) | **The complete inventory** — Reach-by-role (each data role → the ONE canonical component) + every `@lotics/ui/<module>` entry point (incl. `@lotics/ui/vite`'s `loticsOptimizeDeps` + `loticsResolve()` — the pre-bundle list and the whole `resolve` block a custom-code app's `vite.config.ts` imports rather than hand-carries, dev-link included). Read before building any screen; reuse first. |
-| [docs/data_entry.md](./docs/data_entry.md) | **a picker over a select field keeps the field's colours** (`optionPicker` — the hand-rolled `map` to `{value,label}` drops `color`, so a value reads coloured in a register and grey in the editor); a choice that GATES a form is usually one not to ask (two doors to one room is not a chooser; show the dominant path, offer the other beside its submit, and give a recovery link a quieter treatment than an alternative way in); Which editing pattern for which job — inline edit, fieldset forms, choosing a CHOICE control by option count (and why "no selection" is a PLACEHOLDER, never an option valued `""` — the picker reads that as nothing chosen and renders down to its chevron), browser-autofill suppression (search controls only), find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (`InlineFiles` for a record ROW — list + one CTA, `multiple` decides add-vs-replace; the `FilesEditor` COMPOUND for a whole section — root owns selection/gallery/confirm, you compose the bar, a HOST verb reads `useFilesEditorSelection` — plus the three-way file INTAKE: CTA + `FileDropTarget` + `usePasteFiles`), stage gates, whether a multiline value keeps its fixed reserve or `autoGrow`s (who decides the length — the field, or whoever is typing); the swap rule for a NEW editor (same string ⇒ one element, different string ⇒ swap) worked through its two live cases — `InlineMarkdown` renders prose at rest and refuses to collapse when opened, while a URL takes `InlineTextInput`'s `link` TREATMENT because marking it changes its ink and not its characters, the commit-on-blur vs action-press ordering law (the kit gates the press — `pending_commits`). |
+| [docs/data_entry.md](./docs/data_entry.md) | **a picker over a select field keeps the field's colours** (`optionPicker` — the hand-rolled `map` to `{value,label}` drops `color`, so a value reads coloured in a register and grey in the editor); a choice that GATES a form is usually one not to ask (two doors to one room is not a chooser; show the dominant path, offer the other beside its submit, and give a recovery link a quieter treatment than an alternative way in); Which editing pattern for which job — inline edit, fieldset forms, choosing a CHOICE control by option count (and why "no selection" is a PLACEHOLDER, never an option valued `""` — the picker reads that as nothing chosen and renders down to its chevron), browser-autofill suppression (search controls only), find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (`InlineFiles` for a record ROW — list + one CTA, `multiple` decides add-vs-replace; the `FilesEditor` COMPOUND for a whole section — root owns selection/gallery/confirm, you compose the bar, a HOST verb reads `useFilesEditorSelection` — plus the three-way file INTAKE: CTA + `FileDropTarget` + `usePasteFiles`), stage gates, whether a multiline value keeps its fixed reserve or `autoGrow`s (who decides the length — the field, or whoever is typing); the swap rule for a NEW editor (same string ⇒ one element, different string ⇒ swap) worked through its two live cases — `InlineMarkdown` holds the SAME WYSIWYG the product's knowledge docs use (`MarkdownEditor`, ProseMirror on web, raw text on native) mounted AT REST, so focusing it moves nothing and the prose stays selectable — the case that shows a swap can be made to look stable but never to be it, while a URL takes `InlineTextInput`'s `link` TREATMENT because marking it changes its ink and not its characters, the commit-on-blur vs action-press ordering law (the kit gates the press — `pending_commits`). |
 | [docs/ai_patterns.md](./docs/ai_patterns.md) | AI acts, the human stays in charge — composer, live run feed (`AgentRun`), the one law's split — it turns on WHO supplied the values (machine → a gate: a diff when something is being replaced, a full editable preview when records are being created from a document; human-typed → save-direct + the `ResultHeader` receipt), findings, provenance, confidence; **after the run** — a stored record that fills up from several writers (a person, a chat agent, an extraction, an automation) and remembers none of them: an unwritten value must not render like a written one, a machine's prose and a person's must not share a treatment, model markdown goes in `variant="embedded"`, and the read path must project every field the write paths set; the UI half of the SDK's [ai doc](../app-sdk/docs/ai.md), the whole run in a dialog (`AgentRunScope`/`AgentRunPane`/`AgentRunActions` — a parked question REPLACES the feed, actions in the footer, **Stop** while streaming), **stopping** (`cancel` stops the run, `abort` only stops listening — so closing a dialog must `cancel` or it keeps billing); **review surfaces compose from atoms** — `DiffValue` (a changed value, droppable in any cell/row/total), `DiffMark` (what happened to the row — ONE circular disc, every surface, its kind derived from before/after rather than a boolean "did this change" — an empty `before` is `added`, never `changed`), `useChangeSet` (accept/reject/undo bookkeeping, no layout) — see [MIGRATION.md](./MIGRATION.md) for the `ChangeReview` family they replace |
 | [docs/composition.md](./docs/composition.md) | The design-language contract — **the form comes before the treatment** (name what the subject IS — register, rail, board, timeline, deviation queue — before reaching for parts; a subject flattened into rows is well-typed and says nothing, and reuse-first is about not duplicating primitives, not about a screen's shape; **a hierarchy in the DATA does not oblige one in the UI** — who MAINTAINS the structure decides, and a set the reader scans is a register whatever shape the data has), canvas + content column, heading altitude (incl. eyebrow vs group lead — a label is one or the other, and a section heading's own row never wraps so a control label that repeats the title can squeeze the title+description into a narrow ribbon at phone width), banded cards, register vs inset rows (incl. the register laws a row centres its cells by: every cell a FIXED height, a pressable cell on the shared hover token, a column sized by what it carries), the button ladder and **what underlined text may mean** (it GOES somewhere or REVEALS something — never mutates; blue leaves the surface, muted stays on it, and the one in-prose disclosure exception is scoped there), master-detail `Drawer` on a LIST screen vs a child collection's row EXPANDING inside a record, view controls, RECORD EXTENT (one page, sections scrolled to and never routed to), **the register's rhythm** (no hairline between rows — their own height and the hover wash separate them; the register's one line is the band capping the columns, because that is the break whitespace cannot state. Density is `TableRow`'s `minHeight`, never a mode), **a register that TRIAGES** (`TableGroup` — titled bands ordered by what needs the reader now, grouped by what implies a different ACTION rather than by a category already in a column, and what the screen can CLASSIFY kept as a separate list from what it RENDERS, so a value omitted on purpose does not resurface under *Unclassified* and one added later does not vanish), **the register's own craft** (a column header treated as CHROME a step lighter than row metadata, sentence case in the table header too, and a supporting line one RUNG BELOW the line it supports rather than a fixed size — plus the half that rule was missing: every SUBJECT on one row starts at the same rung, the subject leads by WEIGHT and its identity mark rather than by size, and whether the supporting line drops a rung is decided by what else separates the pair; plus the two ways a `columns` array and a rendered row disagree — a partial `priority` annotation, and a conditional column whose cell was not hidden with it), **identity marks** (a mark that looks the same on every row carries nothing — `Avatar` derives its hue from the name and takes circle/square for person vs organization; the palette is ordered by contrast, not spectrum, and never paints a person red or amber; a column of faces must not draw an UNBOUNDED audience as faces, and an overlapping stack separates with translucent INK rather than the surface colour, which a row's wash keeps changing out from under), **where the accent goes** ("which of these" — a selected row, an active filter; never DATA and never the focus ring, while a page-scale position marker like an active TAB takes `primary`, the ink the kit already spends on "this is on"; and selection must not share a wash with hover), **theming is an app-level ESCAPE HATCH, not a product surface** (`applyLoticsTheme({ … })` once at boot, before `mount`, writing the `--lotics-*` roles on the document root; nothing in the platform writes a theme, and `apps.theme.color` is the launcher icon only — the five `var()` roles plus the three font rungs ARE the whole mechanism, and wrapping a component cannot replace them because RN-Web writes `fontFamily` per element and background/border do not inherit), color discipline, **a fact band is read at a GLANCE and a glance is WIDE** (header facts paired into columns rather than stacked one per row — the tell is a screen reported as plain whose treatment is fine, spending its height on facts and its width on nothing; plus a record owes the reader the SIZE of its subject, summed from what the page already holds), **typography** (the ramp is DATA in `type_ramp`, one table both platforms derive from; leading and tracking are baked per rung and a hand-set `letterSpacing` is always a second copy of the curve), whitespace, **where a commit sits** (with its fields, never an overlay's footer — but a full-page editor is not a dialog, so a scrolling document keeps its commit pinned), and how to TEST an overlay component (a `Popover`-backed surface never mounts under jsdom). Selection is never the brand — a neutral ground on a row, a dark doubled edge on a chip or card, with `accent_wash` kept for attention; a lookup key is not a column (the search matches it); `Table` sheds and stacks rather than scrolling horizontally, because narrowing is what asks whether a column earns its width. |
 | [docs/reviewing.md](./docs/reviewing.md) | **Reviewing a screen you built** — the other docs say what good looks like; this one says how to find out whether you achieved it, because "it looks fine" is the same claim as "it should work" made with the same evidence. Measure, never eyeball: render it, extract computed values, let the table show the defect. Two GATES that outrank every treatment question (**SUBTRACT** — what question does this element answer, and count FACTS not elements; **RIGHT CONTROL** — name the species before treating it), then 11 probes each naming what to COLLECT and the SIGNATURE in the numbers: type inventory (range, singletons, the label/value shrink war), ground+border+radius across siblings, what each RULE separates, gap RATIOS, the state diff (paint may change, geometry may not), alignment drift (incl. a centred child that moves while its container measures identical), the surface walk (open it, press it, read the settled string), the DATA probe (what is really in the table — incl. grepping rendered text for internal ids), FIRST PAINT (an entry screen showing zero inputs is gated by something, usually a mode chooser), the ABSENCE pass that catches "bland", and microcopy. Plus the extraction snippets, what measurement cannot see, and how to act on a finding (fix the CLASS, and never resolve one with "the docs say X"). |
@@ -100,7 +100,7 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   `error={overdue ? … }` is the tell: it makes a date due tomorrow read like one due in three
   months. → [catalog.md §Dates & times](./docs/catalog.md).
 - **A third-party channel takes `BrandMark`, our own glyphs take `Icon`.** `@lotics/ui/brand_mark`
-  draws Facebook / Zalo / LinkedIn / Google Meet as solid single-colour silhouettes — a reader
+  draws Facebook / Zalo / LinkedIn / X / Google Meet as solid single-colour silhouettes — a reader
   scanning a feed recognises the logo before the word. The names are an allowlist, so a channel
   with no mark (a phone call, an event, a website) fails to typecheck and falls back to `Icon`
   instead of borrowing another company's logo. → [catalog.md §Text & formatting](./docs/catalog.md).

package/docs/catalog.md

@@ -161,12 +161,22 @@ the navigation ink as a TREATMENT on the same single element — never a swapped
 in `actions`),
 `InlineNumberInput`, `InlineSelect` (single or
 `multi`), `InlineMemberSelect`, `InlineDatePicker`, `InlineTimePicker`,
-**`InlineMarkdown`** (markdown RENDERED at rest, raw source while editing — the
-member that swaps because its two states show different strings; its editor never
-opens shorter than the view it replaced, so pressing a long note cannot collapse
-the box, and **`minLines`** sets the floor for a short one); a
+**`InlineMarkdown`** (a markdown field holding **`MarkdownEditor`** — the same WYSIWYG
+the product's own knowledge docs use, not a raw textarea. It does NOT swap: the editor
+is mounted at rest and merely gains a draft on focus, so focusing moves nothing and
+the prose stays SELECTABLE rather than sitting under a button. Its toolbar is off for
+that reason — a band that appears with the edit pushes everything under it down.
+**`numberOfLines`** is the reserve, as everywhere else in the family); a
 READ-ONLY field in that same column uses `InlineStatic` (matches the editor box exactly, no
-input chrome, so it aligns pixel-for-pixel). A stack of labelled field rows lives in
+input chrome, so it aligns pixel-for-pixel). **`MarkdownEditor`** is that editor standalone — a WYSIWYG whose value stays a plain
+markdown string, with a formatting toolbar as a SIBLING of the field (what the border
+encloses is the document; the controls that act on it sit outside it). Web is
+ProseMirror via `@lotics/markdown-editor`; native falls back to raw-text editing, and
+the platform-neutral `MarkdownEditorProps` is what stops the two drifting. Wrap it in a
+label with **`FormMarkdownEditor`**. Pass **`accessibilityLabel`** whenever the visible
+label is a sibling rather than a wrapping `FormField` — a `DetailRow`, an inline
+editor's frame — or the editable surface is an unnamed text box. A stack of labelled
+field rows lives in
 `DetailTable` + `DetailRow`; the record's identity band is `RecordSummary`; its money
 summary is `Ledger`.
 
@@ -466,12 +476,13 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `SubsectionHeading` instead. Pick between this and `Eyebrow` by what is LABELLED — a block or a
   value; composition.md § Eyebrow vs group lead has the table.
 - **`brand_mark`** — `BrandMark`: an OUTSIDE brand's mark, naming the channel a touchpoint
-  happened on — `facebook`, `zalo`, `linkedin`, `google-meet`. Solid single-colour silhouettes in
+  happened on — `facebook`, `zalo`, `linkedin`, `x`, `google-meet`. Solid single-colour silhouettes in
   each brand's own hex, not the full-colour logos: a byline draws these at 14–20px and a
   five-colour logo turns to mud there. `size` (default 16) and `muted` (draw in the text colour).
   The name list is an ALLOWLIST — a channel with no mark will not typecheck, so the call site
   falls back to a generic `Icon` rather than rendering the wrong company's logo. Not for the app's
-  own glyphs; that is `icon`.
+  own glyphs; that is `icon`. `x` is the one mark whose brand colour is BLACK, so it is the one
+  that needs `muted` on a dark ground; the rest carry their own hue either way.
 - **`markdown`** — `Markdown`: the single canonical markdown renderer for chat, apps, and
   `AgentRun`; rich GFM markdown on web with copyable tables, plain-text on
   native; takes a markdown `children` string. **`variant`** decides whose type

package/docs/data_entry.md

@@ -132,11 +132,19 @@ field), the string changes anyway, so those editors do swap and should. **The ru
 editor: same string in both states ⇒ one element; different string ⇒ swap.**
 
 Two worked cases sit on either side of it, and they look alike until you apply the rule.
-**`InlineMarkdown` swaps**: `**bold**` and **bold** are different strings, so the quarter pixel is
-invisible and rendering prose at rest is worth having. A swap editor is supposed to leave the box
-where it was, which markdown cannot do exactly — so it does the half that matters and refuses to
-COLLAPSE: the resting height becomes the editor's floor, because growing is tolerable where
-shrinking pulls the text out from under the reader and jumps everything below it.
+**`InlineMarkdown` does NOT swap, and the reason it tried to is the lesson.** Its editor is the
+WYSIWYG `MarkdownEditor`, so both states show rendered prose — the rule's first limb, one element.
+It was nonetheless built as a swap on a COST argument (a ProseMirror view per field is not free the
+way an `<input>` is), and every defect that followed came from that one decision: the box changed
+height on open, a toolbar rolled in and pushed the form down, and the resting state was a `Pressable`
+— so it wore the pointer cursor and `userSelect: none` denied a reader the ability to select a
+sentence out of their own note.
+
+None of those are fixable while two elements draw one value; a measured height floor only papers
+over the first. **When "the layout must not move" is a requirement rather than a preference, one
+element is the only thing that delivers it** — a swap can be made to look stable, never to be it. So
+the editor is mounted at rest and gains a draft on focus, and the per-field cost is paid on purpose.
+If a screen ever holds dozens of these, the answer is fewer markdown fields on it, not a swap.
 **A LINK does not swap**: marking a URL changes its ink, not its characters, so `InlineTextInput`
 takes a **`link`** treatment on its single `<input>` rather than swapping in a `TextLink`. Pressing
 the field still edits — an `Open` `InlineButton` in `actions` is how you reach the destination,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "45.2.0",
+  "version": "45.4.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -169,6 +169,14 @@
     "./inline_slot": "./src/inline_slot.tsx",
     "./inline_static": "./src/inline_static.tsx",
     "./inline_files": "./src/inline_files.tsx",
+    "./inline_markdown": "./src/inline_markdown.tsx",
+    "./markdown_editor": {
+      "react-native": "./src/markdown_editor.tsx",
+      "default": "./src/markdown_editor.web.tsx"
+    },
+    "./markdown_editor_props": "./src/markdown_editor_props.ts",
+    "./markdown_editor.css": "./src/markdown_editor.css",
+    "./form_markdown_editor": "./src/form_markdown_editor.tsx",
     "./inline_text_input": "./src/inline_text_input.tsx",
     "./inline_number_input": "./src/inline_number_input.tsx",
     "./inline_select": "./src/inline_select.tsx",
@@ -323,6 +331,7 @@
   "license": "SEE LICENSE IN LICENSE.md",
   "dependencies": {
     "@lotics/docx": "^0.3.0",
+    "@lotics/markdown-editor": "^0.1.0",
     "@lotics/xlsx": "^0.2.0",
     "ai": "^7.0.30",
     "mdast-util-from-markdown": "^2.0.3",

package/src/brand_mark.tsx

@@ -7,7 +7,7 @@ import { Svg, Path } from "react-native-svg";
  * email that is not tied to one provider. Inventing a mark for those is how a
  * byline ends up claiming a channel the record does not carry.
  */
-export type BrandName = "facebook" | "zalo" | "linkedin" | "google-meet";
+export type BrandName = "facebook" | "zalo" | "linkedin" | "x" | "google-meet";
 
 interface Mark {
   /** The brand's own colour. A mark drawn in anything else is not the mark. */
@@ -40,6 +40,14 @@ const MARKS: Record<BrandName, Mark> = {
     color: "#0A66C2",
     path: "M20.447 20.452h-3.554v-5.569c0-1.328-.027-3.037-1.852-3.037-1.853 0-2.136 1.445-2.136 2.939v5.667H9.351V9h3.414v1.561h.046c.477-.9 1.637-1.85 3.37-1.85 3.601 0 4.267 2.37 4.267 5.455v6.286zM5.337 7.433c-1.144 0-2.063-.926-2.063-2.065 0-1.138.92-2.063 2.063-2.063 1.14 0 2.064.925 2.064 2.063 0 1.139-.925 2.065-2.064 2.065zm1.782 13.019H3.555V9h3.564v11.452zM22.225 0H1.771C.792 0 0 .774 0 1.729v20.542C0 23.227.792 24 1.771 24h20.451C23.2 24 24 23.227 24 22.271V1.729C24 .774 23.2 0 22.222 0h.003z",
   },
+  x: {
+    // X's mark is black, and that is the mark — a brand drawn in a colour it
+    // does not use is not the brand. It is the one entry here that depends on
+    // its ground: on a dark surface pass `muted`, which draws it in the text
+    // colour like every other mark and keeps it visible.
+    color: "#000000",
+    path: "M18.901 1.153h3.68l-8.04 9.19L24 22.846h-7.406l-5.8-7.584-6.638 7.584H.474l8.6-9.83L0 1.154h7.594l5.243 6.932ZM17.61 20.644h2.039L6.486 3.24H4.298Z",
+  },
   "google-meet": {
     color: "#00897B",
     path: "M5.53 2.13 0 7.75h5.53zm.398 0v5.62h7.608v3.65l5.47-4.45c-.014-1.22.031-2.25-.025-3.46-.148-1.09-1.287-1.47-2.236-1.36zM23.1 4.32c-.802.295-1.358.995-2.047 1.49-2.506 2.05-4.982 4.12-7.468 6.19 3.025 2.59 6.04 5.18 9.065 7.76 1.218.671 1.428-.814 1.328-1.64v-13a.828.828 0 0 0-.877-.825zM.038 8.15v7.7h5.53v-7.7zm13.577 8.1H6.008v5.62c3.864-.006 7.737.011 11.58-.009 1.02-.07 1.618-1.12 1.468-2.07v-2.51l-5.47-4.68v3.65zm-13.577 0c.02 1.44-.041 2.88.033 4.31.162.948 1.158 1.43 2.047 1.31h3.464v-5.62z",

package/src/form_markdown_editor.tsx

@@ -0,0 +1,15 @@
+import { FormField, FormFieldProps } from "./form_field";
+import { MarkdownEditor } from "./markdown_editor";
+import type { MarkdownEditorProps } from "./markdown_editor_props";
+
+export interface FormMarkdownEditorProps extends Omit<FormFieldProps, "style">, MarkdownEditorProps {}
+
+export function FormMarkdownEditor(props: FormMarkdownEditorProps) {
+  const { label, description, optional, error, ...editorProps } = props;
+
+  return (
+    <FormField label={label} description={description} error={error} optional={optional}>
+      <MarkdownEditor {...editorProps} />
+    </FormField>
+  );
+}

package/src/inline_markdown.tsx

@@ -1,11 +1,8 @@
-import { useCallback, useRef, useState, type ReactNode } from "react";
-import { View, type LayoutChangeEvent, type NativeSyntheticEvent, type TextInputKeyPressEventData } from "react-native";
 import { InlineEditFrame, useInlineEdit, type InlineEditVariant } from "./inline_edit";
-import { Markdown } from "./markdown";
-import { TextInputField } from "./text_input_field";
+import { MarkdownEditor } from "./markdown_editor";
 
 export interface InlineMarkdownProps {
-  /** The markdown SOURCE. Rendered at rest, edited raw. */
+  /** The markdown SOURCE. Rendered rich, edited in place. */
   value: string;
   /** Persist the new source. May be async — the field shows a saving state and
    *  surfaces a thrown error inline, staying in edit mode so nothing is lost. */
@@ -14,80 +11,55 @@ export interface InlineMarkdownProps {
   disabled?: boolean;
   /** How much frame shows at rest — see {@link InlineEditVariant}. Default "framed". */
   variant?: InlineEditVariant;
-  /** The editor's floor, in lines, before the resting height is taken into
-   *  account. Keeps a short or empty value from opening a one-line slot. */
-  minLines?: number;
+  /** Line budget for the field. The box reserves this whether or not the value
+   *  fills it, so nothing moves as the value grows into it. */
+  numberOfLines?: number;
   accessibilityLabel?: string;
 }
 
-/** A short prose reserve, so an empty field is still obviously somewhere to write. */
-const DEFAULT_MIN_LINES = 3;
-const APPROX_LINE_HEIGHT = 22;
-
 /**
- * An inline-editable MARKDOWN value: rendered at rest, raw source while editing.
+ * An inline-editable MARKDOWN value.
+ *
+ * **ONE element, always mounted — it does not swap.** This started as a swap
+ * (rendered prose at rest, an editor on press) and every problem that followed
+ * came from there: the box changed height when it opened, a toolbar rolled in
+ * and pushed the rest of the form down, and the resting state was a BUTTON, so
+ * it took the pointer cursor while `userSelect: none` denied a reader the
+ * ability to select a sentence out of their own note.
  *
- * This one SWAPS, and it is allowed to for the same reason the number and date
- * editors do: its resting display and its editor show genuinely different
- * strings (`**bold**` against **bold**), so the sub-pixel drift that forced
- * `InlineTextInput` to stay a single element is not perceptible here. That rule
- * — same string ⇒ one element, different string ⇒ swap — is what decides which
- * shape a new editor takes, and markdown is the clearest case of the second.
+ * None of those are fixable while two elements draw one value. There is no
+ * arrangement of two renderers of the same markdown that GUARANTEES zero shift —
+ * so the guarantee has to come from there being one. The editor renders at rest
+ * and simply gains a draft when focused, exactly as `InlineTextInput` is one
+ * `<input>` in both states.
  *
- * **The editor never opens SHORTER than the view it replaced.** A swap editor
- * is supposed to leave the box where it was; for markdown it cannot exactly,
- * because rendered prose and its source are different lengths by nature. What it
- * CAN do is refuse to collapse: the resting height is measured and becomes the
- * input's floor, so pressing a long note opens a long editor. Growing is the
- * tolerable direction — shrinking pulls the text the reader was just looking at
- * out from under them, and everything below it jumps up.
+ * What that costs is a ProseMirror view per field, mounted whether or not anyone
+ * edits. That is a real price, paid deliberately: a record surface holds a
+ * handful of these, and "the layout never moves" is worth more than the
+ * instances. If a screen ever holds dozens, the answer is fewer markdown fields
+ * on it — not a swap that reintroduces the shift.
  *
- * Reach for it wherever a field holds markdown a PERSON wrote. A model's output
- * is read-only (you re-run it, you do not hand-edit it) and belongs in a plain
- * `Markdown`.
+ * The toolbar is OFF here for the same reason: a band that appears with the edit
+ * moves everything under it. `MarkdownEditor` keeps it for surfaces whose whole
+ * job is the document, where it is always present and so shifts nothing.
  */
 export function InlineMarkdown(props: InlineMarkdownProps) {
-  const { value, onSave, placeholder, disabled, variant, minLines, accessibilityLabel } = props;
+  const { value, onSave, placeholder, disabled, variant, numberOfLines, accessibilityLabel } = props;
   const edit = useInlineEdit<string>({ value, onSave });
-  const [restingHeight, setRestingHeight] = useState(0);
-  // Not state: it must be current for the render that mounts the input, and a
-  // set during layout would arrive one frame late — as a visible jump.
-  const measured = useRef(0);
-
-  const onViewLayout = useCallback((e: LayoutChangeEvent) => {
-    measured.current = e.nativeEvent.layout.height;
-  }, []);
-
-  const begin = useCallback(() => {
-    setRestingHeight(measured.current);
-    edit.begin();
-  }, [edit]);
-
-  const onKeyPress = useCallback(
-    (e: NativeSyntheticEvent<TextInputKeyPressEventData>) => {
-      // Enter is a PARAGRAPH BREAK here — this is prose, and `numberOfLines > 1`
-      // is what declares that everywhere else in the family. Blur commits.
-      if (e.nativeEvent.key === "Escape") edit.cancel();
-    },
-    [edit],
-  );
-
-  const floor = Math.max((minLines ?? DEFAULT_MIN_LINES) * APPROX_LINE_HEIGHT, restingHeight);
-
-  const display: ReactNode = value === "" ? "" : (
-    <View onLayout={onViewLayout}>
-      <Markdown>{value}</Markdown>
-    </View>
-  );
 
   return (
     <InlineEditFrame
-      // Unlike `InlineTextInput`, `editing` here IS the mount: the input exists
-      // only during an edit, which is what makes the rendered view possible.
-      editing={edit.editing}
-      display={display}
+      // ALWAYS the editor. `editing` is a MOUNT decision, and mounting
+      // unconditionally is what makes the resting and editing states the same
+      // element — see the note above on why nothing else holds the no-shift
+      // guarantee.
+      editing
+      // ...but the ✓/✕ verbs still key off a REAL edit: at rest there is nothing
+      // to accept and nothing to revert.
+      editOpen={edit.editing}
+      display={value}
       placeholder={placeholder}
-      onBegin={begin}
+      onBegin={edit.begin}
       controls="blur"
       onCommit={() => void edit.commit()}
       onCancel={edit.cancel}
@@ -95,23 +67,24 @@ export function InlineMarkdown(props: InlineMarkdownProps) {
       error={edit.error}
       disabled={disabled}
       variant={variant}
+      numberOfLines={numberOfLines}
       accessibilityLabel={accessibilityLabel}
     >
-      <TextInputField
-        value={edit.draft}
+      <MarkdownEditor
+        // The DRAFT only exists once editing has begun; before that the field
+        // must show the record's value, or an external update would be masked by
+        // a stale draft from the last edit (`begin` is what syncs them).
+        value={edit.editing ? edit.draft : value}
         onChangeText={edit.setDraft}
+        // Focus IS begin — the element the reader clicks is already the editor,
+        // so the gesture that used to mount one now just opens a draft on it.
+        onFocus={edit.begin}
         onBlur={() => void edit.commit()}
-        onKeyPress={onKeyPress}
-        multiline
-        // The input ARRIVES with the edit, so it takes the caret on mount. This
-        // is the case `InlineTextInput` cannot serve — it is permanently mounted
-        // and deliberately has no `autoFocus`, so a revealed field there would
-        // cost the reader a second click.
-        autoFocus
+        toolbar={false}
         placeholder={placeholder}
-        accessibilityLabel={accessibilityLabel}
+        numberOfLines={numberOfLines}
         disabled={disabled}
-        style={{ minHeight: floor }}
+        accessibilityLabel={accessibilityLabel}
       />
     </InlineEditFrame>
   );

package/src/locale.tsx

@@ -171,6 +171,22 @@ export interface LoticsLocale {
   /** `FilesEditor`'s shipped bar pieces (upload, select, select-all, download,
    *  remove) and the remove confirm. A HOST verb is a plain `Button` and names
    *  itself, so nothing here is about what an app happens to do with a file. */
+  markdownToolbar: {
+    linkUrl: string;
+    heading1: string;
+    heading2: string;
+    heading3: string;
+    bold: string;
+    italic: string;
+    inlineCode: string;
+    bulletList: string;
+    numberedList: string;
+    quote: string;
+    codeBlock: string;
+    link: string;
+    insertTable: string;
+    divider: string;
+  };
   filesEditor: {
     upload: string;
     select: string;
@@ -388,6 +404,22 @@ export const en: LoticsLocale = {
   overlay: { close: "Close" },
   fileDropzone: { label: "Drag files here", hint: "or click, or paste (⌘V)", drop: "Drop to upload" },
   fileThumbnail: { remove: "Remove" },
+  markdownToolbar: {
+    linkUrl: "Link URL",
+    heading1: "Heading 1",
+    heading2: "Heading 2",
+    heading3: "Heading 3",
+    bold: "Bold",
+    italic: "Italic",
+    inlineCode: "Inline code",
+    bulletList: "Bullet list",
+    numberedList: "Numbered list",
+    quote: "Quote",
+    codeBlock: "Code block",
+    link: "Link",
+    insertTable: "Insert table",
+    divider: "Divider",
+  },
   filesEditor: {
     upload: "Upload",
     select: "Select",
@@ -578,6 +610,22 @@ export const vi: LoticsLocale = {
   overlay: { close: "Đóng" },
   fileDropzone: { label: "Kéo tệp vào đây", hint: "hoặc bấm chọn, hoặc dán (Ctrl+V)", drop: "Thả để tải lên" },
   fileThumbnail: { remove: "Xóa" },
+  markdownToolbar: {
+    linkUrl: "Địa chỉ liên kết",
+    heading1: "Tiêu đề 1",
+    heading2: "Tiêu đề 2",
+    heading3: "Tiêu đề 3",
+    bold: "Đậm",
+    italic: "Nghiêng",
+    inlineCode: "Mã trong dòng",
+    bulletList: "Danh sách gạch đầu dòng",
+    numberedList: "Danh sách đánh số",
+    quote: "Trích dẫn",
+    codeBlock: "Khối mã",
+    link: "Liên kết",
+    insertTable: "Chèn bảng",
+    divider: "Đường phân cách",
+  },
   filesEditor: {
     upload: "Tải lên",
     select: "Chọn",

package/src/markdown_editor.css

@@ -0,0 +1,144 @@
+/* WYSIWYG markdown editor chrome. Typography is inherited from `.ui-markdown`
+   (markdown.css) — this file only covers the editing surface and ProseMirror. */
+
+/* The frame around the DOCUMENT. The toolbar is a sibling above it, so this
+   encloses content and nothing else — and it takes a softer radius than a
+   control would, because it is a sheet of writing rather than a field. */
+.md-editor {
+  border: 1px solid rgba(228, 228, 231, 1);
+  border-radius: 16px;
+  background-color: rgba(255, 255, 255, 1);
+  overflow: hidden;
+  /* The ProseMirror editable element is this node's only child; let it fill the
+     configured min-height so clicks anywhere in the field focus the editor. */
+  display: flex;
+  flex-direction: column;
+}
+
+/* The kit's field grammar, which this editor was not following: hover moves the
+   BORDER, focus adds the RING, and the border never changes colour on focus.
+   It painted a blue border on focus-within instead — a colour that appears
+   nowhere else in the system and a mechanism no other input uses, so the one
+   multi-line field on a page announced focus differently from every field
+   beside it.
+
+   Literal rgba because this is plain CSS with no access to the tokens; the
+   values are `HOVER_BORDER` (zinc-500) and `FOCUS_RING` (2px zinc-900) from
+   `@lotics/ui/control_surface`, and they are the two to update if those move. */
+.md-editor:hover {
+  border-color: rgba(113, 113, 122, 1);
+}
+
+.md-editor:focus-within {
+  box-shadow: 0 0 0 2px rgba(24, 24, 27, 1);
+}
+
+.md-editor[data-disabled="true"] {
+  opacity: 0.6;
+}
+
+.md-editor-content {
+  flex: 1 1 auto;
+  /* position:relative anchors the absolutely-positioned gap cursor. */
+  position: relative;
+  padding: 8px 12px;
+  outline: none;
+  white-space: pre-wrap;
+  word-wrap: break-word;
+}
+
+.md-editor-content .ProseMirror-selectednode {
+  outline: 2px solid rgba(59, 130, 246, 0.6);
+}
+
+.md-editor-content > :first-child {
+  padding-top: 0;
+  margin-top: 0;
+}
+
+.md-editor-content > :last-child {
+  padding-bottom: 0;
+  margin-bottom: 0;
+}
+
+/* Empty-document placeholder */
+
+.md-editor-placeholder::before {
+  content: attr(data-placeholder);
+  color: rgba(161, 161, 170, 1);
+  pointer-events: none;
+  height: 0;
+  float: left;
+}
+
+/* ProseMirror selection / gap cursor */
+
+.ProseMirror[contenteditable="false"] {
+  cursor: default;
+}
+
+.ProseMirror-hideselection *::selection {
+  background: transparent;
+}
+
+.ProseMirror-gapcursor {
+  display: none;
+  pointer-events: none;
+  position: absolute;
+}
+
+.ProseMirror-gapcursor::after {
+  content: "";
+  display: block;
+  position: absolute;
+  top: -2px;
+  width: 20px;
+  border-top: 1px solid rgba(24, 24, 27, 1);
+  animation: md-editor-blink 1.1s steps(2, start) infinite;
+}
+
+@keyframes md-editor-blink {
+  to {
+    visibility: hidden;
+  }
+}
+
+.ProseMirror-focused .ProseMirror-gapcursor {
+  display: block;
+}
+
+/* Table editing (prosemirror-tables) */
+
+.md-editor-content .tableWrapper {
+  overflow-x: auto;
+  margin: 4px 0;
+}
+
+.md-editor-content td,
+.md-editor-content th {
+  position: relative;
+}
+
+.md-editor-content .selectedCell::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  background: rgba(59, 130, 246, 0.16);
+  pointer-events: none;
+  z-index: 2;
+}
+
+.md-editor-content .column-resize-handle {
+  position: absolute;
+  right: -2px;
+  top: 0;
+  bottom: 0;
+  width: 4px;
+  background-color: rgba(59, 130, 246, 1);
+  pointer-events: none;
+  z-index: 3;
+}
+
+.md-editor-content.resize-cursor {
+  cursor: col-resize;
+}

package/src/markdown_editor.tsx

@@ -0,0 +1,29 @@
+import { TextInputField } from "./text_input_field";
+import type { MarkdownEditorProps } from "./markdown_editor_props";
+
+/**
+ * Native fallback for the markdown editor. The WYSIWYG editor is DOM/ProseMirror
+ * based and web-only (see `markdown_editor.web.tsx`); on native, markdown is
+ * edited as raw text.
+ */
+export function MarkdownEditor(props: MarkdownEditorProps) {
+  const { value, onChangeText, onBlur, onFocus, placeholder, numberOfLines, disabled, autoFocus, accessibilityLabel, testID } =
+    props;
+
+  return (
+    <TextInputField
+      testID={testID}
+      value={value}
+      onChangeText={onChangeText}
+      onBlur={onBlur}
+      onFocus={onFocus}
+      placeholder={placeholder}
+      numberOfLines={numberOfLines ?? 6}
+      multiline
+      autoGrow
+      disabled={disabled}
+      autoFocus={autoFocus}
+      accessibilityLabel={accessibilityLabel}
+    />
+  );
+}

package/src/markdown_editor.web.tsx

@@ -0,0 +1,89 @@
+import "./markdown.css";
+import "./markdown_editor.css";
+import { useEffect, useReducer, useRef, useState } from "react";
+import {
+  createMarkdownEditorView,
+  type MarkdownEditorHandle,
+} from "@lotics/markdown-editor/editor_view";
+import { getInputLineHeight } from "./text_utils";
+import { useContainerSize } from "./size_boundary";
+import type { MarkdownEditorProps } from "./markdown_editor_props";
+import { MarkdownToolbar } from "./markdown_toolbar.web";
+
+/**
+ * WYSIWYG markdown editor. Users edit rich text directly; the value stays a
+ * plain markdown string. The ProseMirror engine lives in `@lotics/markdown-editor`.
+ */
+export function MarkdownEditor(props: MarkdownEditorProps) {
+  const { value, onChangeText, onBlur, onFocus, toolbar = true, placeholder, numberOfLines, disabled, autoFocus, accessibilityLabel, testID } =
+    props;
+
+  const hostRef = useRef<HTMLDivElement>(null);
+  const handleRef = useRef<MarkdownEditorHandle | null>(null);
+  const valueRef = useRef(value);
+  const callbacks = useRef({ onChangeText, onBlur, onFocus });
+  callbacks.current = { onChangeText, onBlur, onFocus };
+
+  const [handle, setHandle] = useState<MarkdownEditorHandle | null>(null);
+  const [, forceRender] = useReducer((tick: number) => tick + 1, 0);
+
+  const { small } = useContainerSize();
+  const minHeight = (numberOfLines ?? 6) * getInputLineHeight(small) + 16;
+
+  useEffect(() => {
+    const host = hostRef.current;
+    if (!host) return;
+
+    const created = createMarkdownEditorView(host, {
+      markdown: valueRef.current,
+      editable: !disabled,
+      placeholder,
+      autoFocus,
+      ariaLabel: accessibilityLabel,
+      onChange: (markdown) => {
+        valueRef.current = markdown;
+        callbacks.current.onChangeText(markdown);
+      },
+      onStateChange: forceRender,
+      onBlur: () => callbacks.current.onBlur?.(),
+      onFocus: () => callbacks.current.onFocus?.(),
+    });
+    handleRef.current = created;
+    setHandle(created);
+
+    return () => {
+      created.destroy();
+      handleRef.current = null;
+      setHandle(null);
+    };
+  }, [disabled, placeholder, autoFocus, accessibilityLabel]);
+
+  useEffect(() => {
+    if (value !== valueRef.current) {
+      valueRef.current = value;
+      handleRef.current?.setMarkdown(value);
+    }
+  }, [value]);
+
+  return (
+    // ONE node for the field. It used to be three — an RN `View` holding a
+    // styled `.md-editor` holding a `.md-editor-host` — and each was doing a job
+    // the others could: ProseMirror mounts into whatever node it is handed, so
+    // the styled frame IS the host, and the outer `View` existed only to sit two
+    // siblings next to each other, which a fragment does without a box.
+    //
+    // The toolbar is a SIBLING of the field, not a band inside it. What the
+    // border encloses is the document; the controls that act on it belong
+    // outside that boundary, the way a page's actions sit outside the page.
+    <>
+      {toolbar ? <MarkdownToolbar handle={handle} disabled={disabled} /> : null}
+      <div
+        ref={hostRef}
+        className="md-editor"
+        data-testid={testID}
+        data-disabled={disabled ? "true" : undefined}
+        style={{ minHeight }}
+      />
+    </>
+  );
+}

package/src/markdown_editor_props.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared prop contract for the markdown editor. Declared platform-neutrally so
+ * the web (`markdown_editor.web.tsx`) and native (`markdown_editor.tsx`)
+ * implementations cannot drift.
+ */
+export interface MarkdownEditorProps {
+  value: string;
+  onChangeText: (text: string) => void;
+  onBlur?: () => void;
+  onFocus?: () => void;
+  /**
+   * Show the formatting toolbar.
+   *
+   * OFF for a field embedded in a record row: it is a band that appears with the
+   * edit, and anything that appears moves everything under it. On a surface
+   * whose whole job is the document — a knowledge doc, a settings screen — it is
+   * always there and shifts nothing, so it stays on.
+   */
+  toolbar?: boolean;
+  placeholder?: string;
+  numberOfLines?: number;
+  disabled?: boolean;
+  autoFocus?: boolean;
+  /** Accessible name. Required in spirit whenever the field's visible label is
+   *  a sibling rather than a wrapping `FormField` — a `DetailRow`, an inline
+   *  editor's frame. */
+  accessibilityLabel?: string;
+  testID?: string;
+}

package/src/markdown_toolbar.web.tsx

@@ -0,0 +1,231 @@
+import { useCallback } from "react";
+import { View } from "react-native";
+import type { MarkdownEditorHandle } from "@lotics/markdown-editor/editor_view";
+import { markdownSchema } from "@lotics/markdown-editor/schema";
+import type { MarkType, NodeType } from "prosemirror-model";
+import {
+  applyLink,
+  canApplyLink,
+  clearLink,
+  insertHorizontalRule,
+  insertTable,
+  isBlockActive,
+  isMarkActive,
+  toggleBlockquote,
+  toggleBulletList,
+  toggleCode,
+  toggleCodeBlock,
+  toggleEm,
+  toggleHeading,
+  toggleOrderedList,
+  toggleStrong,
+} from "@lotics/markdown-editor/commands";
+import { colors } from "./colors";
+import { IconButton } from "./icon_button";
+import type { IconName } from "./icon";
+import { useLoticsLocale } from "./locale";
+
+type EditorCommand = typeof toggleStrong;
+
+interface ToolbarButton {
+  kind: "button";
+  icon: IconName;
+  tooltip: string;
+  active: boolean;
+  onPress: () => void;
+}
+
+type ToolbarItem = ToolbarButton | { kind: "divider" };
+
+/**
+ * The formatting band.
+ *
+ * It renders whether or not there is an editor behind it yet, and whether or not
+ * that editor is enabled — the buttons simply go inert. Presence belongs to the
+ * caller (`MarkdownEditor`'s `toolbar`), never to a state that changes while the
+ * reader is looking: a band that arrives when the view mounts, or when the field
+ * gains focus, moves everything under it at exactly the moment attention is
+ * there.
+ */
+export function MarkdownToolbar({
+  handle,
+  disabled,
+}: {
+  handle: MarkdownEditorHandle | null;
+  disabled?: boolean;
+}) {
+  const { markdownToolbar: t } = useLoticsLocale();
+  const view = handle?.view ?? null;
+  const inert = disabled === true || view === null;
+
+  const run = useCallback(
+    (command: EditorCommand) => {
+      if (!view) return;
+      command(view.state, view.dispatch, view);
+      view.focus();
+    },
+    [view],
+  );
+
+  const handleLink = useCallback(() => {
+    if (!view) return;
+    if (isMarkActive(view.state, markdownSchema.marks.link)) {
+      run(clearLink);
+      return;
+    }
+    if (!canApplyLink(view.state)) return;
+    const href = window.prompt(t.linkUrl)?.trim();
+    if (href) run(applyLink(href));
+  }, [view, run, t]);
+
+  const state = view?.state ?? null;
+
+  // With no document there is nothing to be active IN. Wrapping once beats
+  // guarding at each of the thirteen reads below, and keeps the button table a
+  // table rather than a column of ternaries.
+  const blockActive = (nodeType: NodeType, attrs?: Record<string, unknown>): boolean =>
+    state !== null && isBlockActive(state, nodeType, attrs);
+  const markActive = (markType: MarkType): boolean =>
+    state !== null && isMarkActive(state, markType);
+  const { nodes, marks } = markdownSchema;
+
+  const items: ToolbarItem[] = [
+    {
+      kind: "button",
+      icon: "heading-1",
+      tooltip: t.heading1,
+      active: blockActive(nodes.heading, { level: 1 }),
+      onPress: () => run(toggleHeading(1)),
+    },
+    {
+      kind: "button",
+      icon: "heading-2",
+      tooltip: t.heading2,
+      active: blockActive(nodes.heading, { level: 2 }),
+      onPress: () => run(toggleHeading(2)),
+    },
+    {
+      kind: "button",
+      icon: "heading-3",
+      tooltip: t.heading3,
+      active: blockActive(nodes.heading, { level: 3 }),
+      onPress: () => run(toggleHeading(3)),
+    },
+    { kind: "divider" },
+    {
+      kind: "button",
+      icon: "bold",
+      tooltip: t.bold,
+      active: markActive(marks.strong),
+      onPress: () => run(toggleStrong),
+    },
+    {
+      kind: "button",
+      icon: "italic",
+      tooltip: t.italic,
+      active: markActive(marks.em),
+      onPress: () => run(toggleEm),
+    },
+    {
+      kind: "button",
+      icon: "code",
+      tooltip: t.inlineCode,
+      active: markActive(marks.code),
+      onPress: () => run(toggleCode),
+    },
+    { kind: "divider" },
+    {
+      kind: "button",
+      icon: "list",
+      tooltip: t.bulletList,
+      active: blockActive(nodes.bullet_list),
+      onPress: () => run(toggleBulletList),
+    },
+    {
+      kind: "button",
+      icon: "list-ordered",
+      tooltip: t.numberedList,
+      active: blockActive(nodes.ordered_list),
+      onPress: () => run(toggleOrderedList),
+    },
+    {
+      kind: "button",
+      icon: "text-quote",
+      tooltip: t.quote,
+      active: blockActive(nodes.blockquote),
+      onPress: () => run(toggleBlockquote),
+    },
+    {
+      kind: "button",
+      icon: "code-xml",
+      tooltip: t.codeBlock,
+      active: blockActive(nodes.code_block),
+      onPress: () => run(toggleCodeBlock),
+    },
+    { kind: "divider" },
+    {
+      kind: "button",
+      icon: "link-2",
+      tooltip: t.link,
+      active: markActive(marks.link),
+      onPress: handleLink,
+    },
+    {
+      kind: "button",
+      icon: "table-2",
+      tooltip: t.insertTable,
+      active: false,
+      onPress: () => run(insertTable),
+    },
+    {
+      kind: "button",
+      icon: "minus",
+      tooltip: t.divider,
+      active: false,
+      onPress: () => run(insertHorizontalRule),
+    },
+  ];
+
+  return (
+    <View
+      style={{
+        flexDirection: "row",
+        flexWrap: "wrap",
+        alignItems: "center",
+        gap: 2,
+        // No rule beneath it. The toolbar sits ABOVE the field rather than
+        // inside its frame, so it needs no edge of its own — the field's own
+        // border is the boundary, and a second line 4px above it was two
+        // boundaries for one object.
+        paddingBottom: 6,
+      }}
+    >
+      {items.map((item, index) =>
+        item.kind === "divider" ? (
+          <View
+            key={`divider-${index}`}
+            style={{ width: 1, height: 22, marginHorizontal: 6, backgroundColor: colors.border }}
+          />
+        ) : (
+          <IconButton
+            key={item.icon}
+            // OUTSIDE the field, these are standalone controls rather than
+            // furniture inside one — and a standalone control is the band's
+            // height. Inside the frame `md` was right; on their own they read
+            // as undersized next to every other control on the page.
+            size="lg"
+            icon={item.icon}
+            tooltip={item.tooltip}
+            onPress={item.onPress}
+            disabled={inert}
+            iconColor={item.active ? colors.zinc[900] : colors.zinc[600]}
+            style={{
+              borderRadius: 8,
+              backgroundColor: item.active ? colors.zinc[200] : "transparent",
+            }}
+          />
+        ),
+      )}
+    </View>
+  );
+}