@podoba/react 0.0.29 → 0.0.32

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@podoba/react",
-	"version": "0.0.29",
+	"version": "0.0.32",
 	"type": "module",
 	"description": "podoba React components — React Aria Components + Tailwind primitives + layout, built with uic.",
 	"repository": {
@@ -13,7 +13,8 @@
 	"main": "./src/index.ts",
 	"types": "./src/index.ts",
 	"exports": {
-		".": "./src/index.ts"
+		".": "./src/index.ts",
+		"./editor": "./src/editor/index.ts"
 	},
 	"files": [
 		"src",
@@ -27,17 +28,48 @@
 		"typecheck": "tsc --build"
 	},
 	"dependencies": {
-		"@podoba/tokens": "^0.0.29",
-		"@podoba/tailwind": "^0.0.29",
+		"@podoba/tokens": "^0.0.32",
+		"@podoba/tailwind": "^0.0.32",
 		"react-aria-components": "1.18.0",
 		"class-variance-authority": "0.7.1",
 		"clsx": "2.1.1",
 		"tailwind-merge": "3.6.0",
 		"@radix-ui/react-slot": "1.2.4"
 	},
+	"//tiptap": "Only `@podoba/react/editor` (BlockEditor) needs Tiptap. Optional peers, not dependencies: the base package must not make every consumer install ProseMirror, and a peer keeps ONE @tiptap/pm in the tree — two copies of prosemirror-model break instanceof across the editor.",
 	"peerDependencies": {
 		"react": ">=19",
-		"react-dom": ">=19"
+		"react-dom": ">=19",
+		"@tiptap/react": "^3.27.4",
+		"@tiptap/pm": "^3.27.4",
+		"@tiptap/starter-kit": "^3.27.4",
+		"@tiptap/extension-placeholder": "^3.27.4",
+		"@tiptap/extension-highlight": "^3.27.4",
+		"@tiptap/extension-task-list": "^3.27.4",
+		"@tiptap/extension-task-item": "^3.27.4"
+	},
+	"peerDependenciesMeta": {
+		"@tiptap/react": {
+			"optional": true
+		},
+		"@tiptap/pm": {
+			"optional": true
+		},
+		"@tiptap/starter-kit": {
+			"optional": true
+		},
+		"@tiptap/extension-placeholder": {
+			"optional": true
+		},
+		"@tiptap/extension-highlight": {
+			"optional": true
+		},
+		"@tiptap/extension-task-list": {
+			"optional": true
+		},
+		"@tiptap/extension-task-item": {
+			"optional": true
+		}
 	},
 	"devDependencies": {
 		"react": "^19.2.1",
@@ -45,6 +77,13 @@
 		"@types/react": "^19.2.7",
 		"@types/react-dom": "^19.2.3",
 		"typescript": "^5.9.3",
-		"@types/bun": "^1.3.3"
+		"@types/bun": "^1.3.3",
+		"@tiptap/react": "^3.27.4",
+		"@tiptap/pm": "^3.27.4",
+		"@tiptap/starter-kit": "^3.27.4",
+		"@tiptap/extension-placeholder": "^3.27.4",
+		"@tiptap/extension-highlight": "^3.27.4",
+		"@tiptap/extension-task-list": "^3.27.4",
+		"@tiptap/extension-task-item": "^3.27.4"
 	}
 }

package/src/components/brand-page-header.tsx

@@ -1,5 +1,6 @@
 import { type ReactNode, useState } from 'react'
 import { Button } from './button'
+import { DisplayHeading } from './text'
 
 /**
  * BrandPageHeader — the brand-workspace page header (port of gs-platform
@@ -36,7 +37,8 @@ export type BrandPageHeaderProps = {
 	 * gs-style "title to go back": a muted, clickable PARENT link rendered as the
 	 * line ABOVE the title (so the title reads "Parent ⏎ Current"). Pass a real
 	 * router `<Link>` so it's an anchor (cmd/middle-click, deep-link-safe), exactly
-	 * like gs's `parentLink`. The header styles it muted with a hover→fg affordance.
+	 * like gs's `parentLink`. The header uses the source's decorative `fg-subtle`
+	 * (#b3b3b3) with a hover→fg affordance.
 	 */
 	parentLink?: ReactNode
 	/** Optional breadcrumb trail rendered above the greeting. */
