@elabs-ai/components-editor 4.0.0 → 4.2.0

package/src/markdown-academic/math.tsx

@@ -14,6 +14,7 @@
  * a contained error, never crashes the page). a11y: `output: "htmlAndMathml"`
  * emits MathML (read by assistive tech) alongside the visual HTML.
  */
+import { useLocale } from "@elabs-ai/components-ui";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 import katex from "katex";
 import { useMemo, type HTMLAttributes } from "react";
@@ -96,13 +97,14 @@ export interface MathProps extends Omit<HTMLAttributes<HTMLElement>, "children">
 
 /** Inline math (`$…$`) → KaTeX, in the text flow. */
 export function MathInline({ tex, className, ...props }: MathProps) {
+  const { t } = useLocale();
   const { html, error } = useMemo(() => renderKatex(tex, false), [tex]);
   if (error) {
     return (
       <code
         className={cn("text-destructive-text", className)}
-        aria-label={`Math (could not render): ${tex}`}
-        title="Could not render math"
+        aria-label={t("editor.math.renderErrorLabel", { tex })}
+        title={t("editor.math.renderError")}
         {...props}
       >
         {tex}
@@ -125,6 +127,7 @@ export function MathInline({ tex, className, ...props }: MathProps) {
 
 /** Block math (`$$…$$`) → centered display KaTeX. */
 export function MathBlock({ tex, className, ...props }: MathProps) {
+  const { t } = useLocale();
   const { html, error } = useMemo(() => renderKatex(tex, true), [tex]);
   if (error) {
     return (
@@ -133,8 +136,8 @@ export function MathBlock({ tex, className, ...props }: MathProps) {
           "overflow-x-auto rounded-md bg-surface-muted p-3 text-destructive-text",
           className,
         )}
-        aria-label={`Math (could not render): ${tex}`}
-        title="Could not render math"
+        aria-label={t("editor.math.renderErrorLabel", { tex })}
+        title={t("editor.math.renderError")}
         {...props}
       >
         <code>{tex}</code>

package/src/markdown-academic/toc.tsx

@@ -75,7 +75,7 @@ export const TableOfContents = forwardRef<HTMLElement, TableOfContentsProps>(
             <li key={it.id} className={INDENT[Math.min(it.level - minLevel, INDENT.length - 1)]}>
               <a
                 href={`#${it.id}`}
-                className="text-muted-foreground underline hover:text-foreground hover:underline focus-visible:rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                className="text-muted-foreground underline hover:text-foreground hover:underline focus-visible:rounded-sm focus-ring"
               >
                 {it.text}
               </a>

package/src/markdown-editor/completions/completions-menu.tsx

@@ -8,6 +8,7 @@
  * Same visual grammar (bg-popover, accent selection) for consistency with the
  * slash popup and Monaco's own themed suggest widget.
  */
+import { useLocale } from "@elabs-ai/components-ui";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 import { forwardRef, type HTMLAttributes } from "react";
 
@@ -38,17 +39,19 @@ export const CompletionMenu = forwardRef<HTMLDivElement, CompletionMenuProps>(
       activeIndex,
       onSelect,
       idPrefix = "brand-completions",
-      emptyLabel = "No suggestions",
+      emptyLabel: emptyLabelProp,
       className,
       ...props
     },
     ref,
   ) {
+    const { t } = useLocale();
+    const emptyLabel = emptyLabelProp ?? t("editor.completions.noSuggestions");
     return (
       <div
         ref={ref}
         role="listbox"
-        aria-label="Suggestions"
+        aria-label={t("editor.completions.suggestions")}
         className={cn(
           "max-h-[min(280px,50vh)] w-64 overflow-y-auto overflow-x-hidden rounded-md bg-popover p-1 text-popover-foreground shadow-ring-md",
           className,

package/src/markdown-editor/directive-views.tsx

@@ -46,6 +46,7 @@ import {
   DropdownMenuSubContent,
   DropdownMenuSubTrigger,
   DropdownMenuTrigger,
+  useLocale,
 } from "@elabs-ai/components-ui";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 import { editorViewCtx, parserCtx, serializerCtx } from "@milkdown/kit/core";
@@ -170,16 +171,14 @@ function InlineEdit({ value, onCommit, ariaLabel, placeholder, className }: Inli
       spellCheck={false}
       onBlur={commit}
       onKeyDown={onKeyDown}
-      className={cn(
-        "brand-inline-edit rounded-sm outline-none focus-visible:ring-2 focus-visible:ring-ring",
-        className,
-      )}
+      className={cn("brand-inline-edit rounded-sm focus-ring", className)}
     />
   );
 }
 
 /** `:::name` block directives → live @brand component with an editable body. */
 function ContainerDirectiveView() {
+  const { t } = useLocale();
   const { contentRef } = useNodeViewContext();
   const { name, attributes, update } = useDirectiveAttrs();
 
@@ -192,8 +191,8 @@ function ContainerDirectiveView() {
         <CardHeader className="pb-3">
           <CardTitle>
             <InlineEdit
-              ariaLabel="Card title"
-              placeholder="Card title"
+              ariaLabel={t("editor.directiveViews.cardTitle")}
+              placeholder={t("editor.directiveViews.cardTitle")}
               value={attributes.title ?? ""}
               onCommit={(v) => update("title", v)}
             />
@@ -216,7 +215,7 @@ function ContainerDirectiveView() {
             flow, so its label must not join the document heading outline (see #21). */}
         <div className="mb-1 font-medium leading-none tracking-tight">
           <InlineEdit
-            ariaLabel="Callout title"
+            ariaLabel={t("editor.directiveViews.calloutTitle")}
             placeholder={capitalize(attributes.type ?? "note")}
             value={attributes.title ?? ""}
             onCommit={(v) => update("title", v)}
@@ -253,7 +252,9 @@ function ContainerDirectiveView() {
       className="brand-directive brand-directive--unknown"
       data-brand-directive={name}
     >
-      <div className="mb-1 font-medium leading-none tracking-tight">Unknown block: {name}</div>
+      <div className="mb-1 font-medium leading-none tracking-tight">
+        {t("editor.directiveViews.unknownBlock", { name })}
+      </div>
       <AlertDescription>{body}</AlertDescription>
     </Alert>
   );
@@ -495,6 +496,7 @@ function IterationMenuItems({
  * inline (today's behaviour, unchanged).
  */
 function IterationDirectiveView() {
+  const { t } = useLocale();
   const { contentRef, node, getPos, setAttrs } = useNodeViewContext();
   const { name, attributes } = useDirectiveAttrs();
   const [, getInstance] = useInstance();
@@ -580,7 +582,7 @@ function IterationDirectiveView() {
       attributes: attributes as Record<string, string>,
     }).cells.length > 0;
 
-  const disabledHint = "— needs embedded values";
+  const disabledHint = t("editor.directiveViews.needsEmbeddedValues");
 
   const convertToStatic = () => {
     const template = readBodyMarkdown(getInstance as GetEditor, node);
@@ -592,14 +594,14 @@ function IterationDirectiveView() {
     {
       type: "item",
       id: "edit",
-      label: "Edit iteration…",
+      label: t("editor.directiveViews.editIteration"),
       icon: <Pencil className="size-4" aria-hidden="true" />,
       onSelect: requestEdit,
     },
     {
       type: "layout",
       id: "layout",
-      label: "Change layout",
+      label: t("editor.directiveViews.changeLayout"),
       icon: <LayoutGrid className="size-4" aria-hidden="true" />,
       value: (attributes.layout as IterationLayout) || ITERATION_LAYOUTS[kind][0]!,
       options: ITERATION_LAYOUTS[kind],
@@ -610,7 +612,9 @@ function IterationDirectiveView() {
           {
             type: "item",
             id: "transpose",
-            label: hasEmbeddedData ? "Transpose" : `Transpose ${disabledHint}`,
+            label: hasEmbeddedData
+              ? t("editor.directiveViews.transpose")
+              : `${t("editor.directiveViews.transpose")} ${disabledHint}`,
             icon: <ArrowLeftRight className="size-4" aria-hidden="true" />,
             onSelect: transpose,
             disabled: !hasEmbeddedData,
@@ -620,7 +624,9 @@ function IterationDirectiveView() {
     {
       type: "item",
       id: "convert-to-static",
-      label: hasEmbeddedData ? "Convert to static" : `Convert to static ${disabledHint}`,
+      label: hasEmbeddedData
+        ? t("editor.directiveViews.convertToStatic")
+        : `${t("editor.directiveViews.convertToStatic")} ${disabledHint}`,
       icon: <FileText className="size-4" aria-hidden="true" />,
       onSelect: convertToStatic,
       disabled: !hasEmbeddedData,
@@ -630,11 +636,15 @@ function IterationDirectiveView() {
   const header = (
     <div className="mb-1.5 flex items-center gap-1.5 text-meta font-medium text-info-text">
       <Icon className="size-3.5 shrink-0" aria-hidden="true" />
-      <span>{isPivot ? "Pivot" : "Iterate"}</span>
+      <span>{isPivot ? t("editor.directiveViews.pivot") : t("editor.directiveViews.iterate")}</span>
       {!isPivot && attributes.as ? (
-        <span className="font-normal text-muted-foreground">· per {attributes.as}</span>
+        <span className="font-normal text-muted-foreground">
+          {t("editor.directiveViews.perItem", { as: attributes.as })}
+        </span>
       ) : null}
-      <span className="font-normal text-muted-foreground">— template</span>
+      <span className="font-normal text-muted-foreground">
+        {t("editor.directiveViews.templateSuffix")}
+      </span>
       {onEdit ? (
         <DropdownMenu>
           <DropdownMenuTrigger asChild>
@@ -642,9 +652,9 @@ function IterationDirectiveView() {
               type="button"
               // `data-directive-chrome` routes the click to the browser, not ProseMirror.
               data-directive-chrome=""
-              aria-label="Iteration actions"
-              title="Iteration actions…"
-              className="ms-auto inline-flex size-5 items-center justify-center rounded-sm text-muted-foreground hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+              aria-label={t("editor.directiveViews.iterationActions")}
+              title={t("editor.directiveViews.iterationActionsTitle")}
+              className="ms-auto inline-flex size-5 items-center justify-center rounded-sm text-muted-foreground hover:bg-accent hover:text-foreground focus-ring"
             >
               <MoreHorizontal className="size-4" aria-hidden="true" />
             </button>
@@ -703,6 +713,7 @@ function IterationDirectiveView() {
 
 /** `::name` leaf directives (e.g. `::metric`) → live, atomic @brand component. */
 function LeafDirectiveView() {
+  const { t } = useLocale();
   const { name, attributes, update } = useDirectiveAttrs();
 
   if (name !== "metric") {
@@ -711,7 +722,7 @@ function LeafDirectiveView() {
         className="brand-directive brand-directive--leaf brand-directive--unknown rounded-md border border-destructive/40 bg-surface-muted p-3 text-sm text-muted-foreground"
         data-brand-leaf={name}
       >
-        Unknown inline block: <code>::{name}</code>
+        {t("editor.directiveViews.unknownInlineBlock")} <code>::{name}</code>
       </div>
     );
   }
@@ -723,16 +734,16 @@ function LeafDirectiveView() {
       data-brand-leaf="metric"
       label={
         <InlineEdit
-          ariaLabel="Metric label"
-          placeholder="Label"
+          ariaLabel={t("editor.directiveViews.metricLabel")}
+          placeholder={t("editor.directiveViews.metricLabelPlaceholder")}
           value={attributes.label ?? ""}
           onCommit={(v) => update("label", v)}
         />
       }
       value={
         <InlineEdit
-          ariaLabel="Metric value"
-          placeholder="0"
+          ariaLabel={t("editor.directiveViews.metricValue")}
+          placeholder={t("editor.directiveViews.metricValuePlaceholder")}
           value={attributes.value ?? ""}
           onCommit={(v) => update("value", v)}
           className="min-w-[1ch]"

package/src/markdown-editor/markdown-editor.css

@@ -3,12 +3,18 @@
  *
  * Milkdown core ships ZERO styles (headless), so this is where brand-ui owns the
  * look. Every value is a semantic design token (var(--foreground), --border,
- * --radius, …) — NO raw colors — so the editor matches all three themes
+ * --radius, …) — NO raw colors — so the editor matches every theme
  * (light/dark) for free. Every rule
  * is scoped under `.milkdown-host` so nothing leaks globally.
  */
 
 .milkdown-host .ProseMirror {
+  /* Suppresses the platform default outline — NOT a bare removal: the
+     `:focus-visible` rule below is the replacement, drawn on this same
+     element (#309). It owns the indicator unconditionally, so it can't be
+     clipped by an ancestor and can't be deleted by a consumer `className`
+     reaching `cn()` on the wrapper (`markdown-editor.tsx`'s root `div`
+     intentionally carries no focus-ring utility of its own — see #67/#309). */
   outline: none;
   padding: 1rem 1.1rem;
   min-height: 9rem;
@@ -23,8 +29,25 @@
   margin-inline: auto;
 }
 
-.milkdown-host .ProseMirror:focus {
-  outline: none;
+/* Focus indicator (#309) — a compound two-layer shape mirroring the
+   `focus-ring-inset` Tailwind utility (`packages/tokens/src/themes.css`,
+   ADR 0027), hand-written because this stylesheet is a plain side-effect CSS
+   import resolved by the CONSUMER's bundler — not guaranteed to run through
+   Tailwind, so `@apply`/utility classes aren't reachable here (verified:
+   `@apply` appears zero times in any .css file in this repo). Drawn INSIDE
+   the editable's own box (`outline-offset: -3px`, an inset `box-shadow`), so
+   it can't be clipped by an ancestor and survives a consumer `className`
+   deleting the wrapper's classes (`MarkdownWorkspace` already does this via
+   `className="border-0"`). Two layers of opposite value so at least one edge
+   clears 3:1 against the ground whatever `--ring` resolves to in a given
+   theme (`--ring-contour` is the dedicated contour token — `themes-contrast.
+   test.ts`'s `INDICATOR_SURFACES` locks `max(ring, contour) >= 3:1` at the
+   token level; `markdown-editor.stories.tsx`'s `FocusIndicator` play
+   re-measures it on this rendered surface, both themes). */
+.milkdown-host .ProseMirror:focus-visible {
+  outline: 1px solid var(--ring-contour);
+  outline-offset: -3px;
+  box-shadow: inset 0 0 0 2px var(--ring);
 }
 
 /* ----------------------------------------------------------------------------

package/src/markdown-editor/markdown-editor.focus.test.ts

@@ -0,0 +1,49 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+// Read the stylesheet as text. The repo runs vitest per-package (turbo /
+// `--filter`), so cwd is the package root — `src/...` resolves deterministically.
+const css = readFileSync(resolve(process.cwd(), "src/markdown-editor/markdown-editor.css"), "utf8");
+
+/**
+ * #309: `.ProseMirror` used to suppress the platform focus outline
+ * (`outline: none`, repeated as a dead no-op at `:focus`) with no replacement
+ * on the element itself — the only stand-in lived on a DIFFERENT element in a
+ * different file (`markdown-editor.tsx`'s wrapper `focus-ring-within` class),
+ * an implicit, unlocked, easily-overridden dependency raw CSS can't express.
+ * jsdom doesn't apply real focus/outline rendering, so this locks the
+ * stylesheet TEXT deterministically; `markdown-editor.stories.tsx`'s
+ * `FocusIndicator` play is the rendered-surface proof (resolved computed
+ * values, real contrast, both themes).
+ */
+describe("editor focus indicator CSS (regression, #309)", () => {
+  it("gives the editable its own :focus-visible indicator with a real outline", () => {
+    const focusVisibleRule = css.match(/\.milkdown-host \.ProseMirror:focus-visible\s*\{([^}]*)\}/);
+    expect(
+      focusVisibleRule,
+      "expected a .milkdown-host .ProseMirror:focus-visible rule",
+    ).not.toBeNull();
+    const body = focusVisibleRule![1]!;
+    expect(body).toMatch(/outline:\s*(?!none\b)\S/);
+  });
+
+  it("never suppresses the outline on a :focus/:focus-visible rule with nothing else in it", () => {
+    // A rule whose ENTIRE body is `outline: none;` (whitespace only otherwise)
+    // on a focus selector is exactly the dead-suppression defect #309 found —
+    // catches a future edit re-adding `.ProseMirror:focus { outline: none; }`
+    // (or a :focus-visible equivalent) with no compensating declaration.
+    const focusRules = [...css.matchAll(/([.\w-]+:focus(?:-visible)?)\s*\{([^}]*)\}/g)];
+    for (const [, selector, body] of focusRules) {
+      const bareOutlineNone = /^\s*outline:\s*none;?\s*$/.test(body!);
+      expect(
+        bareOutlineNone,
+        `${selector} suppresses outline with no replacement in the same rule`,
+      ).toBe(false);
+    }
+  });
+
+  it("no longer contains the dead .ProseMirror:focus { outline: none; } rule", () => {
+    expect(css).not.toMatch(/\.milkdown-host \.ProseMirror:focus\s*\{\s*outline:\s*none;?\s*\}/);
+  });
+});

package/src/markdown-editor/markdown-editor.stories.tsx

@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
-import { expect, waitFor, within } from "storybook/test";
+import { expect, userEvent, waitFor, within } from "storybook/test";
 import { useRef, useState } from "react";
 import { ThemeProvider } from "@elabs-ai/components-tokens";
 import { MarkdownEditor, type MarkdownEditorHandle } from "./markdown-editor";
@@ -14,9 +14,12 @@ const meta = {
     docs: {
       description: {
         component:
+          "The WYSIWYG markdown surface; the Monaco SOURCE editor is `Editor/CodeEditor` " +
+          "and the read-only render is `Editor/MarkdownPreview` — see " +
+          "[Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs). " +
           "A headless Milkdown (ProseMirror) WYSIWYG markdown surface vendored onto " +
           "brand-ui. Companion to the Monaco `CodeEditor` (source) in the same package. " +
-          "Theming is 100% semantic tokens, so it tracks all three themes via `data-theme`. " +
+          "Theming is 100% semantic tokens, so it tracks every theme via `data-theme`. " +
           "Depends on only `@milkdown/kit` — no Vue/Crepe.",
       },
     },
@@ -138,7 +141,7 @@ Two upstream data sources are still un-mapped.
  * The brand `:::` directives render as the REAL @brand components inside the editor
  * (a live `Card`, `Alert`, `MetricBlock`), with the card/callout title and the metric
  * label/value editable inline — not the old token-styled `toDOM` chrome. Switch the
- * Storybook theme to confirm they track all three themes.
+ * Storybook theme to confirm they track every theme.
  */
 export const LiveDirectives: Story = {
   name: "Live directives (inline-editable)",
@@ -275,9 +278,9 @@ Prose continues normally after the table.
  * - Tab moves to the next cell; Shift+Tab to the previous.
  * - The serialized markdown (shown below the editor) stays lossless GFM.
  *
- * Three-theme sweep: switch the Storybook theme toolbar to verify the table
+ * Cross-theme sweep: switch the Storybook theme toolbar to verify the table
  * borders (`border-border-strong`), header tint (`bg-surface-muted`), and
- * toolbar chrome use only semantic tokens across all three themes.
+ * toolbar chrome use only semantic tokens across every theme.
  */
 export const EditableTable: Story = {
   name: "Editable table (wysiwyg-tables)",
@@ -342,7 +345,14 @@ export const FillsContainer: Story = {
     await expect(editable).toBeVisible();
     // The 1-line doc's editable fills the 700px container (well past the ~144px
     // content floor) — clickable everywhere, with room for the `/` menu.
-    expect(editable.clientHeight).toBeGreaterThan(500);
+    //
+    // Waited for, not read once: the fill chain is `.milkdown-host .ProseMirror.editor
+    // { flex: 1 1 auto }`, and Milkdown adds the `editor` class in a later commit than
+    // the one that puts `role="textbox"` in the DOM. Between the two the editable sits at
+    // its own `min-height: 9rem` (144px) inside an already-700px host — measured, not
+    // guessed. Reading `clientHeight` on the frame `findByRole` resolves therefore samples
+    // a real but transient layout; the settled condition is the one this story is about.
+    await waitFor(() => expect(editable.clientHeight).toBeGreaterThan(500), { timeout: 8000 });
   },
 };
 
@@ -504,7 +514,7 @@ export const IterationContextMenu: Story = {
 };
 
 /**
- * Three-theme sweep for the node menu (#223 round-2): both `NodeMenu` (⋯) and
+ * Cross-theme sweep for the node menu (#223 round-2): both `NodeMenu` (⋯) and
  * `IterationContextMenu` (right-click) above run only under the toolbar's
  * DEFAULT theme (`light`) — Storybook's `defaultTheme` isn't overridable
  * per-story from the global decorator alone, and toggling `preview.tsx` by hand
@@ -558,3 +568,114 @@ export const IterationContextMenuHighDecoration: Story = {
   render: IterationContextMenu.render,
   play: IterationContextMenu.play,
 };
+
+/**
+ * #309 — the editable's own compound focus indicator. Resolves the governing
+ * theme element FROM THE SUBJECT (`el.closest("[data-theme]")`, never a
+ * guessed ancestor — quality-gates.md § Theme-safe), reads RESOLVED computed
+ * values (not the class string — a class-string assertion passed on the
+ * previous, invisible wrapper ring, which is exactly how this shipped), and
+ * asserts at least one of the indicator's two layers clears 3:1 against the
+ * ground the editable sits on. `markdown-editor.focus.test.ts` locks the
+ * stylesheet TEXT; this is the rendered-surface proof.
+ */
+export const FocusIndicator: Story = {
+  name: "Focus indicator (#309)",
+  render: () => (
+    <div className="mx-auto max-w-3xl p-6">
+      <MarkdownEditor
+        defaultValue={"# Focus indicator\n\nClick or Tab into the editable below."}
+        aria-label="Markdown editor"
+      />
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const editable = await canvas.findByRole(
+      "textbox",
+      { name: "Markdown editor" },
+      { timeout: 8000 },
+    );
+    await expect(editable).toBeVisible();
+    expect(editable.classList.contains("ProseMirror")).toBe(true);
+
+    const wrapper = canvasElement.querySelector<HTMLElement>('[data-testid="markdown-editor"]');
+    expect(wrapper).not.toBeNull();
+
+    // Resolve ANY CSS colour string down to sRGB so a contrast ratio is a
+    // measurement, not an assumption — same helper `FlowNode`'s
+    // `FocusIndicator` lock uses for the flow-canvas half of this same fix
+    // family (#286).
+    const toSrgb = (colour: string): [number, number, number] => {
+      const surface = document.createElement("canvas");
+      surface.width = 1;
+      surface.height = 1;
+      const ctx = surface.getContext("2d")!;
+      ctx.fillStyle = colour;
+      ctx.fillRect(0, 0, 1, 1);
+      const [r, g, b] = ctx.getImageData(0, 0, 1, 1).data;
+      return [r! / 255, g! / 255, b! / 255];
+    };
+    const luminance = ([r, g, b]: [number, number, number]) => {
+      const lin = (v: number) => (v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4));
+      return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+    };
+    const contrast = (a: string, b: string) => {
+      const [hi, lo] = [luminance(toSrgb(a)), luminance(toSrgb(b))].sort((x, y) => y - x);
+      return (hi! + 0.05) / (lo! + 0.05);
+    };
+
+    // Resting: no indicator on the editable, and the wrapper draws no ring of
+    // its own either (#309 — exactly one indicator, never a doubled one).
+    await expect(getComputedStyle(editable).outlineStyle).toBe("none");
+    await expect(getComputedStyle(wrapper!).boxShadow).toBe("none");
+
+    // Click into the editable. `:focus-visible` matches on pointer click for
+    // a contenteditable surface per spec (unlike a plain <input>/<button>),
+    // so this is a faithful proxy for the real "click to edit" path.
+    await userEvent.click(editable);
+    await waitFor(() => {
+      expect(getComputedStyle(editable).outlineStyle).toBe("solid");
+    });
+
+    // Exactly one indicator: the wrapper still draws nothing.
+    await expect(getComputedStyle(wrapper!).boxShadow).toBe("none");
+
+    const ground = getComputedStyle(wrapper!).backgroundColor;
+    const contourInk = getComputedStyle(editable).outlineColor;
+    const ringInk = getComputedStyle(editable).getPropertyValue("--ring").trim();
+    const contourRatio = contrast(contourInk, ground);
+    const ringRatio = contrast(ringInk, ground);
+    const bestRatio = Math.max(contourRatio, ringRatio);
+    await expect(
+      bestRatio,
+      `focus indicator vs editor ground: contour ${contourInk} = ${contourRatio.toFixed(2)}:1, ring ${ringInk} = ${ringRatio.toFixed(2)}:1`,
+    ).toBeGreaterThanOrEqual(3);
+
+    // Blur restores the resting state.
+    (editable as HTMLElement).blur();
+    await waitFor(() => {
+      expect(getComputedStyle(editable).outlineStyle).toBe("none");
+    });
+  },
+};
+
+export const FocusIndicatorDark: Story = {
+  name: "Focus indicator (#309) — dark",
+  decorators: [
+    (Story) => (
+      <ThemeProvider defaultTheme="dark" storageKey={null}>
+        <Story />
+      </ThemeProvider>
+    ),
+  ],
+  render: FocusIndicator.render,
+  play: FocusIndicator.play,
+};
+
+export const FocusIndicatorHighDecoration: Story = {
+  name: "Focus indicator (#309) — high decoration",
+  globals: { decoration: "10" },
+  render: FocusIndicator.render,
+  play: FocusIndicator.play,
+};

package/src/markdown-editor/markdown-editor.tsx

@@ -7,7 +7,7 @@
  *
  * - Engine dep: only `@milkdown/kit` (headless). React glue is vendored under
  *   ./milkdown-react so we never pull `@milkdown/react` → `@milkdown/crepe` → Vue.
- * - Theming: token-driven via markdown-editor.css (all three themes, no raw color).
+ * - Theming: token-driven via markdown-editor.css (every theme, no raw color).
  * - Controlled (`value` + `onChange`) or uncontrolled (`defaultValue`). Mirrors the
  *   platform: `isControlled = value !== undefined`; never flips between modes.
  * - StrictMode-safe (see markdown-editor.strictmode.test.tsx).
@@ -527,10 +527,13 @@ export const MarkdownEditor = forwardRef<MarkdownEditorHandle, MarkdownEditorPro
       <div
         data-testid="markdown-editor"
         className={cn(
-          // A 1px hairline focus ring (not a heavy 2px ring) — the editable is a
-          // large surface, so a thinner edit-mode ring reads calmer while still
-          // meeting the visible-focus requirement (same `ring` token). (A7)
-          "milkdown-host overflow-auto rounded-md border border-border bg-background text-foreground focus-within:ring-1 focus-within:ring-ring",
+          // No focus-ring utility here (deliberately, #309): the editable
+          // `.ProseMirror` element owns the compound focus indicator itself
+          // (`markdown-editor.css`'s `:focus-visible` rule), so it renders
+          // even when a consumer `className` overrides this wrapper's
+          // classes (`MarkdownWorkspace` does exactly that via
+          // `className="border-0"`) and never doubles up with a wrapper ring.
+          "milkdown-host overflow-auto rounded-md border border-border bg-background text-foreground",
           className,
         )}
         // Publish the shared markdown scale as CSS vars the editor CSS reads, so the

package/src/markdown-editor/milkdown-react/use-get-editor.timer-leak.test.ts

@@ -0,0 +1,80 @@
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import { createElement } from "react";
+import { afterEach, expect, test, vi } from "vitest";
+
+import { MarkdownEditor } from "../markdown-editor";
+import { waitForPendingMilkdownTeardown } from "./use-get-editor";
+
+afterEach(cleanup);
+
+// @milkdown/ctx's internal `Timer` (armed by `Ctx.wait()`, which
+// `@milkdown/core`'s `create()`/`destroy()` call internally for every
+// `createTimer(name)` — e.g. `ConfigReady`, `InitReady`, `EditorViewReady`)
+// uses `TimerType`'s default delay: `createTimer(name, timeout = 3e3)`,
+// never overridden anywhere in this repo's editor setup.
+const MILKDOWN_TIMER_DELAY_MS = 3000;
+
+/**
+ * Locks issue #84: `@milkdown/ctx`'s `Timer` class starts a 3-second
+ * `setTimeout` on every wait and never clears the handle on the resolve
+ * path — only the DOM/global event listener is removed
+ * (`lib/index.js:281-288`, vendored `@milkdown/ctx@7.21.2`). That leaves the
+ * timer armed for up to 3s after the promise it backs has already settled,
+ * and if it fires after Vitest has recycled the test file's jsdom
+ * environment, its callback's bare (unqualified) `removeEventListener` call
+ * throws `ReferenceError: removeEventListener is not defined` — the
+ * mechanism behind #65's originally-reported error.
+ *
+ * A bare "was `clearTimeout` called at some point" assertion would pass
+ * regardless of this bug, since unrelated React/ProseMirror machinery also
+ * calls `clearTimeout`. So this test tracks every `setTimeout` handle armed
+ * with Milkdown's exact 3-second delay, and every `clearTimeout` call, and
+ * asserts each such handle is cleared once Milkdown's own teardown
+ * (`waitForPendingMilkdownTeardown`, tracked in `use-get-editor.ts`) has
+ * settled. Against the unpatched `@milkdown/ctx` dependency this fails (no
+ * `clearTimeout` call in the vendored file at all — `grep -c clearTimeout`
+ * returns 0); the `patches/@milkdown__ctx@7.21.2.patch` fix (storing the
+ * handle and clearing it in `#removeListener`, which both the resolve and
+ * reject/timeout paths already call) makes it pass.
+ */
+test("clears the vendored @milkdown/ctx wait timer on teardown (#84)", async () => {
+  const originalSetTimeout = globalThis.setTimeout;
+  const originalClearTimeout = globalThis.clearTimeout;
+
+  const armedHandles = new Set<ReturnType<typeof setTimeout>>();
+  const clearedHandles = new Set<Parameters<typeof clearTimeout>[0]>();
+
+  vi.spyOn(globalThis, "setTimeout").mockImplementation(((
+    handler: TimerHandler,
+    timeout?: number,
+    ...args: unknown[]
+  ) => {
+    const handle = originalSetTimeout(handler as never, timeout, ...args);
+    if (timeout === MILKDOWN_TIMER_DELAY_MS) armedHandles.add(handle);
+    return handle;
+  }) as unknown as typeof setTimeout);
+
+  vi.spyOn(globalThis, "clearTimeout").mockImplementation(((
+    handle?: Parameters<typeof clearTimeout>[0],
+  ) => {
+    clearedHandles.add(handle);
+    return originalClearTimeout(handle as never);
+  }) as unknown as typeof clearTimeout);
+
+  const { unmount } = render(createElement(MarkdownEditor, { defaultValue: "# Hello Timer" }));
+  await waitFor(() => expect(screen.getByText("Hello Timer")).toBeInTheDocument());
+
+  unmount();
+  await waitForPendingMilkdownTeardown();
+
+  vi.restoreAllMocks();
+
+  // Sanity: the mechanism under test actually armed at least one 3-second
+  // wait timer during create()/destroy() — otherwise the loop below would
+  // trivially pass over an empty set.
+  expect(armedHandles.size).toBeGreaterThan(0);
+
+  for (const handle of armedHandles) {
+    expect(clearedHandles.has(handle)).toBe(true);
+  }
+});