@@ -81,7 +83,7 @@ export function BrandPageHeader({
 	const isControlled = expandedProp !== undefined
 	const expanded = isControlled ? expandedProp : internalExpanded
 	const hasExpandable = Boolean(createHub)
-	const Heading = `h${headingLevel}` as const
+	const HeadingTag = `h${headingLevel}` as const
 
 	const setExpanded = (next: boolean) => {
 		if (!isControlled) setInternalExpanded(next)
@@ -98,8 +100,8 @@ export function BrandPageHeader({
 				.filter(Boolean)
 				.join(' ')}
 		>
-			<div className="flex flex-col gap-2 sm:flex-row sm:items-start sm:gap-4">
-				<div className="flex min-w-0 flex-1 flex-col gap-1">
+			<div className="flex flex-col gap-2 sm:grid sm:grid-cols-3 sm:items-stretch sm:gap-4">
+				<div className="flex min-w-0 flex-1 flex-col gap-1 sm:col-span-2">
 					{breadcrumbs && breadcrumbs.length > 0 ? (
 						<nav aria-label="Breadcrumb" className="flex flex-wrap items-center gap-1 text-compact text-fg-muted">
 							{breadcrumbs.map((crumb, i) => (
@@ -120,25 +122,27 @@ export function BrandPageHeader({
 							))}
 						</nav>
 					) : null}
-					<Heading className="text-display font-medium leading-[1.12] tracking-wide text-fg">
-						{parentLink ? (
-							// gs "title to go back": muted clickable parent line above the title.
-							// `[&_a]` styles the nested router <Link> (anchor) without @app/ui
-							// importing the router.
-							<>
-								<span className="text-fg-muted transition-colors [&_a:hover]:text-fg [&_a]:text-fg-muted [&_a]:no-underline [&_a]:outline-none [&_a:focus-visible]:underline">
-									{parentLink}
-								</span>
-								<br />
-							</>
-						) : null}
-						{greeting}
-					</Heading>
+					<DisplayHeading asChild className="tracking-tight">
+						<HeadingTag>
+							{parentLink ? (
+								// gs "title to go back": muted clickable parent line above the title.
+								// `[&_a]` styles the nested router <Link> (anchor) without @app/ui
+								// importing the router.
+								<>
+									<span className="text-fg-subtle transition-colors [&_a:hover]:text-fg [&_a]:text-fg-subtle [&_a]:no-underline [&_a]:outline-none [&_a:focus-visible]:underline">
+										{parentLink}
+									</span>
+									<br />
+								</>
+							) : null}
+							{greeting}
+						</HeadingTag>
+					</DisplayHeading>
 				</div>
 
 				{cta ? (
 					// Hero CTA spans 4 of 12 columns (one third) — the greeting takes the rest.
-					<div className="w-full shrink-0 sm:w-1/3">{cta}</div>
+					<div className="h-full min-w-0">{cta}</div>
 				) : ctaLabel ? (
 					<div className="shrink-0">
 						{hasExpandable ? (

package/src/components/button.tsx

@@ -19,11 +19,11 @@ export const Button = uic(RACButton, {
 		'data-[pending]:opacity-70 data-[pending]:cursor-progress',
 	variants: {
 		variant: {
-			// primary (gs `_primary`): base neutral-400 (#242423 = surface-inverted) →
-			// hover neutral-600 (#333333) + `0 0 5px rgba(0,0,0,.5)` shadow → active back
-			// to neutral-400 (surface-inverted, no shadow).
+			// primary (gs `_primary`): base brand-primary (#0d0d0d light / brand-green on
+			// dark) → hover neutral-600 (#333333) + `0 0 5px rgba(0,0,0,.5)` shadow →
+			// active back to brand-primary (no shadow).
 			primary:
-				'bg-surface-inverted text-fg-inverted hover:bg-neutral-600 hover:shadow-[0_0_5px_0_rgba(0,0,0,0.5)] data-[pressed]:bg-surface-inverted data-[pressed]:shadow-none',
+				'bg-brand-primary text-fg-inverted hover:bg-neutral-600 hover:shadow-[0_0_5px_0_rgba(0,0,0,0.5)] data-[pressed]:bg-brand-primary data-[pressed]:shadow-none',
 			// secondary: #f7f6f2 (surface-card) + 1px #eceae1 (border); hover bg #eceae1
 			// (surface-muted) + border #aba89c (fg-subtle); active bg #eceae1.
 			secondary:
@@ -39,6 +39,9 @@ export const Button = uic(RACButton, {
 			sm: 'py-2 px-4',
 			md: 'py-3 px-6',
 			lg: 'py-4 px-8',
+			// Task/workflow CTA: exact source 44px height, 24px inline padding,
+			// 17/20 medium text.
+			prominent: 'h-11 px-6 py-0 text-panel-heading font-medium',
 		},
 	},
 	defaultVariants: {
@@ -49,5 +52,5 @@ export const Button = uic(RACButton, {
 
 export type ButtonProps = RACButtonProps & {
 	variant?: 'primary' | 'secondary' | 'ghost' | 'destructive'
-	size?: 'sm' | 'md' | 'lg'
+	size?: 'sm' | 'md' | 'lg' | 'prominent'
 }

package/src/components/cta-pill.tsx

@@ -27,8 +27,8 @@ export interface CtaPillProps {
 
 export function CtaPill({ lead, emphasis, tail, children }: CtaPillProps) {
 	return (
-		<div className="flex w-full items-center justify-between gap-4 rounded-lg bg-brand-secondary px-6 py-4">
-			<p className="min-w-0 text-heading4 font-medium leading-[22px] tracking-normal text-fg-on-brand">
+		<div className="flex h-full min-h-16 w-full items-center justify-between gap-nav-x rounded-lg bg-brand-green py-2.5 pr-3 pl-4.5">
+			<p className="min-w-0 text-heading4 font-medium leading-5 tracking-tight text-fg-on-brand">
 				{lead} <span className="font-semibold">{emphasis}</span> {tail}
 			</p>
 			<div className="shrink-0">{children}</div>

package/src/components/dialog.tsx

@@ -4,8 +4,8 @@ import {
 	DialogTrigger as RACDialogTrigger,
 	type DialogProps as RACDialogProps,
 	Heading,
-	Modal,
-	ModalOverlay,
+	Modal as RACModal,
+	ModalOverlay as RACModalOverlay,
 } from 'react-aria-components'
 import { uic } from '../utils/uic'
 
@@ -18,25 +18,31 @@ import { uic } from '../utils/uic'
  */
 export const DialogTrigger = RACDialogTrigger
 
-// gs modal backdrop — gs `Dialog.module.scss` overlay: a neutral grey scrim
-// (`rgba(179,179,179,0.5)`) under a light `blur(2px)`.
-const Overlay = uic(ModalOverlay, {
+// Current gs modal backdrop: warm surface-card scrim at 66% under a 10px blur.
+export const ModalOverlay = uic(RACModalOverlay, {
 	displayName: 'DialogOverlay',
 	baseClass:
 		'fixed inset-0 z-50 flex items-center justify-center p-4 ' +
-		'bg-[rgba(179,179,179,0.5)] backdrop-blur-[2px] ' +
-		'data-[entering]:animate-in data-[exiting]:animate-out',
+		'bg-modal-backdrop backdrop-blur-modal-backdrop ' +
+		'data-[entering]:animate-modal-overlay-in data-[exiting]:animate-modal-overlay-out',
 })
 
-// gs content card: white bg, 20px padding (`p-5`), 8px radius (`rounded-lg`), and
-// the gs `Dialog.module.scss` card shadow — a light single-layer
-// `0 2px 8px rgba(0,0,0,.06)`. No border: gs defines the card with the shadow alone.
-const StyledModal = uic(Modal, {
+// gs content card: white bg, 20px padding, 8px radius and the shared two-layer
+// modal elevation.
+export const ModalSurface = uic(RACModal, {
 	displayName: 'DialogModal',
 	baseClass:
-		'rounded-lg bg-surface p-5 outline-none shadow-[0px_2px_8px_0px_rgba(0,0,0,0.06)]',
+		'rounded-lg bg-surface p-5 outline-none shadow-modal-surface ' +
+		'data-[entering]:animate-modal-surface-in data-[exiting]:animate-modal-surface-out',
 })
 
+/**
+ * Unstyled accessible dialog body for edge-to-edge / split modal compositions.
+ * Pair only with the shared {@link ModalOverlay} and {@link ModalSurface}; ordinary
+ * form and confirmation dialogs should use the composed {@link Dialog}.
+ */
+export const ModalDialog = RACDialog
+
 /**
  * Modal width presets. `md` (default) is the form/confirm dialog (gs DialogContent
  * default, 586px); `sm` is a tighter confirm; `lg`/`xl` host wider, taller content
@@ -126,18 +132,18 @@ export const Dialog = ({
 		// when omitted the overlay reads its state from an enclosing DialogTrigger.
 		// Either way the RACDialog render-prop `close` resolves against the active
 		// overlay state, so `close()` works in both modes.
-		<Overlay
-			// Full-screen is an immersive takeover: swap the light 2px scrim for a
-			// heavier backdrop blur so the page behind reads as clearly blurred around
-			// the near-fullscreen canvas. (tailwind-merge dedupes the base blur/scrim.)
-			className={isFlex ? "bg-black/25 backdrop-blur-lg" : undefined}
+		<ModalOverlay
+			// Full-screen is an immersive takeover: swap the light scrim for a heavier
+			// backdrop blur so the page behind reads as clearly blurred around the
+			// near-fullscreen canvas. (tailwind-merge dedupes the base blur/scrim.)
+			className={isFlex ? 'bg-black/25 backdrop-blur-lg' : undefined}
 			isOpen={isOpen}
 			defaultOpen={defaultOpen}
 			onOpenChange={onOpenChange}
 			isDismissable={isDismissable}
 		>
-			<StyledModal className={SIZE_CLASS[size]}>
-				<RACDialog
+			<ModalSurface className={SIZE_CLASS[size]}>
+				<ModalDialog
 					{...props}
 					className={isFlex ? 'flex min-h-0 flex-1 flex-col outline-none' : 'outline-none'}
 				>
@@ -200,8 +206,8 @@ export const Dialog = ({
 							)}
 						</>
 					)}
-				</RACDialog>
-			</StyledModal>
-		</Overlay>
+				</ModalDialog>
+			</ModalSurface>
+		</ModalOverlay>
 	)
 }

package/src/components/input.tsx

@@ -20,19 +20,20 @@ import { uic } from '../utils/uic'
  */
 const StyledInput = uic(RACInput, {
 	displayName: 'InputControl',
-	// White fill so the field reads as editable. The gs original used a cream
-	// (#f7f6f2 → surface-card) fill, but our Card surface is ALSO surface-card, so
-	// a filled field inside a card vanished and read as disabled. Inverted: active
-	// = white (surface), disabled = the muted cream. border #eceae1 → border ·
-	// hover #aba89c → fg-subtle · focus #75e7b8 → brand-green · error → danger.
-	// Identical to textarea.tsx's filled-field skin; `fieldSize` adds the
-	// single-line height (gs sizes the field via padding only).
+	// White fill + border so the field reads as editable. The gs original used a
+	// borderless cream (#f7f6f2 → surface-card) fill, but our Card surface is ALSO
+	// surface-card — and in dark theme surface-card and surface are the SAME colour
+	// (#242423) — so a borderless cream field vanishes on both. Inverted: active =
+	// surface, disabled = the muted cream. border #eceae1 → border · hover #aba89c →
+	// fg-subtle · focus #75e7b8 → brand-green · error → danger. This is the shared
+	// filled-field skin (textarea / combobox / date-field / number-field /
+	// search-field); `fieldSize` adds the single-line height on top.
 	baseClass:
 		'w-full rounded-lg border border-border bg-surface px-4 text-small text-fg ' +
 		'outline-none transition-colors duration-200 placeholder:text-fg-muted ' +
 		'data-[hovered]:border-fg-subtle ' +
 		'data-[focused]:border-brand-green data-[focused]:ring-2 data-[focused]:ring-ring ' +
-		'data-[invalid]:border-danger data-[invalid]:ring-danger ' +
+		'data-[invalid]:border-danger data-[invalid]:ring-2 data-[invalid]:ring-danger ' +
 		'data-[disabled]:bg-surface-muted data-[disabled]:opacity-60 data-[disabled]:pointer-events-none',
 	variants: {
 		// `fieldSize` (not `size`) to avoid colliding with the native <input size>
@@ -41,6 +42,7 @@ const StyledInput = uic(RACInput, {
 			sm: 'h-8',
 			md: 'h-10',
 			lg: 'h-12',
+			tall: 'h-control-tall',
 		},
 	},
 	defaultVariants: {
@@ -56,13 +58,17 @@ export type InputProps = TextFieldProps & {
 	/** Error message; pass a string for a static error or rely on validation. */
 	errorMessage?: string
 	placeholder?: string
-	size?: 'sm' | 'md' | 'lg'
+	size?: 'sm' | 'md' | 'lg' | 'tall'
+	/** Optional class for the TextField root. */
+	rootClassName?: string
+	/** Optional class for the inner native input (for product-specific composition). */
+	inputClassName?: string
 }
 
-export const Input = ({ label, description, errorMessage, placeholder, size, ...props }: InputProps) => (
-	<TextField {...props} className="flex w-full flex-col gap-2">
-		<Label className="text-heading5 font-medium text-fg">{label}</Label>
-		<StyledInput placeholder={placeholder} fieldSize={size} />
+export const Input = ({ label, description, errorMessage, placeholder, size, rootClassName, inputClassName, ...props }: InputProps) => (
+	<TextField {...props} className={`flex w-full flex-col gap-3 ${rootClassName ?? ''}`}>
+		<Label className="text-panel-heading font-medium text-fg">{label}</Label>
+		<StyledInput className={inputClassName} placeholder={placeholder} fieldSize={size} />
 		{description ? (
 			<Text slot="description" className="text-label text-fg-muted">
 				{description}

package/src/components/rich-text-editor.tsx

@@ -1,12 +1,19 @@
 import { type ClipboardEvent as ReactClipboardEvent, type ReactNode, useEffect, useRef } from 'react'
 import { clsx } from 'clsx'
+import { SAFE_LINK_HINT, safeLinkUrl } from '../utils/safe-link-url'
 import { useInFocusOverlay } from './focus-context'
 
 /**
  * RichTextEditor — a dependency-free contentEditable WYSIWYG that emits an HTML
  * string (round-trips with any `set:html` / `dangerouslySetInnerHTML` renderer,
  * so no value migration and no bundled ProseMirror). Ported from pramen's
- * cms-editor `RichText`; TipTap is the upgrade path if tables/embeds are needed.
+ * cms-editor `RichText`.
+ *
+ * Still the right pick for a short caption/bio field. For document-shaped content
+ * — blocks, a `/` palette, tables/embeds — reach for `BlockEditor` from
+ * `@podoba/react/editor` instead; it is the Tiptap-backed upgrade this component's
+ * `execCommand` core cannot grow into. Both emit the same HTML-string value, so
+ * swapping one for the other needs no data migration.
  *
  * The `prose prose-sm` body relies on the @tailwindcss/typography plugin, which
  * @podoba/tailwind's preset already registers.
@@ -32,7 +39,7 @@ const RT_TOOLS: Array<{ label: string; title: string; run: (exec: (c: string, a?
 			if (!raw) return
 			const url = safeLinkUrl(raw)
 			if (!url) {
-				window.alert('Only http(s), mailto, tel, or relative (/, #) links are allowed.')
+				window.alert(SAFE_LINK_HINT)
 				return
 			}
 			x('createLink', url)
@@ -42,13 +49,6 @@ const RT_TOOLS: Array<{ label: string; title: string; run: (exec: (c: string, a?
 	{ label: 'Clear', title: 'Clear formatting', run: (x) => x('removeFormat') },
 ]
 
-/** Allow-list for a link href: http(s), mailto, tel, or a relative/anchor path.
- * The prefix allow-list inherently rejects `javascript:`/`data:`/`vbscript:`. */
-function safeLinkUrl(raw: string): string | null {
-	const url = raw.trim()
-	return /^(https?:\/\/|mailto:|tel:|\/|#)/i.test(url) ? url : null
-}
-
 /** Cosmetic scrub (NOT a security boundary — sanitise on the server). */
 function scrubHtml(html: string): string {
 	return html

package/src/components/section-tabs.tsx

@@ -36,6 +36,10 @@ export type SectionTabsProps = {
 	resetLabel?: string
 	/** Glyph for the reset control; defaults to a small grid icon. */
 	resetIcon?: ReactNode
+	/** Visible reset content. When set, renders a source-style text tab (e.g. "Summary"). */
+	resetContent?: ReactNode
+	/** Whether the reset/overview destination is the currently selected section. */
+	isResetSelected?: boolean
 	className?: string
 }
 
@@ -49,12 +53,12 @@ const GridGlyph = () => (
 )
 
 const tabBase =
-	'inline-flex h-7 items-center gap-2 rounded-sm px-3 text-compact text-fg-muted outline-none ' +
-	'transition-colors duration-[120ms] ease-[ease] data-[hovered]:bg-surface-muted data-[hovered]:text-fg ' +
+	'inline-flex h-7 shrink-0 items-center gap-2 rounded-sm px-nav-x py-1.5 text-compact font-normal text-fg-muted outline-none ' +
+	'transition-colors duration-150 ease-in-out data-[hovered]:bg-surface-muted data-[hovered]:text-fg ' +
 	'data-[focus-visible]:ring-2 data-[focus-visible]:ring-ring ' +
 	'data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50 data-[disabled]:bg-transparent data-[disabled]:text-fg-muted'
 
-const tabActive = 'bg-surface-muted font-medium text-fg'
+const tabActive = 'bg-surface-muted text-fg'
 
 export function SectionTabs({
 	tabs,
@@ -64,19 +68,37 @@ export function SectionTabs({
 	onReset,
 	resetLabel = 'Reset',
 	resetIcon,
+	resetContent,
+	isResetSelected = false,
 	className,
 }: SectionTabsProps) {
 	return (
-		<div className={['flex flex-wrap items-center gap-1', className].filter(Boolean).join(' ')} role="group">
+		<div
+			className={[
+				'flex min-h-9 w-full flex-nowrap items-start gap-2 overflow-x-auto pb-2 [scrollbar-width:none] [&::-webkit-scrollbar]:hidden lg:w-2/3 lg:flex-wrap lg:overflow-visible lg:pb-0',
+				className,
+			]
+				.filter(Boolean)
+				.join(' ')}
+			role="group"
+		>
 			{onReset ? (
-				<Button
-					variant="ghost"
-					aria-label={resetLabel}
-					onPress={onReset}
-					className="h-7 w-7 rounded-sm p-0 text-fg-muted data-[hovered]:text-fg"
-				>
-					{resetIcon ?? <GridGlyph />}
-				</Button>
+				<div className="sticky left-0 z-10 shrink-0 bg-surface pr-1 lg:static lg:bg-transparent lg:pr-0">
+					<Button
+						variant="ghost"
+						aria-label={resetLabel}
+						aria-pressed={isResetSelected}
+						onPress={onReset}
+						className={[
+							resetContent ? tabBase : 'h-7 w-7 rounded-sm p-0 text-fg-muted data-[hovered]:text-fg',
+							isResetSelected ? tabActive : '',
+						]
+							.filter(Boolean)
+							.join(' ')}
+					>
+						{resetContent ?? resetIcon ?? <GridGlyph />}
+					</Button>
+				</div>
 			) : null}
 			{tabs.map((tab) => {
 				const selected = active === tab.key

package/src/components/select.tsx

@@ -21,21 +21,21 @@ import { useInFocusOverlay } from './focus-context'
  * RAC handles the listbox ARIA pattern, keyboard navigation, typeahead and
  * focus management. Styling via `uic`. Pass options as `SelectItem` children.
  *
- * Re-skinned 1:1 to gs-platform's designer spec (Figma GraphicStandard 1.5,
- * node 2115-4271 — `Select.module.scss`): a tall (min-h 58px) borderless filled
- * trigger on the cream `surface-card`, matching our `Input` / `Textarea` fill so
- * the form controls stay consistent. gs token map: bg #f7f6f2 → surface-card ·
- * hover #eceae1 → surface-muted · text #0d0d0d → fg · placeholder → fg-muted ·
+ * Re-skinned to gs-platform's designer spec (Figma GraphicStandard 1.5, node
+ * 2115-4271 — `Select.module.scss`): a tall (58px) filled trigger matching our
+ * `Input` / `Textarea` so the form controls stay consistent. gs token map:
+ * hover border #aba89c → fg-subtle · text #0d0d0d → fg · placeholder → fg-muted ·
  * 8px radius → rounded-lg · 6px item radius → rounded-md · error → danger.
  */
 const SelectTrigger = uic(RACButton, {
 	displayName: 'SelectTrigger',
-	// Sized to match the other form fields (Input / ComboBox): h-12, 16px side
-	// padding, 8px radius. White fill + border so the trigger doesn't vanish inside
-	// a Card (also surface-card) and read as disabled; hover darkens the border.
-	// Error → 2px danger ring driven off the RACSelect root's `data-invalid`.
+	// gs source control geometry (58px tall, 20px inline padding, 8px radius) with
+	// the shared bordered fill: gs draws it borderless on cream, but our Card is
+	// also surface-card and dark theme collapses surface-card onto surface, so a
+	// borderless cream trigger disappears. White fill + border keeps it visible and
+	// consistent with the other form controls; hover darkens the border.
 	baseClass:
-		'flex h-12 w-full items-center justify-between gap-2.5 rounded-lg border border-border bg-surface px-4 ' +
+		'flex h-control-tall w-full items-center justify-between gap-2.5 rounded-lg border border-border bg-surface px-5 ' +
 		'text-small text-fg outline-none transition-colors ' +
 		'data-[hovered]:border-fg-subtle ' +
 		'data-[focus-visible]:ring-2 data-[focus-visible]:ring-ring ' +
@@ -66,6 +66,10 @@ export type SelectProps<T extends object> = RACSelectProps<T> & {
 	 */
 	placeholder: string
 	children: ReactNode
+	/** Optional class for the Select root. */
+	rootClassName?: string
+	/** Optional class for the trigger (for product-specific composition). */
+	triggerClassName?: string
 }
 
 export const Select = <T extends object>({
@@ -74,6 +78,8 @@ export const Select = <T extends object>({
 	errorMessage,
 	placeholder,
 	children,
+	rootClassName,
+	triggerClassName,
 	...props
 }: SelectProps<T>) => {
 	// In a focus overlay, show the options inline (seamless) instead of a popover.
@@ -91,8 +97,8 @@ export const Select = <T extends object>({
 	const err = <FieldError className="text-label text-danger">{errorMessage}</FieldError>
 
 	return (
-		<RACSelect {...props} placeholder={placeholder} className="group flex flex-col gap-2">
-			<Label className="text-heading5 font-medium text-fg">{label}</Label>
+		<RACSelect {...props} placeholder={placeholder} className={`group flex flex-col gap-3 ${rootClassName ?? ''}`}>
+			<Label className="text-panel-heading font-medium text-fg">{label}</Label>
 			{inFocus ? (
 				<>
 					{listbox}
@@ -101,7 +107,7 @@ export const Select = <T extends object>({
 				</>
 			) : (
 				<>
-					<SelectTrigger>
+					<SelectTrigger className={triggerClassName}>
 						<SelectValue className="data-[placeholder]:text-fg-muted" />
 						{/* gs chevron: 9.5px caret, dark (neutral-400 → fg), non-interactive. */}
 						<svg

package/src/components/text.tsx

@@ -6,10 +6,12 @@ import { uic } from '../utils/uic'
  * They express the `@app/tokens` type ramp as variant props so screens stop
  * hand-writing `text-[NNpx]` literals (the scale, not arbitrary pixels). Two ramps:
  *
- *   • <Text> — the SIZE-ONLY UI ramp (micro · caption · label · compact · callout ·
- *     body · subtitle · title · headline · display). Like the tokens, these set
- *     font-size only; pair with `leading-*` via `className` where a fixed leading
- *     matters. `weight` + `tone` cover the common cases.
+ *   • <Text> — the UI ramp (micro · caption · label · compact · small · callout ·
+ *     body · subtitle · title · headline · display). Four of these carry the gs
+ *     source leading with them (compact 13/16, small 14/18, body 16/22,
+ *     display 28/30); the rest are size-only — pair those with `leading-*` via
+ *     `className` where a fixed leading matters. `weight` + `tone` cover the
+ *     common cases.
  *   • <Heading> — the semantic heading ramp (`level` 1–5 → text-heading1…5), which
  *     DO carry a matching line-height. Renders an <h2> by default; pass `asChild`
  *     to project the styles onto the correct heading element for the document
@@ -20,6 +22,25 @@ import { uic } from '../utils/uic'
  * no i18n.
  */
 
+/**
+ * The large product heading from the GS reference UI (`label-1` in its original
+ * token vocabulary): 30px / 32px / medium with -2px tracking.
+ *
+ * Kept separate from the 28px semantic Heading ramp because it is a reusable
+ * product-display treatment, not a document-outline level. Use `asChild` to project
+ * it onto the correct h1–h6 element.
+ */
+export const DisplayHeading = uic('h2', {
+	displayName: 'DisplayHeading',
+	baseClass: 'text-display-large font-medium text-fg',
+})
+
+/** Compact 17px / 20px section title used in workflow and dialog panels. */
+export const PanelHeading = uic('h3', {
+	displayName: 'PanelHeading',
+	baseClass: 'text-panel-heading font-medium text-fg',
+})
+
 export const Text = uic('span', {
 	displayName: 'Text',
 	baseClass: 'text-fg',

package/src/editor/block-editor.tsx

@@ -0,0 +1,522 @@
+import { useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from 'react'
+import { createPortal } from 'react-dom'
+import { EditorContent, useEditor, useEditorState, type Editor } from '@tiptap/react'
+import { BubbleMenu } from '@tiptap/react/menus'
+import type { EditorState } from '@tiptap/pm/state'
+import StarterKit from '@tiptap/starter-kit'
+import Placeholder from '@tiptap/extension-placeholder'
+import Highlight from '@tiptap/extension-highlight'
+import TaskList from '@tiptap/extension-task-list'
+import TaskItem from '@tiptap/extension-task-item'
+import { clsx } from 'clsx'
+import { SAFE_LINK_HINT, safeLinkUrl } from '../utils/safe-link-url'
+
+/**
+ * BlockEditor — a Notion-style block/rich-text editor for podoba, on Tiptap 3
+ * (ProseMirror). Opt-in subpath (`@podoba/react/editor`) so the base library stays
+ * free of the ProseMirror weight — importing this is what pulls Tiptap into a bundle.
+ * The Tiptap packages are OPTIONAL PEERS: install them alongside @podoba/react only
+ * if you import this subpath.
+ *
+ * Serialises to an **HTML string** (controlled `value` / `onChange(html)`), so it is a
+ * drop-in upgrade for any `set:html` / `dangerouslySetInnerHTML` renderer with no value
+ * migration. SECURITY: like any editor, it can emit arbitrary HTML — sanitise on the
+ * SERVER on write; the `value`/`onChange` contract here is presentation only.
+ *
+ * CONTROLLED-VALUE CONTRACT: echo `onChange`'s HTML back as `value` VERBATIM. The
+ * editor only re-seeds its document when `value` differs from what it last emitted, so
+ * a parent that normalises/sanitises before echoing would re-seed on every keystroke
+ * and send the caret back to the start. Sanitise on write to your store, not in render.
+ *
+ * Notion features: `/` slash menu (self-contained — insert paragraph/heading/list/
+ * to-do/quote/code/divider), an inline bubble toolbar (bold/italic/strike/highlight/
+ * code/link), and StarterKit's markdown input rules. Styling rides `@tailwindcss/
+ * typography` (`prose`), which @podoba/tailwind already registers, plus design tokens
+ * so it flips under `[data-theme="dark"]`.
+ *
+ * Prefer this over {@link ../components/rich-text-editor RichTextEditor} for
+ * document-shaped content; the dependency-free contentEditable one stays the right
+ * pick for a short caption/bio field where ProseMirror is not worth installing.
+ */
+export type BlockEditorProps = {
+	/** Controlled HTML value. Must be echoed back verbatim — see the contract above. */
+	value: string
+	/** Called with the editor's HTML on every change. */
+	onChange: (html: string) => void
+	/** Empty-document placeholder (also the `/`-hint). */
+	placeholder?: string
+	/** Optional visible label rendered above the editor; names the editable region. */
+	label?: ReactNode
+	/** Set false for a read-only render. */
+	editable?: boolean
+	/** Min height of the editable surface (default 200px). */
+	minHeight?: number | string
+	/** Class on the outer container. */
+	className?: string
+	/** Accessible name when there is no visible `label`. */
+	'aria-label'?: string
+}
+
+type SlashCommand = {
+	title: string
+	hint: string
+	keywords: string[]
+	run: (editor: Editor) => void
+}
+
+// The `/` block palette. Kept generic (no domain blocks) — a CMS/app composes richer
+// block types around this at the document level; this is the text-block vocabulary.
+const SLASH_COMMANDS: readonly SlashCommand[] = [
+	{ title: 'Text', hint: 'Plain paragraph', keywords: ['text', 'paragraph', 'body', 'p'], run: (e) => e.chain().focus().setParagraph().run() },
+	{ title: 'Heading 1', hint: 'Big section heading', keywords: ['h1', 'heading', 'title'], run: (e) => e.chain().focus().toggleHeading({ level: 1 }).run() },
+	{ title: 'Heading 2', hint: 'Medium heading', keywords: ['h2', 'subheading'], run: (e) => e.chain().focus().toggleHeading({ level: 2 }).run() },
+	{ title: 'Heading 3', hint: 'Small heading', keywords: ['h3'], run: (e) => e.chain().focus().toggleHeading({ level: 3 }).run() },
+	{ title: 'Bulleted list', hint: 'Unordered list', keywords: ['bullet', 'unordered', 'ul', 'list'], run: (e) => e.chain().focus().toggleBulletList().run() },
+	{ title: 'Numbered list', hint: 'Ordered list', keywords: ['numbered', 'ordered', 'ol', 'list'], run: (e) => e.chain().focus().toggleOrderedList().run() },
+	{ title: 'To-do list', hint: 'Checklist', keywords: ['todo', 'task', 'checkbox', 'check'], run: (e) => e.chain().focus().toggleTaskList().run() },
+	{ title: 'Quote', hint: 'Block quote', keywords: ['quote', 'blockquote', 'citation'], run: (e) => e.chain().focus().toggleBlockquote().run() },
+	{ title: 'Code', hint: 'Code block', keywords: ['code', 'snippet', 'pre'], run: (e) => e.chain().focus().toggleCodeBlock().run() },
+	{ title: 'Divider', hint: 'Horizontal rule', keywords: ['divider', 'rule', 'hr', 'separator'], run: (e) => e.chain().focus().setHorizontalRule().run() },
+]
+
+/** Open palette: the doc position of the trigger `/`, the query typed after it, and
+ * the highlighted row. Screen position is derived from `from` at paint time, never
+ * stored — so the menu can be re-placed on scroll/resize without stale coordinates. */
+type SlashState = { from: number; query: string; index: number }
+
+/** Filter the palette by title or keyword. Exported for tests. */
+export function filterCommands(query: string): SlashCommand[] {
+	const q = query.trim().toLowerCase()
+	if (!q) return [...SLASH_COMMANDS]
+	return SLASH_COMMANDS.filter((c) => c.title.toLowerCase().includes(q) || c.keywords.some((k) => k.includes(q)))
+}
+
+/** A `/` only opens the palette at the start of a block or after whitespace — never
+ * mid-word, so `and/or`, `https://…` and `/api/v2` stay plain text. Code blocks are
+ * excluded outright: a `/` there is always literal. Exported for tests. */
+export function canOpenSlash(state: EditorState, from: number): boolean {
+	if (from < 0 || from > state.doc.content.size) return false
+	const $from = state.doc.resolve(from)
+	if ($from.parent.type.spec.code) return false
+	if ($from.parentOffset === 0) return true
+	// textBetween returns '' for a non-text node (inline image, mention) — treat that
+	// as a boundary too; only a real word character blocks the trigger.
+	return /^\s*$/.test($from.parent.textBetween($from.parentOffset - 1, $from.parentOffset))
+}
+
+const btn =
+	'inline-flex h-8 min-w-8 items-center justify-center rounded-md px-2 text-small text-fg-muted transition-colors hover:bg-surface-muted hover:text-fg data-[active=true]:bg-surface-muted data-[active=true]:text-fg'
+
+/** Marks the bubble toolbar toggles. `active` keys read off the useEditorState
+ * snapshot below — Tiptap 3 does NOT re-render on transactions, so a plain
+ * `editor.isActive()` read during render would go stale on selection-only changes. */
+const MARK_TOOLS = [
+	{ key: 'bold', title: 'Bold', label: <b>B</b>, run: (e: Editor) => e.chain().focus().toggleBold().run() },
+	{ key: 'italic', title: 'Italic', label: <i>i</i>, run: (e: Editor) => e.chain().focus().toggleItalic().run() },
+	{ key: 'strike', title: 'Strikethrough', label: <s>S</s>, run: (e: Editor) => e.chain().focus().toggleStrike().run() },
+	{ key: 'highlight', title: 'Highlight', label: 'H', run: (e: Editor) => e.chain().focus().toggleHighlight().run() },
+	{ key: 'code', title: 'Inline code', label: '</>', run: (e: Editor) => e.chain().focus().toggleCode().run() },
+] as const
+
+const LinkIcon = () => (
+	<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+		<path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71" />
+		<path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71" />
+	</svg>
+)
+
+export function BlockEditor({ value, onChange, placeholder = "Write, or press '/' for blocks…", label, editable = true, minHeight = 200, className, ...aria }: BlockEditorProps) {
+	const onChangeRef = useRef(onChange)
+	onChangeRef.current = onChange
+	const lastEmitted = useRef<string>(value)
+	// The Placeholder extension is configured once at editor creation, so read the
+	// current prop through a ref — that keeps `placeholder` live without recreating
+	// the whole editor on every change.
+	const placeholderRef = useRef(placeholder)
+	placeholderRef.current = placeholder
+
+	// Slash state lives in a REF as well as in React state: ProseMirror handlers run
+	// synchronously inside the key event, long before React re-renders, so reading a
+	// render-assigned ref would lag a full render (two fast `/`s would double-open).
+	// `setSlash` writes both, so handlers always see what the last one wrote.
+	const slashRef = useRef<SlashState | null>(null)
+	const [slash, setSlashState] = useState<SlashState | null>(null)
+	const setSlash = useCallback((next: SlashState | null) => {
+		slashRef.current = next
+		setSlashState(next)
+	}, [])
+
+	const [linkOpen, setLinkOpen] = useState(false)
+	const linkOpenRef = useRef(false)
+	linkOpenRef.current = linkOpen
+	const [linkDraft, setLinkDraft] = useState('')
+	const [linkError, setLinkError] = useState<string | null>(null)
+	const linkInputRef = useRef<HTMLInputElement>(null)
+
+	const menuRef = useRef<HTMLDivElement>(null)
+	const [menuPos, setMenuPos] = useState<{ left: number; top: number } | null>(null)
+	// The palette portals to <body>, so mount first — a portal has no server render.
+	const [mounted, setMounted] = useState(false)
+	useEffect(() => setMounted(true), [])
+
+	const reactId = useId()
+	const labelId = `${reactId}-label`
+	const listboxId = `${reactId}-slash`
+	const optionId = (i: number) => `${listboxId}-option-${i}`
+
+	// `runSlash` closes over `editor`, which does not exist yet — hand the handlers a
+	// ref instead of relying on Tiptap re-applying options after every render.
+	const runSlashRef = useRef<(cmd: SlashCommand) => void>(() => {})
+
+	const ariaLabel = aria['aria-label']
+	const filtered = useMemo(() => filterCommands(slash?.query ?? ''), [slash?.query])
+	const activeOption = slash ? Math.min(slash.index, Math.max(filtered.length - 1, 0)) : 0
+	const paletteOpen = slash !== null && filtered.length > 0
+
+	const editor = useEditor({
+		editable,
+		// Explicit: Tiptap otherwise renders immediately and warns on every SSR pass.
+		// A published library cannot assume a client-only host.
+		immediatelyRender: false,
+		extensions: [
+			StarterKit.configure({ heading: { levels: [1, 2, 3] }, link: { openOnClick: false, autolink: true } }),
+			Highlight,
+			TaskList,
+			TaskItem.configure({ nested: true }),
+			Placeholder.configure({ placeholder: () => placeholderRef.current }),
+		],
+		content: value || '',
+		editorProps: {
+			attributes: {
+				class: clsx(
+					'prose prose-sm max-w-none px-4 py-3 text-fg outline-none',
+					'prose-headings:text-fg prose-p:text-fg prose-strong:text-fg prose-a:text-accent-strong',
+					'prose-code:text-fg prose-blockquote:text-fg-muted prose-li:text-fg',
+				),
+				style: `min-height:${typeof minHeight === 'number' ? `${minHeight}px` : minHeight}`,
+				// The contenteditable IS the textbox — naming the EditorContent wrapper
+				// instead would leave it nameless to assistive tech.
+				role: 'textbox',
+				'aria-multiline': 'true',
+				...(label ? { 'aria-labelledby': labelId } : {}),
+				...(ariaLabel ? { 'aria-label': ariaLabel } : {}),
+				'aria-expanded': paletteOpen ? 'true' : 'false',
+				...(paletteOpen ? { 'aria-controls': listboxId, 'aria-activedescendant': optionId(activeOption) } : {}),
+			},
+			// The `/` trigger fires on the actual character insert, so it covers every
+			// input method (IME, synthetic input, paste of a single char) with one path.
+			handleTextInput(view, from, _to, text) {
+				if (text !== '/' || slashRef.current) return false
+				if (!canOpenSlash(view.state, from)) return false
+				setSlash({ from, query: '', index: 0 })
+				return false // let the `/` type; onUpdate tracks it as the query prefix
+			},
+			handleKeyDown(_view, event) {
+				const s = slashRef.current
+				if (!s) return false
+				if (event.key === 'Escape') {
+					setSlash(null)
+					return true
+				}
+				const list = filterCommands(s.query)
+				// Nothing to pick — close and let the key through. Swallowing Enter and
+				// the arrows here is what used to strand the caret after `/api/v2`.
+				if (list.length === 0) {
+					setSlash(null)
+					return false
+				}
+				if (event.key === 'ArrowDown') {
+					setSlash({ ...s, index: (s.index + 1) % list.length })
+					return true
+				}
+				if (event.key === 'ArrowUp') {
+					setSlash({ ...s, index: (s.index - 1 + list.length) % list.length })
+					return true
+				}
+				if (event.key === 'Enter' || event.key === 'Tab') {
+					runSlashRef.current(list[Math.min(s.index, list.length - 1)])
+					return true
+				}
+				return false
+			},
+		},
+		onUpdate({ editor }) {
+			const html = editor.getHTML()
+			lastEmitted.current = html
+			onChangeRef.current(html)
+			// Track the `/query` the caret is typing after an open palette.
+			const s = slashRef.current
+			if (!s) return
+			const to = editor.state.selection.from
+			if (to < s.from) return setSlash(null)
+			const text = editor.state.doc.textBetween(s.from, to, '\n', '\n')
+			if (!text.startsWith('/')) return setSlash(null)
+			const query = text.slice(1)
+			// A block query is one word. Whitespace, or a query that matches nothing,
+			// means the user is writing prose — close rather than linger invisibly.
+			if (/\s/.test(query) || filterCommands(query).length === 0) return setSlash(null)
+			setSlash({ ...s, query, index: 0 })
+		},
+		// A pure caret move (click, arrow, select-all) fires no update — close the
+		// palette when the caret leaves the `/query` it belongs to.
+		onSelectionUpdate({ editor }) {
+			const s = slashRef.current
+			if (!s) return
+			const to = editor.state.selection.from
+			if (to < s.from || to > s.from + s.query.length + 1) setSlash(null)
+		},
+		onBlur() {
+			setSlash(null)
+		},
+	})
+
+	// Push EXTERNAL value changes into the editor (switching records, resets) without
+	// clobbering the caret on our own keystrokes.
+	useEffect(() => {
+		if (!editor) return
+		if (value !== lastEmitted.current && value !== editor.getHTML()) {
+			editor.commands.setContent(value || '', { emitUpdate: false })
+			lastEmitted.current = value
+		}
+	}, [value, editor])
+
+	// Tiptap's own re-render pass re-applies options with `editable` pinned to the
+	// live instance value, so the prop has to be pushed through this side channel.
+	useEffect(() => {
+		if (editor) editor.setEditable(editable)
+	}, [editable, editor])
+
+	const runSlash = useCallback(
+		(cmd: SlashCommand | undefined) => {
+			const s = slashRef.current
+			if (!editor || !s || !cmd) return
+			// Clamp: the doc can have shrunk under an open palette (an external
+			// setContent), which would make deleteRange throw on a stale position.
+			const size = editor.state.doc.content.size
+			const from = Math.min(Math.max(s.from, 0), size)
+			const to = Math.min(Math.max(editor.state.selection.from, from), size)
+			editor.chain().focus().deleteRange({ from, to }).run()
+			cmd.run(editor)
+			setSlash(null)
+		},
+		[editor, setSlash],
+	)
+	runSlashRef.current = runSlash
+
+	// Place the palette from the caret's CURRENT viewport coords, clamped into the
+	// viewport and flipped above the caret when it would overflow the bottom.
+	const placeMenu = useCallback(() => {
+		const s = slashRef.current
+		const el = menuRef.current
+		if (!editor || !s || !el) return
+		const size = editor.state.doc.content.size
+		if (s.from > size) return setSlash(null)
+		const caret = editor.view.coordsAtPos(s.from)
+		const rect = el.getBoundingClientRect()
+		const gap = 6
+		const edge = 8
+		let top = caret.bottom + gap
+		if (top + rect.height > window.innerHeight - edge) top = Math.max(edge, caret.top - gap - rect.height)
+		const left = Math.max(edge, Math.min(caret.left, window.innerWidth - rect.width - edge))
+		setMenuPos((prev) => (prev && prev.left === left && prev.top === top ? prev : { left, top }))
+	}, [editor, setSlash])
+
+	useLayoutEffect(() => {
+		if (slash) placeMenu()
+		else setMenuPos(null)
+	}, [slash, placeMenu])
+
+	// Fixed coordinates go stale the moment anything scrolls — including a scroll
+	// inside the editor itself, hence the capture-phase listener.
+	useEffect(() => {
+		if (!slash) return
+		const replace = () => placeMenu()
+		window.addEventListener('scroll', replace, true)
+		window.addEventListener('resize', replace)
+		return () => {
+			window.removeEventListener('scroll', replace, true)
+			window.removeEventListener('resize', replace)
+		}
+	}, [slash, placeMenu])
+
+	// Selection-driven mark states. Tiptap 3's useEditor deliberately does not
+	// re-render on transactions; this subscription is what keeps the toolbar honest.
+	const active = useEditorState({
+		editor,
+		selector: ({ editor }) =>
+			editor
+				? {
+						bold: editor.isActive('bold'),
+						italic: editor.isActive('italic'),
+						strike: editor.isActive('strike'),
+						highlight: editor.isActive('highlight'),
+						code: editor.isActive('code'),
+						link: editor.isActive('link'),
+						hasSelection: !editor.state.selection.empty,
+					}
+				: null,
+	})
+
+	const closeLink = useCallback(() => {
+		setLinkOpen(false)
+		setLinkError(null)
+		linkOpenRef.current = false
+	}, [])
+
+	// The link panel replaces the toolbar in place; a collapsed selection means the
+	// bubble menu is on its way out, so it must not strand an open panel.
+	useEffect(() => {
+		if (linkOpen && active && !active.hasSelection && !active.link) closeLink()
+	}, [linkOpen, active, closeLink])
+
+	useEffect(() => {
+		if (linkOpen) linkInputRef.current?.focus()
+	}, [linkOpen])
+
+	const openLink = () => {
+		if (!editor) return
+		setLinkDraft((editor.getAttributes('link').href as string | undefined) ?? '')
+		setLinkError(null)
+		linkOpenRef.current = true
+		setLinkOpen(true)
+	}
+
+	const applyLink = () => {
+		if (!editor) return
+		if (linkDraft.trim() === '') {
+			editor.chain().focus().extendMarkRange('link').unsetLink().run()
+			closeLink()
+			return
+		}
+		const url = safeLinkUrl(linkDraft)
+		if (!url) return setLinkError(SAFE_LINK_HINT)
+		editor.chain().focus().extendMarkRange('link').setLink({ href: url }).run()
+		closeLink()
+	}
+
+	return (
+		<div className={clsx('flex w-full flex-col gap-2', className)}>
+			{label ? (
+				<span id={labelId} className="text-small font-medium text-fg">
+					{label}
+				</span>
+			) : null}
+			<div className="relative rounded-lg border border-border bg-surface focus-within:border-brand-green">
+				{editor ? (
+					<BubbleMenu
+						editor={editor}
+						// Mirrors Tiptap's default (focus + non-empty selection), plus: stay up
+						// while the link panel owns focus, or typing a URL would dismiss itself.
+						shouldShow={({ editor, view, state, element }) => {
+							const inMenu = element.contains(document.activeElement)
+							if (!editor.isEditable || !(view.hasFocus() || inMenu)) return false
+							return linkOpenRef.current || !state.selection.empty
+						}}
+						className="flex flex-col gap-1 rounded-lg border border-border bg-surface-card p-1 shadow-md"
+					>
+						{linkOpen ? (
+							<>
+								<div className="flex items-center gap-1">
+									<input
+										ref={linkInputRef}
+										type="text"
+										value={linkDraft}
+										aria-label="Link URL"
+										aria-invalid={linkError ? true : undefined}
+										placeholder="https://, mailto:, /path"
+										className="h-8 w-56 rounded-md border border-border bg-surface px-2 text-small text-fg outline-none placeholder:text-fg-subtle focus:border-brand-green"
+										onChange={(e) => {
+											setLinkDraft(e.target.value)
+											setLinkError(null)
+										}}
+										onKeyDown={(e) => {
+											if (e.key === 'Enter') {
+												e.preventDefault()
+												applyLink()
+											}
+											if (e.key === 'Escape') {
+												e.preventDefault()
+												closeLink()
+												editor.chain().focus().run()
+											}
+										}}
+									/>
+									<button type="button" className={btn} onMouseDown={(e) => e.preventDefault()} onClick={applyLink} title="Apply link">
+										Apply
+									</button>
+									<button
+										type="button"
+										className={btn}
+										onMouseDown={(e) => e.preventDefault()}
+										onClick={() => {
+											closeLink()
+											editor.chain().focus().run()
+										}}
+										title="Cancel"
+									>
+										Cancel
+									</button>
+								</div>
+								{linkError ? <span className="px-1 pb-0.5 text-caption text-danger">{linkError}</span> : null}
+							</>
+						) : (
+							<div className="flex items-center gap-0.5">
+								{MARK_TOOLS.map((tool) => (
+									// preventDefault on mousedown keeps the editor selection while the button is clicked.
+									<button
+										key={tool.key}
+										type="button"
+										className={btn}
+										data-active={active?.[tool.key] ?? false}
+										aria-pressed={active?.[tool.key] ?? false}
+										onMouseDown={(e) => e.preventDefault()}
+										onClick={() => tool.run(editor)}
+										title={tool.title}
+									>
+										{tool.label}
+									</button>
+								))}
+								<button type="button" className={btn} data-active={active?.link ?? false} aria-pressed={active?.link ?? false} onMouseDown={(e) => e.preventDefault()} onClick={openLink} title="Link">
+									<LinkIcon />
+								</button>
+							</div>
+						)}
+					</BubbleMenu>
+				) : null}
+
+				<EditorContent editor={editor} />
+
+				{mounted && paletteOpen && slash
+					? createPortal(
+							<div
+								ref={menuRef}
+								id={listboxId}
+								role="listbox"
+								aria-label="Insert block"
+								className="fixed z-50 max-h-72 w-64 overflow-auto rounded-lg border border-border bg-surface-card p-1 shadow-md"
+								style={{ left: menuPos?.left ?? 0, top: menuPos?.top ?? 0, visibility: menuPos ? 'visible' : 'hidden' }}
+							>
+								{filtered.map((cmd, i) => (
+									// role=option must sit on a plain element — a <button> would override it.
+									// Focus stays in the editor; aria-activedescendant on the textbox drives AT.
+									<div
+										key={cmd.title}
+										id={optionId(i)}
+										role="option"
+										aria-selected={i === activeOption}
+										className={clsx('flex w-full cursor-pointer flex-col items-start rounded-md px-3 py-1.5 text-left', i === activeOption ? 'bg-surface-muted' : 'hover:bg-surface-muted')}
+										onMouseDown={(e) => e.preventDefault()}
+										onClick={() => runSlash(cmd)}
+									>
+										<span className="text-small text-fg">{cmd.title}</span>
+										<span className="text-caption text-fg-subtle">{cmd.hint}</span>
+									</div>
+								))}
+							</div>,
+							document.body,
+						)
+					: null}
+			</div>
+		</div>
+	)
+}

package/src/editor/index.ts

@@ -0,0 +1,3 @@
+// @podoba/react/editor — the opt-in Tiptap block editor. Kept behind a subpath so the
+// base @podoba/react bundle never pulls ProseMirror; importing here is the opt-in.
+export { BlockEditor, type BlockEditorProps } from './block-editor'

package/src/utils/safe-link-url.ts

@@ -0,0 +1,13 @@
+/** Allow-list for a link href: http(s), mailto, tel, or a relative/anchor path.
+ * The prefix allow-list inherently rejects `javascript:`/`data:`/`vbscript:`.
+ *
+ * Shared by every editor surface that takes a user-typed URL (RichTextEditor's
+ * toolbar, BlockEditor's link panel) so the allow-list can never drift between them.
+ * This is a UI guard, NOT the security boundary — sanitise HTML on the SERVER on write. */
+export function safeLinkUrl(raw: string): string | null {
+	const url = raw.trim()
+	return /^(https?:\/\/|mailto:|tel:|\/|#)/i.test(url) ? url : null
+}
+
+/** The message shown when {@link safeLinkUrl} rejects an input. */
+export const SAFE_LINK_HINT = 'Only http(s), mailto, tel, or relative (/, #) links are allowed.'

package/src/utils/uic.ts

@@ -58,12 +58,15 @@ const twMerge = extendTailwindMerge({
 						'caption',
 						'label',
 						'compact',
+						'small',
 						'callout',
 						'body',
 						'subtitle',
 						'title',
 						'headline',
 						'display',
+						'display-large',
+						'panel-heading',
 						// Heading ramp (size + line-height).
 						'heading1',
 						'heading2',
@@ -75,10 +78,15 @@ const twMerge = extendTailwindMerge({
 			],
 		},
 		theme: {
-			spacing: ['nav-x'],
+			spacing: ['nav-x', 'control-tall'],
 			// Custom card/panel radius key (rounded-panel) → dedupes against other
 			// rounded-* utilities. xl/2xl are stock keys tailwind-merge already knows.
 			radius: ['panel'],
+			// Custom blur/shadow keys, so `backdrop-blur-modal-backdrop` dedupes against
+			// a caller's `backdrop-blur-lg` (Dialog size="full" does exactly this) and
+			// `shadow-modal-surface` isn't misread as a shadow COLOR.
+			blur: ['modal-backdrop'],
+			shadow: ['modal-surface'],
 		},
 	},
 })