Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(docs): interactive Open Knowledge editor in the marketing hero (#2152)

sarah1c80a42d71b2
diff --git a/bun.lock b/bun.lock
index bca615639..81cf99a20 100644
--- a/bun.lock
+++ b/bun.lock
@@ -21,8 +21,21 @@
"name": "@inkeep/open-knowledge-docs",
"version": "0.0.1",
"dependencies": {
+ "@codemirror/commands": "^6.10.3",
+ "@codemirror/lang-markdown": "^6.5.0",
+ "@codemirror/language": "^6.12.3",
+ "@codemirror/state": "^6.6.0",
+ "@codemirror/view": "^6.41.0",
+ "@floating-ui/dom": "^1.7.6",
"@inkeep/cxkit-react": "^0.5.117",
+ "@inkeep/open-knowledge-core": "workspace:*",
"@radix-ui/react-popover": "^1.1.17",
+ "@tiptap/core": "^3.22.3",
+ "@tiptap/extension-drag-handle": "3.22.3",
+ "@tiptap/extensions": "^3.22.3",
+ "@tiptap/pm": "^3.22.3",
+ "@tiptap/react": "^3.22.3",
+ "@tiptap/suggestion": "^3.22.3",
"@types/mdx": "^2.0.13",
"clsx": "^2.1.1",
"fumadocs-core": "~16.1.0",
@@ -33,13 +46,13 @@
"next": "^16",
"next-themes": "^0.4.6",
"posthog-js": "^1.393.0",
+ "radix-ui": "^1.4.3",
"react": "^19",
"react-dom": "^19",
"tailwind-merge": "^3.6.0",
"zod": "^4.3.6",
},
"devDependencies": {
- "@inkeep/open-knowledge-core": "workspace:*",
"@tailwindcss/postcss": "^4",
"@types/node": "^24.0.7",
"@types/react": "^19",
diff --git a/docs/package.json b/docs/package.json
index 4b5c59b33..81528e722 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -16,8 +16,21 @@
"postinstall": "fumadocs-mdx"
},
"dependencies": {
+ "@codemirror/commands": "^6.10.3",
+ "@codemirror/lang-markdown": "^6.5.0",
+ "@codemirror/language": "^6.12.3",
+ "@codemirror/state": "^6.6.0",
+ "@codemirror/view": "^6.41.0",
+ "@floating-ui/dom": "^1.7.6",
"@inkeep/cxkit-react": "^0.5.117",
+ "@inkeep/open-knowledge-core": "workspace:*",
"@radix-ui/react-popover": "^1.1.17",
+ "@tiptap/core": "^3.22.3",
+ "@tiptap/extension-drag-handle": "3.22.3",
+ "@tiptap/extensions": "^3.22.3",
+ "@tiptap/pm": "^3.22.3",
+ "@tiptap/react": "^3.22.3",
+ "@tiptap/suggestion": "^3.22.3",
"@types/mdx": "^2.0.13",
"clsx": "^2.1.1",
"fumadocs-core": "~16.1.0",
@@ -28,13 +41,13 @@
"next": "^16",
"next-themes": "^0.4.6",
"posthog-js": "^1.393.0",
+ "radix-ui": "^1.4.3",
"react": "^19",
"react-dom": "^19",
"tailwind-merge": "^3.6.0",
"zod": "^4.3.6"
},
"devDependencies": {
- "@inkeep/open-knowledge-core": "workspace:*",
"@tailwindcss/postcss": "^4",
"@types/node": "^24.0.7",
"@types/react": "^19",
diff --git a/docs/src/app/(home)/sections/hero-preview.tsx b/docs/src/app/(home)/sections/hero-preview.tsx
index 380b02f9e..61b217880 100644
--- a/docs/src/app/(home)/sections/hero-preview.tsx
+++ b/docs/src/app/(home)/sections/hero-preview.tsx
@@ -1,11 +1,25 @@
'use client';
import { ArrowUp, Check, GitBranch, Globe, Loader2 } from 'lucide-react';
-import { useEffect, useId, useRef, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
import { ClaudeIcon } from '@/components/icons/claude';
import { CodexBrandIcon } from '@/components/icons/codex';
import { CursorIcon } from '@/components/icons/cursor';
+import {
+ OkEditorBody,
+ OkEditorModeToggle,
+ OkEditorProvider,
+ parseEditorMarkdown,
+ useEditorDocStats,
+ useOkEditor,
+} from '@/components/ok-editor/ok-editor';
+import {
+ HERO_FRONTMATTER,
+ HERO_FRONTMATTER_YAML,
+ heroRevealMarkdown,
+} from '@/components/ok-editor/seed';
import { OkIcon } from '@/components/ok-icon';
+import { OkWordmark } from '@/components/ok-wordmark';
import { useIsInView } from '@/lib/use-is-in-view';
import { usePrefersReducedMotion } from '@/lib/use-prefers-reduced-motion';
import { cn } from '@/lib/utils';
@@ -22,6 +36,8 @@ const AGENT_META = {
export type HeroPreviewAgentId = keyof typeof AGENT_META;
+const AGENT_IDS = Object.keys(AGENT_META) as HeroPreviewAgentId[];
+
const PAUSED = false;
const USER_MESSAGE = 'Help me write up our launch week';
@@ -50,7 +66,14 @@ const SEGMENTS: ReadonlyArray<{ phase: Phase; ms: number }> = [
{ phase: 'hold', ms: 2200 },
{ phase: 'reset', ms: 500 },
];
-const CYCLE_MS = SEGMENTS.reduce((sum, s) => sum + s.ms, 0);
+const RUN_ONCE_MS = SEGMENTS.filter((s) => s.phase !== 'reset').reduce((sum, s) => sum + s.ms, 0);
+
+const FINAL_STATE: State = {
+ phase: 'hold',
+ userTypedLen: USER_MESSAGE.length,
+ agentTypedLen: AGENT_STATUS.length,
+ contentStep: 5,
+};
const FILL_THRESHOLDS_MS = [0, 450, 900, 1350] as const;
@@ -134,29 +157,23 @@ function computeStateForSegment(phase: Phase, local: number, localProgress: numb
}
}
-export function HeroPreview({
- agentId,
- active = true,
-}: {
- agentId: HeroPreviewAgentId;
- active?: boolean;
-}) {
- const { label, Icon, brandColor } = AGENT_META[agentId];
- const [state, setState] = useState<State>({
- phase: 'hold',
- userTypedLen: USER_MESSAGE.length,
- agentTypedLen: AGENT_STATUS.length,
- contentStep: 5,
- });
+export function HeroPreview({ activeAgentId }: { activeAgentId: HeroPreviewAgentId }) {
+ const activeAgent = AGENT_META[activeAgentId];
+ const [state, setState] = useState<State>(() => computeState(0));
+ const [animationDone, setAnimationDone] = useState(false);
const [containerRef, inView] = useIsInView<HTMLDivElement>('100px');
const prefersReducedMotion = usePrefersReducedMotion();
useEffect(() => {
if (PAUSED) return;
- if (prefersReducedMotion) return;
+ if (animationDone) return;
+ if (prefersReducedMotion) {
+ setState(FINAL_STATE);
+ setAnimationDone(true);
+ return;
+ }
if (!inView) return;
- if (!active) return;
let raf = 0;
let lastPhase: Phase | null = null;
let lastUserLen = -1;
@@ -164,7 +181,12 @@ export function HeroPreview({
let lastStep = -1;
const start = performance.now();
const step = (now: number) => {
- const elapsed = (now - start) % CYCLE_MS;
+ const elapsed = now - start;
+ if (elapsed >= RUN_ONCE_MS) {
+ setState(FINAL_STATE);
+ setAnimationDone(true);
+ return;
+ }
const next = computeState(elapsed);
if (
next.phase !== lastPhase ||
@@ -182,7 +204,7 @@ export function HeroPreview({
};
raf = requestAnimationFrame(step);
return () => cancelAnimationFrame(raf);
- }, [inView, prefersReducedMotion, active]);
+ }, [inView, prefersReducedMotion, animationDone]);
const mobileScene: 'chat' | 'editor' =
state.phase === 'rest' ||
@@ -198,42 +220,53 @@ export function HeroPreview({
className="flex h-full w-full bg-[#fdfdfc] font-(family-name:--font-inter)"
>
{/* Two layout modes:
- - <md: slider — both panels sit side-by-side in a 200%-wide track that
- translates between scenes.
- - md+: side-by-side at a fixed natural size (1024×576), scaled via
- `transform: scale(calc(100cqw / 1024px))` to fit the card. Container
- queries (cqw) drive the scale, so the layout stays at its natural
- readable proportions and just shrinks/grows proportionally. */}
- <div className="relative h-full w-full overflow-hidden md:flex md:items-center md:justify-center md:[container-type:size] lg:block lg:[container-type:normal]">
+ - <lg: single-pane slider — both panels sit side-by-side in a 200%-wide
+ track that translates between scenes (one visible at a time, full size).
+ - lg+: both panels side-by-side, filling the card. */}
+ <div className="relative h-full w-full overflow-hidden">
<div
className={cn(
- 'flex h-full w-[200%] transition-transform duration-500 ease-out',
+ 'flex h-full w-[200%]',
+ prefersReducedMotion ? '' : 'transition-transform duration-500 ease-out',
mobileScene === 'editor' ? '-translate-x-1/2' : 'translate-x-0',
- 'md:h-[576px] md:w-[1024px] md:flex-none',
- 'md:grid md:grid-cols-[minmax(0,1fr)_minmax(0,1.55fr)] md:grid-rows-1',
- 'md:translate-x-0 md:transition-none',
- 'md:[transform-origin:center_center]',
- 'md:[transform:scale(min(1,calc(100cqw_/_1024px),calc(100cqh_/_576px)))]',
- 'lg:h-full lg:w-full lg:[transform:none]',
+ 'lg:grid lg:h-full lg:w-full lg:flex-none lg:grid-cols-[minmax(0,1fr)_minmax(0,1.55fr)] lg:grid-rows-1',
+ 'lg:translate-x-0 lg:transition-none',
)}
>
- <div className="flex h-full w-1/2 shrink-0 flex-col md:contents">
- <ChatPanel
- AgentIcon={Icon}
- brandColor={brandColor}
- agentLabel={label}
- phase={state.phase}
- userTypedLen={state.userTypedLen}
- agentTypedLen={state.agentTypedLen}
- />
+ {/* Chat cell — one chat panel per agent, stacked and cross-faded. All
+ share the single animation state; only the active agent's branding
+ is visible, so switching agents just cross-fades the chat. */}
+ <div className="relative h-full w-1/2 shrink-0 lg:w-auto">
+ {AGENT_IDS.map((id) => {
+ const meta = AGENT_META[id];
+ return (
+ <div
+ key={id}
+ aria-hidden={activeAgentId !== id}
+ className={cn(
+ 'absolute inset-0 transition-opacity duration-500 ease-out',
+ activeAgentId === id ? 'opacity-100' : 'pointer-events-none opacity-0',
+ )}
+ >
+ <ChatPanel
+ AgentIcon={meta.Icon}
+ brandColor={meta.brandColor}
+ agentLabel={meta.label}
+ phase={state.phase}
+ userTypedLen={state.userTypedLen}
+ agentTypedLen={state.agentTypedLen}
+ />
+ </div>
+ );
+ })}
</div>
- <div className="flex h-full w-1/2 shrink-0 flex-col md:block md:w-auto md:p-2">
+ <div className="flex h-full w-1/2 shrink-0 flex-col lg:block lg:w-auto lg:p-2">
<EditorPanel
- phase={state.phase}
contentStep={state.contentStep}
- AgentIcon={Icon}
- brandColor={brandColor}
- agentLabel={label}
+ AgentIcon={activeAgent.Icon}
+ brandColor={activeAgent.brandColor}
+ agentLabel={activeAgent.label}
+ animationDone={animationDone}
/>
</div>
</div>
@@ -312,7 +345,7 @@ function ChatPanel({
}, [phase]);
return (
- <div className="flex h-full min-h-0 flex-col border-b border-border md:border-b-0">
+ <div className="flex h-full min-h-0 flex-col border-b border-border lg:border-b-0">
{/* Chat sub-header — traffic lights + agent label, only on this side */}
<div className="flex shrink-0 items-center gap-6 px-4 py-3">
<TrafficLights />
@@ -335,7 +368,7 @@ function ChatPanel({
<span>{userTyped}</span>
{showUserCaret && (
<span
- className="ml-px inline-block h-[0.9em] w-[1.5px] translate-y-[1px] animate-pulse bg-slide-text/60 align-middle"
+ className="ml-px inline-block h-[0.9em] w-[1.5px] translate-y-[1px] motion-safe:animate-pulse bg-slide-text/60 align-middle"
aria-hidden="true"
/>
)}
@@ -360,7 +393,7 @@ function ChatPanel({
<span>{agentTyped}</span>
{showAgentCaret && (
<span
- className="ml-px inline-block h-[0.9em] w-[1.5px] translate-y-[1px] animate-pulse bg-slide-text/60 align-middle"
+ className="ml-px inline-block h-[0.9em] w-[1.5px] translate-y-[1px] motion-safe:animate-pulse bg-slide-text/60 align-middle"
aria-hidden="true"
/>
)}
@@ -461,209 +494,119 @@ function ToolCallCard({
* --------------------------------------------------------------------------- */
function EditorPanel({
- phase,
contentStep,
AgentIcon,
brandColor,
agentLabel,
+ animationDone,
}: {
- phase: Phase;
contentStep: number;
AgentIcon: typeof ClaudeIcon;
brandColor: string | undefined;
agentLabel: string;
+ animationDone: boolean;
}) {
- const agentConnected =
- phase === 'tool-appear' ||
- phase === 'tool-filling' ||
- phase === 'tool-done' ||
- phase === 'hold';
-
- const highlight: 'peak' | 'active' | 'none' =
- phase === 'tool-done'
- ? 'peak'
- : phase === 'tool-appear' || phase === 'tool-filling'
- ? 'active'
- : 'none';
-
- const showHeading = contentStep >= 1 && phase !== 'reset';
- const showCheck1 = contentStep >= 2 && phase !== 'reset';
- const showCheck2 = contentStep >= 3 && phase !== 'reset';
- const showCheck3 = contentStep >= 4 && phase !== 'reset';
- const showCallout = contentStep >= 5 && phase !== 'reset';
-
- const isFilled =
- phase === 'tool-done' || phase === 'hold' || (phase === 'reset' && contentStep === 5);
- const wordCount = isFilled ? 76 : 44;
- const charCount = isFilled ? 385 : 235;
- const tokenCount = Math.ceil(charCount / 4);
-
- const editorScrollRef = useRef<HTMLDivElement>(null);
- useEffect(() => {
- if (phase === 'reset') return;
- const el = editorScrollRef.current;
- if (!el) return;
- const scroll = () => {
- const top = phase === 'rest' || contentStep === 0 ? 0 : el.scrollHeight;
- el.scrollTo({ top, behavior: 'smooth' });
- };
- scroll();
- const t = window.setTimeout(scroll, 450);
- return () => window.clearTimeout(t);
- }, [phase, contentStep]);
-
return (
- <div className="flex h-full min-h-0 flex-col bg-slide-bg-elevated md:overflow-hidden md:rounded-lg md:shadow-[0_0px_48px_-16px_rgba(35,31,32,0.18)]">
- {/* Editor sub-header — row 1: URL bar; row 2: mode toggle + presence avatar */}
- <div className="relative flex shrink-0 flex-col gap-3 px-4 py-3 text-left">
- <div className="flex items-center gap-2 rounded-md bg-slide-text/[0.04] px-3 py-1.5 text-[11.5px] text-slide-muted">
- <Globe className="size-3.5 shrink-0" aria-hidden="true" />
- <span className="truncate">https://openknowledge.ai/{DOC_PATH}</span>
- </div>
- <div className="grid grid-cols-[1fr_auto_1fr] items-center gap-3">
- <span className="flex items-center gap-1.5 truncate text-[11px] text-slide-muted">
- <OkIcon className="size-[18px] shrink-0" aria-hidden="true" />
- <span className="hidden sm:inline">OpenKnowledge</span>
- </span>
- <div className="justify-self-center">
- <ModeTogglePreview />
+ <OkEditorProvider
+ initialMarkdown={heroRevealMarkdown(contentStep)}
+ frontmatter={HERO_FRONTMATTER_YAML}
+ >
+ <div className="flex h-full min-h-0 flex-col bg-slide-bg-elevated lg:overflow-hidden lg:rounded-lg lg:shadow-[0_0px_48px_-16px_rgba(35,31,32,0.18)]">
+ {/* Editor sub-header — row 1: URL bar; row 2: mode toggle + presence avatar */}
+ <div className="relative flex shrink-0 flex-col gap-3 px-4 py-3 text-left">
+ <div className="flex items-center gap-2 rounded-md bg-slide-text/[0.04] px-3 py-1.5 text-[11.5px] text-slide-muted">
+ <Globe className="size-3.5 shrink-0 opacity-50" aria-hidden="true" />
+ <span className="truncate">https://openknowledge.ai/{DOC_PATH}</span>
</div>
- <div
- className="flex justify-self-end transition-opacity duration-300"
- style={{ opacity: agentConnected ? 1 : 0 }}
- aria-hidden={!agentConnected}
- >
- <div
- className="flex size-6 items-center justify-center rounded-full"
- style={{
- backgroundColor: brandColor
- ? `color-mix(in srgb, ${brandColor} 18%, transparent)`
- : undefined,
- }}
- title={`${agentLabel} is editing`}
- >
- <AgentIcon className="size-3.5" aria-hidden="true" style={{ color: brandColor }} />
+ <div className="grid grid-cols-[1fr_auto_1fr] items-center gap-3">
+ <span className="flex items-center gap-1.5 truncate text-[11px] text-slide-muted">
+ {/* Icon-only on small screens; the full wordmark lockup on large. */}
+ <OkIcon className="size-[24px] shrink-0 lg:hidden" aria-hidden="true" />
+ <OkWordmark
+ aria-label="OpenKnowledge"
+ className="hidden h-[24px] w-auto shrink-0 lg:block"
+ />
+ </span>
+ <div className="justify-self-center">
+ {animationDone ? <OkEditorModeToggle /> : <ModeTogglePreview />}
+ </div>
+ <div className="flex justify-self-end">
+ <div
+ className="flex size-6 items-center justify-center rounded-full"
+ style={{
+ backgroundColor: brandColor
+ ? `color-mix(in srgb, ${brandColor} 18%, transparent)`
+ : undefined,
+ }}
+ title={`${agentLabel} is editing`}
+ >
+ <AgentIcon className="size-3.5" aria-hidden="true" style={{ color: brandColor }} />
+ </div>
</div>
</div>
+ {/* Fade beneath the header so document content scrolls in softly. */}
+ <div
+ aria-hidden="true"
+ className="pointer-events-none absolute inset-x-0 top-full z-10 h-3 bg-linear-to-b from-slide-bg-elevated to-transparent"
+ />
</div>
- {/* Fade beneath the header so document content scrolls in softly. */}
+
<div
- aria-hidden="true"
- className="pointer-events-none absolute inset-x-0 top-full z-10 h-3 bg-linear-to-b from-slide-bg-elevated to-transparent"
- />
- </div>
+ data-revealing={animationDone ? undefined : 'true'}
+ className="flex min-h-0 flex-1 flex-col gap-5 overflow-y-auto px-6 pt-1 pb-4 text-left subtle-scrollbar"
+ >
+ <FrontmatterPanel />
- <div
- ref={editorScrollRef}
- className="flex min-h-0 flex-1 flex-col gap-5 overflow-y-hidden px-6 pt-1 pb-4 text-left"
- >
- <div className="flex flex-col gap-2.5 text-1sm">
- <PropertyRow label="title" value="Launch week recap" />
- <PropertyRow
- label="tags"
- value={
- <span className="inline-flex flex-wrap gap-1.5">
- {['#launch', '#retro', '#v2'].map((t) => (
- <span
- key={t}
- className="rounded-full bg-slide-accent/10 px-2 py-[2px] text-xs font-medium text-slide-accent"
- >
- {t}
- </span>
- ))}
- </span>
- }
- />
+ <OkEditorBody />
+ <HeroEditorReveal step={contentStep} live={animationDone} />
</div>
- <h4 className="text-lg font-semibold text-slide-text">Launch week recap</h4>
-
- <p className="text-sm leading-relaxed text-slide-muted">
- v2.0 went public on June 3 — the end of a quiet QA window and the start of launch week.
- </p>
-
- <p className="text-sm leading-relaxed text-slide-muted">
- 47 PRs merged across the cycle. Activity stayed close to zero through QA, then spiked on
- launch day as the announcement went live.
- </p>
-
- {/* The section the agent writes */}
- <div className="flex flex-col gap-2">
- <RevealRow visible={showHeading}>
- <h5
- className={cn(
- 'text-sm font-semibold text-slide-text rounded transition-colors duration-500',
- highlight === 'peak' && 'bg-primary/15 px-1 -mx-1',
- highlight === 'active' && 'bg-primary/10 px-1 -mx-1',
- )}
- >
- Highlights
- </h5>
- </RevealRow>
-
- <ul className="flex flex-col gap-2 text-sm leading-relaxed text-slide-text mb-3">
- <RevealRow visible={showCheck1}>
- <TaskItem highlight={highlight}>Shipped v2.0 to public on Jun 3</TaskItem>
- </RevealRow>
- <RevealRow visible={showCheck2}>
- <TaskItem highlight={highlight}>1.4k new signups in the first 24 hours</TaskItem>
- </RevealRow>
- <RevealRow visible={showCheck3}>
- <TaskItem highlight={highlight}>Hit #1 on Product Hunt and front of HN</TaskItem>
- </RevealRow>
- </ul>
-
- <RevealRow visible={showCallout} maxHeight="340px">
- <DailyActivityChart visible={showCallout} />
- </RevealRow>
- </div>
- </div>
-
- {/* Word-count footer — pinned below the scrolling document body */}
- <div className="relative flex shrink-0 items-center justify-between bg-slide-bg-elevated px-6 py-2 font-mono text-[11px] text-slide-muted tabular-nums">
- {/* Fade above the footer so document content dissolves into it. */}
- <div
- aria-hidden="true"
- className="pointer-events-none absolute inset-x-0 bottom-full h-3 bg-linear-to-t from-slide-bg-elevated to-transparent"
- />
- <span className="flex items-center gap-1">
- <GitBranch size={11} /> main
- </span>
- {/* Invisible placeholder pins width; visible text swaps on isFilled */}
- <span className="relative inline-grid">
- <span className="invisible col-start-1 row-start-1" aria-hidden="true">
- 76 words · 385 chars · ~97 tokens
+ {/* Word-count footer — pinned below the scrolling document body */}
+ <div className="relative flex shrink-0 items-center justify-between bg-slide-bg-elevated px-6 py-2 font-mono text-[11px] text-slide-muted tabular-nums">
+ {/* Fade above the footer so document content dissolves into it. */}
+ <div
+ aria-hidden="true"
+ className="pointer-events-none absolute inset-x-0 bottom-full h-3 bg-linear-to-t from-slide-bg-elevated to-transparent"
+ />
+ <span className="flex items-center gap-1">
+ <GitBranch size={11} /> main
</span>
- <span className="col-start-1 row-start-1">
- {wordCount} words · {charCount} chars · ~{tokenCount} tokens
+ {/* Invisible placeholder pins a min width; live stats overlay it. */}
+ <span className="relative inline-grid">
+ <span className="invisible col-start-1 row-start-1" aria-hidden="true">
+ 76 words · 385 chars · ~97 tokens
+ </span>
+ <HeroEditorStats />
</span>
- </span>
+ </div>
</div>
- </div>
+ </OkEditorProvider>
);
}
-function RevealRow({
- visible,
- children,
- maxHeight = '160px',
-}: {
- visible: boolean;
- children: React.ReactNode;
- maxHeight?: string;
-}) {
+function HeroEditorReveal({ step, live }: { step: number; live: boolean }) {
+ const { editor } = useOkEditor();
+ const appliedStep = useRef(step);
+ useEffect(() => {
+ if (!editor) return;
+ if (appliedStep.current !== step) {
+ appliedStep.current = step;
+ const json = parseEditorMarkdown(heroRevealMarkdown(step));
+ queueMicrotask(() => {
+ if (!editor.isDestroyed) editor.commands.setContent(json);
+ });
+ }
+ editor.setEditable(live);
+ }, [editor, step, live]);
+ return null;
+}
+
+function HeroEditorStats() {
+ const { words, chars, tokens } = useEditorDocStats();
return (
- <div
- className="overflow-hidden transition-[opacity,max-height,transform] duration-400 ease-out"
- style={{
- opacity: visible ? 1 : 0,
- maxHeight: visible ? maxHeight : '0px',
- transform: visible ? 'translateY(0)' : 'translateY(4px)',
- }}
- aria-hidden={!visible}
- >
- {children}
- </div>
+ <span className="col-start-1 row-start-1">
+ {words} words · {chars} chars · ~{tokens} tokens
+ </span>
);
}
@@ -676,143 +619,28 @@ function PropertyRow({ label, value }: { label: string; value: React.ReactNode }
);
}
-function TaskItem({
- children,
- highlight,
-}: {
- children: React.ReactNode;
- highlight: 'peak' | 'active' | 'none';
-}) {
+function FrontmatterPanel() {
+ const { mode } = useOkEditor();
+ if (mode === 'source') return null;
return (
- <li className="flex items-start gap-2">
- <span
- aria-hidden="true"
- className="mt-[0.3em] size-4 shrink-0 rounded-[3px] border-[1.5px] border-border bg-transparent"
+ <div className="flex flex-col gap-2.5 pl-6 text-1sm">
+ <PropertyRow label="title" value={HERO_FRONTMATTER.title} />
+ <PropertyRow
+ label="tags"
+ value={
+ <span className="inline-flex flex-wrap gap-1.5">
+ {HERO_FRONTMATTER.tags.map((t) => (
+ <span
+ key={t}
+ className="rounded-full bg-slide-accent/10 px-2 py-[2px] text-xs font-medium text-slide-accent"
+ >
+ #{t}
+ </span>
+ ))}
+ </span>
+ }
/>
- <span
- className={cn(
- 'flex-1 rounded transition-colors duration-500',
- highlight === 'peak' && 'bg-primary/15 px-1 -mx-1',
- highlight === 'active' && 'bg-primary/10 px-1 -mx-1',
- )}
- >
- {children}
- </span>
- </li>
- );
-}
-
-function DailyActivityChart({ visible }: { visible: boolean }) {
- const data = [
- 11, 4, 1, 0.5, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2, 0.5, 0, 0, 0, 0, 1, 1.2, 1, 24, 8, 1, 0.2, 0,
- 0.5, 0,
- ];
- const max = 24;
- const yTicks = [0, 6, 12, 18, 24];
- const xLabels: ReadonlyArray<readonly [number, string]> = [
- [0, 'May 10'],
- [15, 'May 25'],
- [30, 'Jun 9'],
- ];
-
- const W = 480;
- const H = 150;
- const padL = 22;
- const padR = 6;
- const padT = 6;
- const padB = 18;
- const innerW = W - padL - padR;
- const innerH = H - padT - padB;
- const xAt = (i: number) => padL + (i / (data.length - 1)) * innerW;
- const yAt = (v: number) => padT + innerH - (v / max) * innerH;
- const baseline = yAt(0);
-
- const pts = data.map((v, i) => ({ x: xAt(i), y: yAt(v) }));
- let linePath = `M ${pts[0].x.toFixed(2)} ${pts[0].y.toFixed(2)}`;
- for (let i = 0; i < pts.length - 1; i++) {
- const p0 = pts[i - 1] ?? pts[i];
- const p1 = pts[i];
- const p2 = pts[i + 1];
- const p3 = pts[i + 2] ?? p2;
- const c1x = p1.x + (p2.x - p0.x) / 6;
- const c2x = p2.x - (p3.x - p1.x) / 6;
- const c1y = Math.min(baseline, p1.y + (p2.y - p0.y) / 6);
- const c2y = Math.min(baseline, p2.y - (p3.y - p1.y) / 6);
- linePath += ` C ${c1x.toFixed(2)} ${c1y.toFixed(2)}, ${c2x.toFixed(2)} ${c2y.toFixed(2)}, ${p2.x.toFixed(2)} ${p2.y.toFixed(2)}`;
- }
- const areaPath = `${linePath} L ${pts[pts.length - 1].x.toFixed(2)} ${baseline.toFixed(2)} L ${pts[0].x.toFixed(2)} ${baseline.toFixed(2)} Z`;
-
- const gradientId = useId();
-
- return (
- <figure className="flex flex-col gap-3.5 rounded-xl bg-slide-bg p-4">
- <figcaption className="text-[12.5px] font-medium text-slide-text/80">
- PRs merged per day · last 30 days
- </figcaption>
- <div
- className="overflow-hidden transition-[clip-path] duration-1200 ease-out"
- style={{ clipPath: visible ? 'inset(0 0 0 0)' : 'inset(0 100% 0 0)' }}
- >
- <svg
- viewBox={`0 0 ${W} ${H}`}
- preserveAspectRatio="none"
- className="block h-auto w-full"
- aria-label="Daily PRs merged, May 10 to June 9, peaking at 24 on June 3"
- >
- <defs>
- <linearGradient id={gradientId} x1="0" y1="0" x2="0" y2="1">
- <stop offset="0%" stopColor="var(--slide-accent)" stopOpacity={0.24} />
- <stop offset="100%" stopColor="var(--slide-accent)" stopOpacity={0.02} />
- </linearGradient>
- </defs>
- {yTicks.map((t) => (
- <line
- key={t}
- x1={padL}
- x2={W - padR}
- y1={yAt(t)}
- y2={yAt(t)}
- className="stroke-slide-text/4"
- strokeWidth={1}
- />
- ))}
- {yTicks.map((t) => (
- <text
- key={t}
- x={padL - 4}
- y={yAt(t)}
- textAnchor="end"
- dominantBaseline="middle"
- className="fill-slide-muted"
- style={{ fontSize: 8 }}
- >
- {t}
- </text>
- ))}
- {xLabels.map(([i, label]) => (
- <text
- key={label}
- x={xAt(i)}
- y={H - 4}
- textAnchor="middle"
- className="fill-slide-muted"
- style={{ fontSize: 8 }}
- >
- {label}
- </text>
- ))}
- <path d={areaPath} fill={`url(#${gradientId})`} />
- <path
- d={linePath}
- fill="none"
- stroke="var(--slide-accent)"
- strokeWidth={1.4}
- strokeLinejoin="round"
- strokeLinecap="round"
- />
- </svg>
- </div>
- </figure>
+ </div>
);
}
diff --git a/docs/src/app/(home)/sections/hero.tsx b/docs/src/app/(home)/sections/hero.tsx
index b0623d086..b4a4358b9 100644
--- a/docs/src/app/(home)/sections/hero.tsx
+++ b/docs/src/app/(home)/sections/hero.tsx
@@ -109,25 +109,24 @@ export function Hero() {
className="object-cover"
/>
<div
- className="relative z-10 aspect-3/4 w-full overflow-hidden rounded-[28px] border border-white/20 p-3 backdrop-blur-[20px] sm:aspect-square sm:p-4 md:aspect-video md:p-5"
+ className="relative z-10 flex h-[620px] w-full flex-col overflow-hidden rounded-[28px] border border-white/20 p-3 backdrop-blur-[20px] sm:p-4 lg:aspect-video lg:h-auto lg:p-5"
style={{
backgroundColor: 'rgba(255, 254, 254, 0.18)',
boxShadow: '6px 6px 24px rgba(153, 173, 205, 0.2)',
}}
>
- <div className="relative h-full w-full overflow-hidden rounded-xl">
- {AGENTS.map(({ id }) => (
- <div
- key={id}
- aria-hidden={activeId !== id}
- className={cn(
- 'absolute inset-0 transition-opacity duration-500 ease-out',
- activeId === id ? 'opacity-100' : 'opacity-0',
- )}
- >
- <HeroPreview agentId={id} active={activeId === id} />
- </div>
- ))}
+ {/* `flex-1 min-h-0` fills the card and hands a definite pixel height
+ down the editor's `h-full` chain — more robust than a percentage
+ chain (Safari in particular mishandles `height:100%` descendants of
+ some sized boxes). Single-pane (<lg) uses a fixed height so it stays
+ a consistent size rather than lurching as the container width snaps;
+ the lg two-pane reverts to `aspect-video` so the wide layout grows
+ taller with the screen instead of going wide-and-short. */}
+ <div className="relative min-h-0 w-full flex-1 overflow-hidden rounded-xl">
+ {/* One shared preview: the editor + intro animation are a single
+ instance, so switching agents only cross-fades the chat panel —
+ the intro never replays and editor edits persist. */}
+ <HeroPreview activeAgentId={activeId} />
</div>
</div>
</div>
diff --git a/docs/src/app/global.css b/docs/src/app/global.css
index b8ab08c6b..6f2d900e9 100644
--- a/docs/src/app/global.css
+++ b/docs/src/app/global.css
@@ -308,7 +308,7 @@
}
.ok-prosemirror h2 {
font-size: 1.25em;
- letter-spacing: -0.02em;
+ letter-spacing: -0.03em;
}
.ok-prosemirror h3 {
font-size: 1.1em;
@@ -359,7 +359,7 @@
}
.ok-prosemirror hr {
border: none;
- border-top: 1px solid var(--slide-border);
+ border-top: 1px solid var(--border);
margin: 1em 0;
}
.ok-prosemirror .ok-wikilink {
@@ -418,7 +418,7 @@
}
.ok-prosemirror th,
.ok-prosemirror td {
- border: 1px solid var(--slide-border);
+ border: 1px solid var(--border);
padding: 0.4em 0.6em;
text-align: left;
}
diff --git a/docs/src/components/ok-editor/block-type-selector.tsx b/docs/src/components/ok-editor/block-type-selector.tsx
new file mode 100644
index 000000000..42b55eb8a
--- /dev/null
+++ b/docs/src/components/ok-editor/block-type-selector.tsx
@@ -0,0 +1,140 @@
+'use client';
+
+import type { Editor } from '@tiptap/core';
+import { useEditorState } from '@tiptap/react';
+import {
+ ChevronDown,
+ Heading1,
+ Heading2,
+ Heading3,
+ List,
+ ListOrdered,
+ ListTodo,
+ Pilcrow,
+ Quote,
+ SquareCode,
+} from 'lucide-react';
+import {
+ DropdownMenu,
+ DropdownMenuContent,
+ DropdownMenuItem,
+ DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { cn } from '@/lib/utils';
+
+type BlockType = {
+ name: string;
+ label: string;
+ Icon: typeof Pilcrow;
+ isActive: (e: Editor) => boolean;
+ run: (e: Editor) => void;
+};
+
+const BLOCK_TYPES: BlockType[] = [
+ {
+ name: 'paragraph',
+ label: 'Text',
+ Icon: Pilcrow,
+ isActive: (e) => e.isActive('paragraph') && !e.isActive('list'),
+ run: (e) => e.chain().focus().setParagraph().run(),
+ },
+ {
+ name: 'heading1',
+ label: 'Heading 1',
+ Icon: Heading1,
+ isActive: (e) => e.isActive('heading', { level: 1 }),
+ run: (e) => e.chain().focus().toggleHeading({ level: 1 }).run(),
+ },
+ {
+ name: 'heading2',
+ label: 'Heading 2',
+ Icon: Heading2,
+ isActive: (e) => e.isActive('heading', { level: 2 }),
+ run: (e) => e.chain().focus().toggleHeading({ level: 2 }).run(),
+ },
+ {
+ name: 'heading3',
+ label: 'Heading 3',
+ Icon: Heading3,
+ isActive: (e) => e.isActive('heading', { level: 3 }),
+ run: (e) => e.chain().focus().toggleHeading({ level: 3 }).run(),
+ },
+ {
+ name: 'bulletList',
+ label: 'Bullet List',
+ Icon: List,
+ isActive: (e) => e.isActive('list', { ordered: false }),
+ run: (e) => e.chain().focus().toggleBulletList().run(),
+ },
+ {
+ name: 'orderedList',
+ label: 'Ordered List',
+ Icon: ListOrdered,
+ isActive: (e) => e.isActive('list', { ordered: true }),
+ run: (e) => e.chain().focus().toggleOrderedList().run(),
+ },
+ {
+ name: 'taskList',
+ label: 'Task List',
+ Icon: ListTodo,
+ isActive: (e) =>
+ e.isActive('listItem', { checked: true }) || e.isActive('listItem', { checked: false }),
+ run: (e) => e.chain().focus().toggleTaskList().run(),
+ },
+ {
+ name: 'blockquote',
+ label: 'Quote',
+ Icon: Quote,
+ isActive: (e) => e.isActive('blockquote'),
+ run: (e) => e.chain().focus().toggleBlockquote().run(),
+ },
+ {
+ name: 'codeBlock',
+ label: 'Code Block',
+ Icon: SquareCode,
+ isActive: (e) => e.isActive('codeBlock'),
+ run: (e) => e.chain().focus().toggleCodeBlock({ language: 'js' }).run(),
+ },
+];
+
+const DEFAULT_TYPE = BLOCK_TYPES[0] as BlockType;
+
+export function BlockTypeSelector({ editor }: { editor: Editor }) {
+ const { current, activeStates } = useEditorState({
+ editor,
+ selector: ({ editor: e }) => {
+ const activeStates = Object.fromEntries(BLOCK_TYPES.map((b) => [b.name, b.isActive(e)]));
+ const current = BLOCK_TYPES.find((b) => activeStates[b.name]) ?? DEFAULT_TYPE;
+ return { current, activeStates };
+ },
+ });
+ const CurrentIcon = current.Icon;
+
+ return (
+ <DropdownMenu>
+ <DropdownMenuTrigger asChild>
+ <button type="button" className="ok-bubble-blocktype" aria-label="Block type">
+ <CurrentIcon className="ok-bubble-icon" />
+ <span>{current.label}</span>
+ <ChevronDown className="size-3 opacity-50" />
+ </button>
+ </DropdownMenuTrigger>
+ <DropdownMenuContent align="start" sideOffset={8} className="w-44">
+ {BLOCK_TYPES.map((b) => {
+ const Icon = b.Icon;
+ return (
+ <DropdownMenuItem
+ key={b.name}
+ className={cn(activeStates[b.name] && 'bg-slide-text/[0.06] text-slide-text')}
+ onMouseDown={(e) => e.preventDefault()}
+ onSelect={() => b.run(editor)}
+ >
+ <Icon className="size-4" />
+ <span>{b.label}</span>
+ </DropdownMenuItem>
+ );
+ })}
+ </DropdownMenuContent>
+ </DropdownMenu>
+ );
+}
diff --git a/docs/src/components/ok-editor/bubble-menu.tsx b/docs/src/components/ok-editor/bubble-menu.tsx
new file mode 100644
index 000000000..2913be65b
--- /dev/null
+++ b/docs/src/components/ok-editor/bubble-menu.tsx
@@ -0,0 +1,169 @@
+'use client';
+
+import { autoUpdate, computePosition, flip, offset, shift } from '@floating-ui/dom';
+import { type Editor, posToDOMRect } from '@tiptap/core';
+import { useEditorState } from '@tiptap/react';
+import { BubbleMenu } from '@tiptap/react/menus';
+import { Bold, Code, Highlighter, Italic, Strikethrough, Underline } from 'lucide-react';
+import { useEffect, useRef } from 'react';
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip';
+import { cn } from '@/lib/utils';
+import { BlockTypeSelector } from './block-type-selector';
+
+const FORMAT_ACTIONS = [
+ {
+ name: 'Bold',
+ Icon: Bold,
+ run: (e: Editor) => e.chain().focus().toggleBold().run(),
+ mark: 'strong',
+ shortcut: '⌘B',
+ },
+ {
+ name: 'Italic',
+ Icon: Italic,
+ run: (e: Editor) => e.chain().focus().toggleItalic().run(),
+ mark: 'emphasis',
+ shortcut: '⌘I',
+ },
+ {
+ name: 'Underline',
+ Icon: Underline,
+ run: (e: Editor) => e.chain().focus().toggleUnderline().run(),
+ mark: 'underline',
+ shortcut: '⌘U',
+ },
+ {
+ name: 'Strikethrough',
+ Icon: Strikethrough,
+ run: (e: Editor) => e.chain().focus().toggleStrike().run(),
+ mark: 'strike',
+ shortcut: '⌘⇧S',
+ },
+ {
+ name: 'Code',
+ Icon: Code,
+ run: (e: Editor) => e.chain().focus().toggleCode().run(),
+ mark: 'code',
+ shortcut: '⌘E',
+ },
+ {
+ name: 'Highlight',
+ Icon: Highlighter,
+ run: (e: Editor) => e.chain().focus().toggleHighlight().run(),
+ mark: 'highlight',
+ shortcut: '⌘⇧H',
+ },
+] as const;
+
+function shouldShow({ editor }: { editor: Editor }): boolean {
+ if (!editor.isEditable) return false;
+ const { from, to, empty } = editor.state.selection;
+ if (empty) return false;
+ return Boolean(editor.state.doc.textBetween(from, to, ' ').trim());
+}
+
+export function OkBubbleMenu({ editor }: { editor: Editor }) {
+ const menuRef = useRef<HTMLDivElement>(null);
+ const stopAutoUpdate = useRef<(() => void) | null>(null);
+
+ useEffect(() => () => stopAutoUpdate.current?.(), []);
+
+ const active = useEditorState({
+ editor,
+ selector: ({ editor: e }): Record<string, boolean> =>
+ Object.fromEntries(FORMAT_ACTIONS.map((a) => [a.mark, e.isActive(a.mark)])),
+ });
+ const inCodeBlock = useEditorState({
+ editor,
+ selector: ({ editor: e }) => e.isActive('codeBlock'),
+ });
+
+ let contextElement: Element | undefined;
+ try {
+ contextElement = editor.view.dom;
+ } catch {
+ contextElement = undefined;
+ }
+
+ const anchor = {
+ getBoundingClientRect: () => {
+ try {
+ const { from, to } = editor.state.selection;
+ return posToDOMRect(editor.view, from, to);
+ } catch {
+ return new DOMRect();
+ }
+ },
+ contextElement,
+ };
+
+ const onShow = () => {
+ const popup = menuRef.current;
+ if (!popup) return;
+ stopAutoUpdate.current?.();
+ stopAutoUpdate.current = autoUpdate(anchor, popup, () => {
+ computePosition(anchor, popup, {
+ placement: 'top',
+ strategy: 'fixed',
+ middleware: [offset(8), flip(), shift({ padding: 8 })],
+ })
+ .then(({ x, y }) => {
+ if (!popup.isConnected) return;
+ popup.style.position = 'fixed';
+ popup.style.left = `${x}px`;
+ popup.style.top = `${y}px`;
+ })
+ .catch(() => {});
+ });
+ };
+
+ const onHide = () => {
+ stopAutoUpdate.current?.();
+ stopAutoUpdate.current = null;
+ };
+
+ return (
+ <BubbleMenu
+ ref={menuRef}
+ editor={editor}
+ shouldShow={shouldShow}
+ updateDelay={200}
+ appendTo={() => document.body}
+ options={{ onShow, onHide, strategy: 'fixed' }}
+ className="ok-bubble-menu"
+ >
+ <BlockTypeSelector editor={editor} />
+ {/* Marks don't apply in code blocks — show only the block-type dropdown
+ there (so the block can still be converted back to text). */}
+ {!inCodeBlock && <span className="ok-bubble-sep" aria-hidden="true" />}
+ {/* delayDuration 0 (the shadcn default) feels twitchy in a dense toolbar;
+ a short delay reads as intentional hover. */}
+ {!inCodeBlock && (
+ <TooltipProvider delayDuration={350}>
+ {FORMAT_ACTIONS.map(({ name, Icon, run, mark, shortcut }) => (
+ <Tooltip key={name}>
+ <TooltipTrigger asChild>
+ <button
+ type="button"
+ aria-label={name}
+ aria-pressed={active[mark]}
+ className={cn('ok-bubble-btn', active[mark] && 'is-active')}
+ onMouseDown={(e) => {
+ e.preventDefault();
+ run(editor);
+ }}
+ >
+ <Icon className="ok-bubble-icon" />
+ </button>
+ </TooltipTrigger>
+ <TooltipContent sideOffset={8} className="flex items-center gap-1.5">
+ {name}
+ <span className="text-[11px] text-slide-bg/60">{shortcut}</span>
+ </TooltipContent>
+ </Tooltip>
+ ))}
+ </TooltipProvider>
+ )}
+ </BubbleMenu>
+ );
+}
diff --git a/docs/src/components/ok-editor/drag-handle.tsx b/docs/src/components/ok-editor/drag-handle.tsx
new file mode 100644
index 000000000..dd451784c
--- /dev/null
+++ b/docs/src/components/ok-editor/drag-handle.tsx
@@ -0,0 +1,99 @@
+'use client';
+
+import { offset } from '@floating-ui/dom';
+import { type Editor, Extension } from '@tiptap/core';
+import { DragHandlePlugin, normalizeNestedOptions } from '@tiptap/extension-drag-handle';
+import type { Node as PmNode } from '@tiptap/pm/model';
+import { TextSelection } from '@tiptap/pm/state';
+
+const HANDLE_HEIGHT = 24;
+const MAX_SINGLE_LINE_HEIGHT = 44;
+const BODY_LINE_HEIGHT = 26;
+
+const PLUS_SVG = `<svg aria-hidden="true" xmlns="http://www.w3.org/2000/svg" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M5 12h14"/><path d="M12 5v14"/></svg>`;
+const GRIP_SVG = `<svg aria-hidden="true" xmlns="http://www.w3.org/2000/svg" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="9" cy="12" r="1"/><circle cx="9" cy="5" r="1"/><circle cx="9" cy="19" r="1"/><circle cx="15" cy="12" r="1"/><circle cx="15" cy="5" r="1"/><circle cx="15" cy="19" r="1"/></svg>`;
+
+function buildControls() {
+ const container = document.createElement('div');
+ container.className = 'ok-block-controls';
+
+ const addBtn = document.createElement('button');
+ addBtn.type = 'button';
+ addBtn.className = 'ok-block-btn';
+ addBtn.setAttribute('aria-label', 'Add block below');
+ addBtn.innerHTML = PLUS_SVG;
+ addBtn.addEventListener('mousedown', (e) => {
+ e.preventDefault();
+ e.stopPropagation();
+ });
+
+ const grip = document.createElement('button');
+ grip.type = 'button';
+ grip.className = 'ok-block-btn ok-block-grip';
+ grip.setAttribute('aria-label', 'Drag to move');
+ grip.setAttribute('tabindex', '-1');
+ grip.innerHTML = GRIP_SVG;
+
+ container.append(addBtn, grip);
+ return { container, addBtn, grip };
+}
+
+function addBlockBelow(editor: Editor, pos: number, node: PmNode) {
+ const { state, view } = editor;
+ const insertAt = pos + node.nodeSize;
+ if (insertAt > state.doc.content.size) return;
+ const paragraph = state.schema.nodes.paragraph?.create();
+ if (!paragraph) return;
+ const tr = state.tr.insert(insertAt, paragraph);
+ tr.setSelection(TextSelection.near(tr.doc.resolve(insertAt + 1))).scrollIntoView();
+ view.dispatch(tr);
+ view.focus();
+ editor.commands.insertContent('/');
+}
+
+export const BlockDragHandle = Extension.create({
+ name: 'okBlockDragHandle',
+
+ addProseMirrorPlugins() {
+ const editor = this.editor;
+ let curNode: PmNode | null = null;
+ let curPos = -1;
+
+ const { container, addBtn, grip } = buildControls();
+
+ addBtn.addEventListener('click', () => {
+ if (curNode && curPos >= 0) addBlockBelow(editor, curPos, curNode);
+ });
+ grip.addEventListener('click', () => {
+ if (curPos < 0) return;
+ try {
+ editor.chain().focus().setNodeSelection(curPos).run();
+ } catch {}
+ });
+
+ return [
+ DragHandlePlugin({
+ editor,
+ element: container,
+ nestedOptions: normalizeNestedOptions(false),
+ computePositionConfig: {
+ placement: 'left-start',
+ strategy: 'absolute',
+ middleware: [
+ offset(({ rects }) => {
+ const firstLineHeight =
+ rects.reference.height <= MAX_SINGLE_LINE_HEIGHT
+ ? rects.reference.height
+ : BODY_LINE_HEIGHT;
+ return { mainAxis: 6, crossAxis: (firstLineHeight - HANDLE_HEIGHT) / 2 };
+ }),
+ ],
+ },
+ onNodeChange: ({ node, pos }) => {
+ curNode = node;
+ curPos = pos;
+ },
+ }).plugin,
+ ];
+ },
+});
diff --git a/docs/src/components/ok-editor/mode-toggle.tsx b/docs/src/components/ok-editor/mode-toggle.tsx
new file mode 100644
index 000000000..b0f3c0525
--- /dev/null
+++ b/docs/src/components/ok-editor/mode-toggle.tsx
@@ -0,0 +1,54 @@
+'use client';
+
+export type EditorMode = 'visual' | 'source';
+
+export function ModeToggle({
+ mode,
+ onChange,
+}: {
+ mode: EditorMode;
+ onChange: (mode: EditorMode) => void;
+}) {
+ return (
+ <div className="ok-mode-toggle">
+ <button
+ type="button"
+ aria-pressed={mode === 'visual'}
+ aria-label="Visual editor"
+ data-active={mode === 'visual'}
+ className="ok-mode-toggle-btn"
+ onClick={() => onChange('visual')}
+ >
+ <TextboxIcon className="ok-mode-toggle-icon" />
+ Visual
+ </button>
+ <button
+ type="button"
+ aria-pressed={mode === 'source'}
+ aria-label="Markdown source editor"
+ data-active={mode === 'source'}
+ className="ok-mode-toggle-btn"
+ onClick={() => onChange('source')}
+ >
+ <MarkdownIcon className="ok-mode-toggle-icon" />
+ Markdown
+ </button>
+ </div>
+ );
+}
+
+function TextboxIcon({ className }: { className?: string }) {
+ return (
+ <svg className={className} viewBox="0 0 256 256" fill="currentColor" aria-hidden="true">
+ <path d="M112,40a8,8,0,0,0-8,8V64H24A16,16,0,0,0,8,80v96a16,16,0,0,0,16,16h80v16a8,8,0,0,0,16,0V48A8,8,0,0,0,112,40ZM24,176V80h80v96ZM248,80v96a16,16,0,0,1-16,16H144a8,8,0,0,1,0-16h88V80H144a8,8,0,0,1,0-16h88A16,16,0,0,1,248,80ZM88,112a8,8,0,0,1-8,8H72v24a8,8,0,0,1-16,0V120H48a8,8,0,0,1,0-16H80A8,8,0,0,1,88,112Z" />
+ </svg>
+ );
+}
+
+function MarkdownIcon({ className }: { className?: string }) {
+ return (
+ <svg className={className} viewBox="0 0 256 256" fill="currentColor" aria-hidden="true">
+ <path d="M232,48H24A16,16,0,0,0,8,64V192a16,16,0,0,0,16,16H232a16,16,0,0,0,16-16V64A16,16,0,0,0,232,48Zm0,144H24V64H232V192ZM128,104v48a8,8,0,0,1-16,0V123.31L93.66,141.66a8,8,0,0,1-11.32,0L64,123.31V152a8,8,0,0,1-16,0V104a8,8,0,0,1,13.66-5.66L88,124.69l26.34-26.35A8,8,0,0,1,128,104Zm77.66,18.34a8,8,0,0,1,0,11.32l-24,24a8,8,0,0,1-11.32,0l-24-24a8,8,0,0,1,11.32-11.32L168,132.69V104a8,8,0,0,1,16,0v28.69l10.34-10.35A8,8,0,0,1,205.66,122.34Z" />
+ </svg>
+ );
+}
diff --git a/docs/src/components/ok-editor/ok-editor.css b/docs/src/components/ok-editor/ok-editor.css
new file mode 100644
index 000000000..673a6e6a6
--- /dev/null
+++ b/docs/src/components/ok-editor/ok-editor.css
@@ -0,0 +1,538 @@
+/*
+ * Scoped editor typography — ported from the real editor's canonical
+ * ProseMirror rules in packages/app/src/globals.css and remapped onto the
+ * docs site's design tokens (--slide-*, --color-gray-*, --primary, --border).
+ * Everything is scoped under `.ok-editor-prose` (the class set on the
+ * ProseMirror root via editorProps) so it never leaks to docs prose.
+ *
+ * Drift note: the source of truth for the editor's look is the app stylesheet.
+ * If the app's `.ProseMirror` typography changes, re-sync the rules below.
+ */
+
+.ok-editor-prose {
+ outline: none;
+ font-size: 0.9375rem;
+ line-height: 1.7;
+ color: var(--slide-text);
+ /* Left margin room for the block drag handle (positioned left-start). */
+ padding-left: 1.5rem;
+}
+
+/* Anchor for the absolutely-positioned drag handle (appended next to the
+ ProseMirror root by DragHandlePlugin). */
+.ok-editor-visual {
+ position: relative;
+}
+
+/* Block hover controls — "+" (add block) and a drag grip in the left margin.
+ DragHandlePlugin toggles visibility/pointer-events; we only style looks. */
+.ok-block-controls {
+ display: flex;
+ align-items: center;
+ gap: 0.0625rem;
+}
+.ok-block-btn {
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ width: 1.125rem;
+ height: 1.5rem;
+ border-radius: 0.3rem;
+ color: color-mix(in oklab, var(--slide-muted) 65%, transparent);
+ cursor: pointer;
+ transition:
+ background-color 0.12s ease,
+ color 0.12s ease;
+}
+.ok-block-btn:hover {
+ background-color: color-mix(in oklab, var(--slide-text) 8%, transparent);
+ color: var(--slide-text);
+}
+.ok-block-grip {
+ cursor: grab;
+}
+.ok-block-controls[data-dragging="true"] .ok-block-grip {
+ cursor: grabbing;
+}
+
+.ok-editor-prose p {
+ margin-bottom: 0.5em;
+}
+
+/* Placeholder ("Type '/' for commands") — the Placeholder extension tags the
+ focused empty node with `is-empty` + a `data-placeholder` attr. */
+.ok-editor-prose p.is-empty::before {
+ content: attr(data-placeholder);
+ pointer-events: none;
+ float: left;
+ height: 0;
+ color: color-mix(in oklab, var(--slide-muted) 60%, transparent);
+}
+
+.ok-editor-prose > :first-child {
+ margin-top: 0;
+}
+
+/* Headings */
+.ok-editor-prose h1,
+.ok-editor-prose h2,
+.ok-editor-prose h3 {
+ font-weight: 600;
+ margin-top: 1em;
+ margin-bottom: 0.4em;
+ color: var(--slide-text);
+}
+
+.ok-editor-prose > h1:first-child,
+.ok-editor-prose > h2:first-child,
+.ok-editor-prose > h3:first-child {
+ margin-top: 0;
+}
+
+.ok-editor-prose h1 {
+ font-size: 1.5em;
+ letter-spacing: -0.04em;
+}
+.ok-editor-prose h2 {
+ font-size: 1.25em;
+ letter-spacing: -0.03em;
+}
+.ok-editor-prose h3 {
+ font-size: 1.1em;
+ letter-spacing: -0.02em;
+}
+
+/* Lists */
+.ok-editor-prose ul {
+ list-style-type: disc;
+ padding-left: 1.5em;
+ margin-bottom: 0.5em;
+}
+
+.ok-editor-prose ol {
+ list-style-type: decimal;
+ padding-left: 2.5em;
+ margin-bottom: 0.5em;
+}
+
+.ok-editor-prose li {
+ margin-bottom: 0.15em;
+}
+
+.ok-editor-prose li > p {
+ margin-bottom: 0.15em;
+}
+
+.ok-editor-prose ul ul {
+ list-style-type: circle;
+ margin-bottom: 0;
+}
+
+.ok-editor-prose ul ul ul {
+ list-style-type: square;
+}
+
+/* Task lists — the unified List extension emits <li data-type="taskItem"> */
+.ok-editor-prose ul:has(> li[data-type="taskItem"]) {
+ list-style: none;
+ padding-left: 0;
+}
+
+.ok-editor-prose li[data-type="taskItem"] {
+ display: flex;
+ align-items: flex-start;
+ gap: 0.5em;
+ margin-bottom: 0.5em;
+}
+
+.ok-editor-prose li[data-type="taskItem"] > label {
+ flex-shrink: 0;
+ margin-top: 0.3em;
+}
+
+.ok-editor-prose li[data-type="taskItem"] > label input[type="checkbox"] {
+ appearance: none;
+ width: 1rem;
+ height: 1rem;
+ border: 1px solid var(--color-gray-300);
+ border-radius: 3px;
+ background: transparent;
+ cursor: pointer;
+ display: grid;
+ place-content: center;
+ margin: 0;
+ transition:
+ background-color 150ms,
+ border-color 150ms;
+}
+
+.ok-editor-prose li[data-type="taskItem"] > label input[type="checkbox"]:checked {
+ background-color: var(--primary);
+ border-color: var(--primary);
+}
+
+.ok-editor-prose li[data-type="taskItem"] > label input[type="checkbox"]:checked::after {
+ content: "";
+ width: 0.55rem;
+ height: 0.55rem;
+ mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='white' stroke-width='3.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M20 6 9 17l-5-5'/%3E%3C/svg%3E");
+ mask-size: contain;
+ mask-repeat: no-repeat;
+ background-color: #fff;
+}
+
+.ok-editor-prose li[data-type="taskItem"] > label input[type="checkbox"]:focus-visible {
+ outline: 2px solid var(--primary);
+ outline-offset: 2px;
+}
+
+.ok-editor-prose li[data-type="taskItem"] > div {
+ flex: 1;
+}
+
+.ok-editor-prose li[data-type="taskItem"] > div p {
+ margin-bottom: 0;
+}
+
+.ok-editor-prose li[data-type="taskItem"][data-checked="true"] > div {
+ text-decoration: line-through;
+ color: var(--color-gray-400);
+}
+
+/* Blockquote */
+.ok-editor-prose blockquote {
+ border-left: 3px solid var(--color-gray-300);
+ padding-left: 1em;
+ margin-left: 0;
+ margin-bottom: 0.5em;
+ color: var(--color-gray-600);
+}
+
+/* Links */
+.ok-editor-prose a {
+ color: var(--slide-accent-strong);
+ text-decoration: underline;
+ text-underline-offset: 2px;
+}
+
+/* Highlight mark */
+.ok-editor-prose mark {
+ color: inherit;
+ padding: 0.05em 0.25em;
+ border-radius: 0.2em;
+ background: color-mix(in oklab, #f59e0b 22%, transparent);
+}
+
+/* Inline code */
+.ok-editor-prose code {
+ font-family: var(--font-mono);
+ font-size: 0.875em;
+ background: var(--color-gray-100);
+ padding: 0.1em 0.35em;
+ border-radius: 0.3em;
+}
+
+/* Code block fallback (until the preview NodeView lands) */
+.ok-editor-prose pre {
+ background: var(--color-gray-100);
+ padding: 0.75em 1em;
+ margin-bottom: 0.5em;
+ overflow-x: auto;
+ font-family: var(--font-mono);
+ font-size: 0.875em;
+ line-height: 1.6;
+ border-radius: 0.5rem;
+}
+
+.ok-editor-prose pre code {
+ background: none;
+ padding: 0;
+ font-size: inherit;
+}
+
+/* Keyboard focus ring for the editor's interactive buttons (a11y). */
+.ok-block-btn:focus-visible,
+.ok-slash-item:focus-visible,
+.ok-mode-toggle-btn:focus-visible,
+.ok-bubble-btn:focus-visible,
+.ok-bubble-blocktype:focus-visible {
+ outline: 2px solid var(--primary);
+ outline-offset: 1px;
+}
+
+/* --- Visual / Markdown segmented toggle (mirrors ModeTogglePreview) ------ */
+
+.ok-mode-toggle {
+ display: inline-flex;
+ flex-shrink: 0;
+ align-items: center;
+ gap: 0.125rem;
+ border-radius: 8px;
+ padding: 0.125rem;
+ background-color: color-mix(in srgb, var(--slide-text) 5%, transparent);
+}
+
+.ok-mode-toggle-btn {
+ display: flex;
+ height: 1.5rem;
+ align-items: center;
+ gap: 0.25rem;
+ border-radius: 6px;
+ padding: 0 0.375rem;
+ font-family: var(--font-mono);
+ font-size: 10px;
+ font-weight: 500;
+ text-transform: uppercase;
+ letter-spacing: 0.05em;
+ color: var(--slide-muted);
+ cursor: pointer;
+ transition:
+ color 150ms,
+ background-color 150ms;
+}
+
+.ok-mode-toggle-btn[data-active="true"] {
+ color: var(--slide-text);
+ background-color: var(--slide-bg-elevated);
+ box-shadow: 0 1px 2px rgba(0, 0, 0, 0.06);
+}
+
+.ok-mode-toggle-icon {
+ width: 0.75rem;
+ height: 0.75rem;
+ flex-shrink: 0;
+}
+
+/* --- Source pane -------------------------------------------------------- */
+
+.ok-source-host {
+ min-height: 0;
+}
+
+/* --- html-preview embeds (chart / stat cards) --------------------------- */
+
+.ok-editor-prose .ok-embed-preview {
+ position: relative;
+ margin: 1.5em 0 0.75em;
+}
+
+/* Hover-revealed delete button (top-right of the embed). */
+.ok-embed-delete {
+ position: absolute;
+ top: 0.5rem;
+ right: 0.5rem;
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ width: 1.5rem;
+ height: 1.5rem;
+ border-radius: 0.375rem;
+ color: var(--slide-muted);
+ background: color-mix(in srgb, var(--slide-bg-elevated) 82%, transparent);
+ box-shadow: 0 1px 2px rgba(15, 23, 42, 0.06);
+ cursor: pointer;
+ opacity: 0;
+ transition:
+ opacity 0.12s ease,
+ background-color 0.12s ease,
+ color 0.12s ease;
+}
+.ok-embed-preview:hover .ok-embed-delete,
+.ok-embed-delete:focus-visible {
+ opacity: 1;
+}
+.ok-embed-delete:hover {
+ color: #ef4444;
+ background: color-mix(in srgb, #ef4444 12%, var(--slide-bg-elevated));
+}
+
+.ok-embed-iframe {
+ display: block;
+ width: 100%;
+ /* Softer card border + a background nudged toward white — lighter, airier
+ embeds (applies to both the line chart and the bar chart). */
+ border: 1px solid color-mix(in srgb, var(--border) 55%, transparent);
+ border-radius: 0.625rem;
+ background: color-mix(in srgb, var(--slide-bg) 50%, var(--slide-bg-elevated));
+}
+
+.ok-editor-prose pre.ok-code-block {
+ /* same surface as the generic code-block fallback above */
+ background: var(--color-gray-100);
+ border-radius: 0.5rem;
+}
+
+/* --- Reveal entrance — the newly landed block fades + rises in. The unified
+ reveal appends one block per step, so the last child is the fresh one; only
+ it animates (rebuilt earlier blocks appear instantly, no whole-doc re-pulse).
+ Also gives a gentle fade when the user adds a block later.
+ prefers-reduced-motion users get no movement. --- */
+@media (prefers-reduced-motion: no-preference) {
+ .ok-editor-prose > *:last-child {
+ animation: ok-reveal-in 360ms ease-out both;
+ }
+}
+
+@keyframes ok-reveal-in {
+ from {
+ opacity: 0;
+ transform: translateY(4px);
+ }
+ to {
+ opacity: 1;
+ transform: none;
+ }
+}
+
+/* --- Slash-command menu (popup mounts on document.body, so global) ------- */
+
+.ok-slash-popup {
+ position: fixed;
+ z-index: 60;
+}
+
+.ok-slash-menu {
+ display: flex;
+ flex-direction: column;
+ gap: 1px;
+ width: 200px;
+ max-height: 280px;
+ overflow-y: auto;
+ padding: 0.25rem;
+ border-radius: 0.625rem;
+ background: var(--slide-bg-elevated);
+ border: 1px solid var(--border);
+ box-shadow:
+ 0 1px 2px rgba(15, 23, 42, 0.04),
+ 0 8px 24px -8px rgba(15, 23, 42, 0.18);
+ font-family: var(--font-inter, system-ui, sans-serif);
+ /* Subtle thin scrollbar — native CSS (no @apply: this standalone file isn't
+ connected to the docs Tailwind context, and `subtle-scrollbar` lives only
+ in the app's globals.css). Mirrors that class's intent. */
+ scrollbar-width: thin;
+ scrollbar-color: color-mix(in oklab, var(--slide-text) 18%, transparent) transparent;
+}
+
+.ok-slash-item {
+ display: flex;
+ align-items: center;
+ gap: 0.5rem;
+ width: 100%;
+ padding: 0.375rem 0.5rem;
+ border-radius: 0.375rem;
+ font-size: 0.8125rem;
+ text-align: left;
+ color: var(--slide-text);
+ cursor: pointer;
+}
+
+.ok-slash-item[data-active="true"] {
+ background: color-mix(in srgb, var(--slide-text) 6%, transparent);
+}
+
+.ok-slash-item-icon {
+ width: 0.875rem;
+ height: 0.875rem;
+ flex-shrink: 0;
+ color: var(--slide-muted);
+}
+
+/* Selection bubble menu (inline format toolbar). Positioned fixed via
+ floating-ui in bubble-menu.tsx; this styles only the appearance. */
+.ok-bubble-menu {
+ display: flex;
+ align-items: center;
+ gap: 0.125rem;
+ padding: 0.25rem;
+ border-radius: 0.625rem;
+ background: var(--slide-bg-elevated);
+ border: 1px solid var(--border);
+ box-shadow:
+ 0 1px 2px rgba(15, 23, 42, 0.04),
+ 0 8px 24px -8px rgba(15, 23, 42, 0.18);
+ z-index: 60;
+}
+
+.ok-bubble-btn {
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ width: 1.75rem;
+ height: 1.75rem;
+ border-radius: 0.375rem;
+ color: var(--slide-text);
+ cursor: pointer;
+ transition:
+ background-color 0.12s ease,
+ color 0.12s ease;
+}
+.ok-bubble-btn:hover {
+ background: color-mix(in srgb, var(--slide-text) 6%, transparent);
+}
+.ok-bubble-btn.is-active {
+ background: color-mix(in srgb, var(--slide-accent-strong) 12%, transparent);
+ color: var(--slide-accent-strong);
+}
+.ok-bubble-icon {
+ width: 0.9375rem;
+ height: 0.9375rem;
+}
+
+/* Block-type dropdown trigger (left of the format buttons) */
+.ok-bubble-blocktype {
+ display: inline-flex;
+ align-items: center;
+ gap: 0.25rem;
+ height: 1.75rem;
+ padding: 0 0.375rem;
+ border-radius: 0.375rem;
+ font-size: 0.8125rem;
+ font-weight: 500;
+ white-space: nowrap;
+ color: var(--slide-text);
+ cursor: pointer;
+ transition: background-color 0.12s ease;
+}
+.ok-bubble-blocktype:hover {
+ background: color-mix(in srgb, var(--slide-text) 6%, transparent);
+}
+.ok-bubble-sep {
+ width: 1px;
+ align-self: stretch;
+ margin: 0.25rem 0.0625rem;
+ background: var(--slide-border);
+}
+
+.ok-slash-empty {
+ width: 200px;
+ padding: 0.5rem 0.625rem;
+ border-radius: 0.625rem;
+ background: var(--slide-bg-elevated);
+ border: 1px solid var(--slide-border);
+ font-size: 0.8125rem;
+ color: var(--slide-muted);
+}
+
+/* Intro reveal — as each step writes content into the editor, the freshly-added
+ block eases in (the agent "writing" effect). `setContent` diffs the DOM, so a
+ CSS animation fires only when a node is first created and never replays on the
+ reused, unchanged nodes. We target exactly the revealed content — the
+ Highlights heading, each new task, and the chart — so the static intro text
+ (which mounts first) doesn't animate. `> :last-child` is avoided because the
+ editor keeps a trailing empty paragraph there. Scoped to `[data-revealing]`
+ (intro only) so live edits don't animate; motion-gated for reduced motion.
+ Kept last in the file so the base h2 / li / embed rules above retain ascending
+ specificity (these `[data-revealing] …` selectors are higher-specificity). */
+@media (prefers-reduced-motion: no-preference) {
+ [data-revealing] .ok-editor-prose h2,
+ [data-revealing] .ok-editor-prose li:last-child,
+ [data-revealing] .ok-editor-prose .ok-embed-preview {
+ animation: ok-block-reveal 420ms cubic-bezier(0.22, 1, 0.36, 1) both;
+ }
+}
+@keyframes ok-block-reveal {
+ from {
+ opacity: 0;
+ transform: translateY(7px);
+ }
+}
diff --git a/docs/src/components/ok-editor/ok-editor.tsx b/docs/src/components/ok-editor/ok-editor.tsx
new file mode 100644
index 000000000..8899a28d9
--- /dev/null
+++ b/docs/src/components/ok-editor/ok-editor.tsx
@@ -0,0 +1,175 @@
+'use client';
+
+import type { EditorView } from '@codemirror/view';
+import { MarkdownManager, sharedExtensions } from '@inkeep/open-knowledge-core';
+import type { Editor } from '@tiptap/core';
+import { Placeholder, UndoRedo } from '@tiptap/extensions';
+import { EditorContent, useEditor, useEditorState } from '@tiptap/react';
+import dynamic from 'next/dynamic';
+import {
+ createContext,
+ type ReactNode,
+ type RefObject,
+ use,
+ useEffect,
+ useRef,
+ useState,
+} from 'react';
+import { createPortal } from 'react-dom';
+import './ok-editor.css';
+import { OkBubbleMenu } from './bubble-menu';
+import { BlockDragHandle } from './drag-handle';
+import { type EditorMode, ModeToggle } from './mode-toggle';
+import { PreviewCodeBlock } from './preview-code-block';
+import { HERO_SEED_MARKDOWN } from './seed';
+import { SlashCommand } from './slash-command';
+
+const SourceEditor = dynamic(() => import('./source-editor').then((m) => m.SourceEditor), {
+ ssr: false,
+});
+
+const markdownManager = new MarkdownManager({ extensions: sharedExtensions });
+const extensions = [
+ ...sharedExtensions.map((ext) => (ext.name === 'codeBlock' ? PreviewCodeBlock : ext)),
+ UndoRedo,
+ SlashCommand,
+ BlockDragHandle,
+ Placeholder.configure({ placeholder: "Type '/' for commands", showOnlyCurrent: true }),
+];
+
+export function parseEditorMarkdown(markdown: string) {
+ return markdownManager.parse(markdown);
+}
+
+export interface EditorDocStats {
+ words: number;
+ chars: number;
+ tokens: number;
+}
+
+const EMPTY_STATS: EditorDocStats = { words: 0, chars: 0, tokens: 0 };
+
+function computeDocStats(editor: Editor): EditorDocStats {
+ let text = '';
+ let chars = 0;
+ editor.state.doc.descendants((node) => {
+ if (node.type.name === 'codeBlock') {
+ const meta = typeof node.attrs.meta === 'string' ? node.attrs.meta : '';
+ if (node.attrs.language === 'html' && /\bpreview\b/.test(meta)) return false;
+ }
+ if (node.isText) {
+ const s = node.text ?? '';
+ text += s;
+ chars += s.length;
+ return true;
+ }
+ if (node.type.isBlock && text.length > 0 && !text.endsWith('\n')) text += '\n';
+ return true;
+ });
+ const words = text.trim() ? (text.trim().match(/\S+/g)?.length ?? 0) : 0;
+ return { words, chars, tokens: Math.ceil(chars / 4) };
+}
+
+export function useEditorDocStats(): EditorDocStats {
+ const { editor } = useOkEditor();
+ return (
+ useEditorState({
+ editor,
+ selector: ({ editor }) => (editor ? computeDocStats(editor) : EMPTY_STATS),
+ }) ?? EMPTY_STATS
+ );
+}
+
+interface OkEditorContextValue {
+ editor: Editor | null;
+ mode: EditorMode;
+ switchMode: (mode: EditorMode) => void;
+ sourceDoc: string;
+ sourceViewRef: RefObject<EditorView | null>;
+}
+
+const OkEditorContext = createContext<OkEditorContextValue | null>(null);
+
+export function useOkEditor(): OkEditorContextValue {
+ const ctx = use(OkEditorContext);
+ if (!ctx) throw new Error('OkEditor components must be rendered inside <OkEditorProvider>');
+ return ctx;
+}
+
+export function OkEditorProvider({
+ children,
+ initialMarkdown,
+ frontmatter,
+}: {
+ children: ReactNode;
+ initialMarkdown?: string;
+ /** Optional YAML frontmatter block (`---\n…\n---`) revealed above the body in
+ * Markdown mode. The body editor stays frontmatter-free (the property panel is
+ * its display chrome); this only round-trips through the source view. */
+ frontmatter?: string;
+}) {
+ const [mode, setMode] = useState<EditorMode>('visual');
+ const [sourceDoc, setSourceDoc] = useState('');
+ const sourceViewRef = useRef<EditorView | null>(null);
+ const [initialContent] = useState(() =>
+ markdownManager.parse(initialMarkdown ?? HERO_SEED_MARKDOWN),
+ );
+
+ const editor = useEditor({
+ extensions,
+ content: initialContent,
+ editable: true,
+ immediatelyRender: false,
+ editorProps: {
+ attributes: { class: 'ok-editor-prose focus:outline-none', spellcheck: 'false' },
+ },
+ });
+
+ function switchMode(next: EditorMode) {
+ if (next === mode || !editor) return;
+ if (next === 'source') {
+ const body = markdownManager.serialize(editor.getJSON());
+ setSourceDoc(frontmatter ? `${frontmatter}\n\n${body}` : body);
+ } else {
+ const raw = sourceViewRef.current?.state.doc.toString() ?? sourceDoc;
+ const body = raw.replace(/^---\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n)*/, '');
+ editor.commands.setContent(markdownManager.parse(body));
+ }
+ setMode(next);
+ }
+
+ return (
+ <OkEditorContext value={{ editor, mode, switchMode, sourceDoc, sourceViewRef }}>
+ {children}
+ </OkEditorContext>
+ );
+}
+
+export function OkEditorModeToggle() {
+ const { mode, switchMode } = useOkEditor();
+ return <ModeToggle mode={mode} onChange={switchMode} />;
+}
+
+export function OkEditorBody() {
+ const { editor, mode, sourceDoc, sourceViewRef } = useOkEditor();
+
+ const visualHostRef = useRef<HTMLDivElement>(null);
+ const [visualHost, setVisualHost] = useState<HTMLElement | null>(null);
+ useEffect(() => {
+ setVisualHost(visualHostRef.current);
+ }, []);
+
+ return (
+ <>
+ <div ref={visualHostRef} className="ok-editor-visual" hidden={mode !== 'visual'} />
+ {visualHost &&
+ createPortal(
+ // biome-ignore lint/plugin/no-unportaled-editor-content: single non-pooled editor portalled into an exclusively-owned target — the rule's canonical shape; no Activity pool / editor cache in this marketing preview.
+ <EditorContent editor={editor} />,
+ visualHost,
+ )}
+ {editor && mode === 'visual' && <OkBubbleMenu editor={editor} />}
+ {mode === 'source' && <SourceEditor initialDoc={sourceDoc} viewRef={sourceViewRef} />}
+ </>
+ );
+}
diff --git a/docs/src/components/ok-editor/preview-code-block.tsx b/docs/src/components/ok-editor/preview-code-block.tsx
new file mode 100644
index 000000000..0c114fd9a
--- /dev/null
+++ b/docs/src/components/ok-editor/preview-code-block.tsx
@@ -0,0 +1,90 @@
+'use client';
+
+import { CodeBlockFidelity, PREVIEW_THEME_TOKENS } from '@inkeep/open-knowledge-core';
+import {
+ NodeViewContent,
+ type NodeViewProps,
+ NodeViewWrapper,
+ ReactNodeViewRenderer,
+} from '@tiptap/react';
+import { Trash2 } from 'lucide-react';
+
+const THEME_VARS = PREVIEW_THEME_TOKENS.map((t) => `${t.name}:${t.light}`).join(';');
+
+const CHART_PALETTE = [
+ '--chart-1:#93c5fd',
+ '--chart-2:#60a5fa',
+ '--chart-3:#3784ff',
+ '--chart-4:#2563eb',
+ '--chart-5:#1d4ed8',
+].join(';');
+
+function buildSrcDoc(html: string): string {
+ return `<!doctype html><html><head><meta charset="utf-8"><style>
+:root{${THEME_VARS};${CHART_PALETTE}}
+html,body{margin:0;height:100%;background:transparent;color:var(--foreground);font-family:system-ui,-apple-system,sans-serif}
+/* Embeds are static, sized-to-fit content — never show the iframe's OS
+ scrollbar (a sub-pixel overflow shouldn't paint a thick gutter). */
+html{scrollbar-width:none}
+html::-webkit-scrollbar{width:0;height:0;display:none}
+*{box-sizing:border-box}
+</style></head><body>${html}</body></html>`;
+}
+
+const DEFAULT_PREVIEW_HEIGHT = 230;
+
+function previewHeight(meta: string): number {
+ const m = /\bh=(\d+)\b/.exec(meta);
+ return m ? Number(m[1]) : DEFAULT_PREVIEW_HEIGHT;
+}
+
+function PreviewCodeBlockView({ node, deleteNode }: NodeViewProps) {
+ const language = typeof node.attrs.language === 'string' ? node.attrs.language : '';
+ const meta = typeof node.attrs.meta === 'string' ? node.attrs.meta : '';
+ const isPreview = language === 'html' && /\bpreview\b/.test(meta);
+
+ if (isPreview) {
+ return (
+ <NodeViewWrapper className="ok-embed-preview" contentEditable={false}>
+ <iframe
+ sandbox="allow-scripts"
+ srcDoc={buildSrcDoc(node.textContent)}
+ title="Embedded preview"
+ className="ok-embed-iframe"
+ style={{ height: `${previewHeight(meta)}px` }}
+ />
+ {/* The embed isn't editable, but it can be removed. Hover-revealed
+ delete button (top-right); mousedown-preventDefault keeps the editor
+ from grabbing a selection before the click deletes the node. */}
+ <button
+ type="button"
+ className="ok-embed-delete"
+ aria-label="Delete embed"
+ onMouseDown={(e) => e.preventDefault()}
+ onClick={() => deleteNode()}
+ >
+ <Trash2 className="size-3.5" />
+ </button>
+ {/* The code text stays in the document (round-trips to markdown) but is
+ hidden while the preview renders. */}
+ <pre hidden>
+ <NodeViewContent />
+ </pre>
+ </NodeViewWrapper>
+ );
+ }
+
+ return (
+ <NodeViewWrapper>
+ <pre className="ok-code-block">
+ <NodeViewContent />
+ </pre>
+ </NodeViewWrapper>
+ );
+}
+
+export const PreviewCodeBlock = CodeBlockFidelity.extend({
+ addNodeView() {
+ return ReactNodeViewRenderer(PreviewCodeBlockView);
+ },
+});
diff --git a/docs/src/components/ok-editor/seed.ts b/docs/src/components/ok-editor/seed.ts
new file mode 100644
index 000000000..8067d83b5
--- /dev/null
+++ b/docs/src/components/ok-editor/seed.ts
@@ -0,0 +1,64 @@
+const HERO_INTRO = `# Launch week recap
+
+v2.0 went public on June 3 — the end of a quiet QA window and the start of launch week.
+
+47 PRs merged across the cycle. Activity stayed close to zero through QA, then spiked on launch day as the announcement went live.`;
+
+const HERO_TASKS = [
+ '- [ ] Shipped v2.0 to public on Jun 3',
+ '- [ ] 1.4k new signups in the first 24 hours',
+ '- [ ] Hit #1 on Product Hunt and front of Hacker News',
+];
+
+export const HERO_FRONTMATTER = {
+ title: 'Launch week recap',
+ tags: ['launch', 'retro', 'v2'],
+} as const;
+
+export const HERO_FRONTMATTER_YAML = [
+ '---',
+ `title: ${HERO_FRONTMATTER.title}`,
+ 'tags:',
+ ...HERO_FRONTMATTER.tags.map((t) => ` - ${t}`),
+ '---',
+].join('\n');
+
+const HERO_CHART_HTML = `<div style="font-family:system-ui,-apple-system,sans-serif;height:100%;box-sizing:border-box;display:flex;flex-direction:column;padding:13px 16px 11px;color:var(--foreground)">
+ <div style="flex:none;font-size:15px;font-weight:500;margin-bottom:16px">PRs merged per day · last 30 days</div>
+ <div id="plot" style="position:relative;flex:1 1 auto;min-height:0" aria-label="Daily PRs merged, peaking on launch day"></div>
+ <script>
+ var data=[11,4,1,0.5,0,0,0,0,0,0,0,0,0,0,0,2,0.5,0,0,0,0,1,1.2,1,24,8,1,0.2,0,0.5,0];
+ var max=24,n=data.length,PADL=26,PADR=6,PADT=6,PADB=18;
+ var xN=function(i){return (i/(n-1)*1000).toFixed(1);};
+ var yN=function(v){return ((1-v/max)*1000).toFixed(1);};
+ var base=1000,pts=data.map(function(v,i){return {x:+xN(i),y:+yN(v)};});
+ var line='M '+pts[0].x+' '+pts[0].y;
+ for(var i=0;i<pts.length-1;i++){
+ var p0=pts[i-1]||pts[i],p1=pts[i],p2=pts[i+1],p3=pts[i+2]||p2;
+ var c1x=p1.x+(p2.x-p0.x)/6,c2x=p2.x-(p3.x-p1.x)/6;
+ var c1y=Math.min(base,p1.y+(p2.y-p0.y)/6),c2y=Math.min(base,p2.y-(p3.y-p1.y)/6);
+ line+=' C '+c1x.toFixed(1)+' '+c1y.toFixed(1)+', '+c2x.toFixed(1)+' '+c2y.toFixed(1)+', '+p2.x+' '+p2.y;
+ }
+ var area=line+' L '+pts[n-1].x+' '+base+' L '+pts[0].x+' '+base+' Z';
+ var ticks=[0,6,12,18,24];
+ var grid=ticks.map(function(t){return '<line x1="0" x2="1000" y1="'+yN(t)+'" y2="'+yN(t)+'" vector-effect="non-scaling-stroke" style="stroke:color-mix(in srgb, var(--border) 65%, transparent)" stroke-width="1"/>';}).join('');
+ var svg='<div style="position:absolute;left:'+PADL+'px;right:'+PADR+'px;top:'+PADT+'px;bottom:'+PADB+'px"><svg viewBox="0 0 1000 1000" preserveAspectRatio="none" style="display:block;width:100%;height:100%;overflow:visible">'
+ +'<defs><linearGradient id="g" x1="0" y1="0" x2="0" y2="1"><stop offset="0%" style="stop-color:var(--primary);stop-opacity:0.16"/><stop offset="100%" style="stop-color:var(--primary);stop-opacity:0.015"/></linearGradient></defs>'
+ +grid+'<path d="'+area+'" style="fill:url(#g)"/>'
+ +'<path d="'+line+'" vector-effect="non-scaling-stroke" style="fill:none;stroke:color-mix(in oklab, var(--primary) 78%, white);stroke-width:1.5;stroke-linejoin:round;stroke-linecap:round"/></svg></div>';
+ var ylab=ticks.map(function(t){var top='calc('+PADT+'px + '+(1-t/max).toFixed(4)+' * (100% - '+(PADT+PADB)+'px))';return '<div style="position:absolute;left:0;top:'+top+';width:'+(PADL-8)+'px;text-align:right;transform:translateY(-50%);font-size:10px;line-height:1;color:var(--muted-foreground)">'+t+'</div>';}).join('');
+ var xlab=[[0,'May 10'],[15,'May 25'],[30,'Jun 9']].map(function(d){var left='calc('+PADL+'px + '+(d[0]/(n-1)).toFixed(4)+' * (100% - '+(PADL+PADR)+'px))';return '<div style="position:absolute;bottom:0;left:'+left+';transform:translateX(-50%);font-size:10px;line-height:1;white-space:nowrap;color:var(--muted-foreground)">'+d[1]+'</div>';}).join('');
+ document.getElementById('plot').innerHTML=svg+ylab+xlab;
+ </script>
+</div>`;
+
+export function heroRevealMarkdown(step: number): string {
+ let md = HERO_INTRO;
+ if (step >= 1) md += '\n\n## Highlights';
+ const tasks = step <= 1 ? 0 : Math.min(HERO_TASKS.length, step - 1);
+ if (tasks > 0) md += `\n\n${HERO_TASKS.slice(0, tasks).join('\n')}`;
+ if (step >= 5) md += `\n\n\`\`\`html preview h=224\n${HERO_CHART_HTML}\n\`\`\``;
+ return md;
+}
+
+export const HERO_SEED_MARKDOWN = heroRevealMarkdown(5);
diff --git a/docs/src/components/ok-editor/slash-command.tsx b/docs/src/components/ok-editor/slash-command.tsx
new file mode 100644
index 000000000..89a3220a6
--- /dev/null
+++ b/docs/src/components/ok-editor/slash-command.tsx
@@ -0,0 +1,134 @@
+'use client';
+
+import { autoUpdate, computePosition, flip, offset, shift } from '@floating-ui/dom';
+import { Extension } from '@tiptap/core';
+import { PluginKey } from '@tiptap/pm/state';
+import { ReactRenderer } from '@tiptap/react';
+import Suggestion, { type SuggestionKeyDownProps, type SuggestionProps } from '@tiptap/suggestion';
+import { filterSlashItems, type SlashItem } from './slash-items';
+import { SlashMenu, type SlashMenuProps } from './slash-menu';
+
+const slashKey = new PluginKey('okSlashCommand');
+
+export const SlashCommand = Extension.create({
+ name: 'okSlashCommand',
+
+ addProseMirrorPlugins() {
+ return [
+ Suggestion<SlashItem>({
+ editor: this.editor,
+ pluginKey: slashKey,
+ char: '/',
+ items: ({ query }) => filterSlashItems(query),
+ command: ({ editor, range, props: item }) => {
+ editor.chain().focus().deleteRange(range).run();
+ item.command(editor);
+ },
+ render: () => {
+ let renderer: ReactRenderer<unknown, SlashMenuProps> | null = null;
+ let popup: HTMLElement | null = null;
+ let current: SuggestionProps<SlashItem> | null = null;
+ let selectedIndex = 0;
+ let stopAutoUpdate: (() => void) | null = null;
+
+ const anchor = {
+ getBoundingClientRect: () => current?.clientRect?.() ?? new DOMRect(),
+ get contextElement() {
+ return current?.editor.view.dom;
+ },
+ };
+
+ const reposition = () => {
+ if (!popup) return;
+ computePosition(anchor, popup, {
+ strategy: 'fixed',
+ placement: 'bottom-start',
+ middleware: [offset(6), flip(), shift({ padding: 8 })],
+ }).then(({ x, y }) => {
+ if (!popup) return;
+ popup.style.left = `${x}px`;
+ popup.style.top = `${y}px`;
+ const caret = current?.clientRect?.();
+ const onScreen = !!caret && caret.bottom > 0 && caret.top < window.innerHeight;
+ popup.style.visibility = onScreen ? 'visible' : 'hidden';
+ });
+ };
+
+ const update = () => {
+ if (!renderer || !current) return;
+ renderer.updateProps({
+ items: current.items,
+ selectedIndex,
+ onSelect: current.command,
+ onHoverIndex: (i: number) => {
+ selectedIndex = i;
+ update();
+ },
+ });
+ };
+
+ return {
+ onStart(props: SuggestionProps<SlashItem>) {
+ current = props;
+ selectedIndex = 0;
+ popup = document.createElement('div');
+ popup.className = 'ok-slash-popup';
+ popup.style.visibility = 'hidden'; // revealed once positioned
+ document.body.appendChild(popup);
+ renderer = new ReactRenderer<unknown, SlashMenuProps>(SlashMenu, {
+ props: {
+ items: props.items,
+ selectedIndex,
+ onSelect: props.command,
+ onHoverIndex: (i: number) => {
+ selectedIndex = i;
+ update();
+ },
+ },
+ editor: props.editor,
+ });
+ popup.appendChild(renderer.element);
+ stopAutoUpdate = autoUpdate(anchor, popup, reposition);
+ },
+ onUpdate(props: SuggestionProps<SlashItem>) {
+ current = props;
+ selectedIndex = Math.min(selectedIndex, Math.max(0, props.items.length - 1));
+ update();
+ reposition();
+ },
+ onKeyDown({ event }: SuggestionKeyDownProps) {
+ if (!current || current.items.length === 0) return false;
+ const items = current.items;
+ if (event.key === 'ArrowDown') {
+ selectedIndex = (selectedIndex + 1) % items.length;
+ update();
+ return true;
+ }
+ if (event.key === 'ArrowUp') {
+ selectedIndex = (selectedIndex - 1 + items.length) % items.length;
+ update();
+ return true;
+ }
+ if (event.key === 'Enter' || event.key === 'Tab') {
+ const item = items[selectedIndex];
+ if (item) current.command(item);
+ return true;
+ }
+ return false;
+ },
+ onExit() {
+ stopAutoUpdate?.();
+ renderer?.destroy();
+ popup?.remove();
+ stopAutoUpdate = null;
+ renderer = null;
+ popup = null;
+ current = null;
+ selectedIndex = 0;
+ },
+ };
+ },
+ }),
+ ];
+ },
+});
diff --git a/docs/src/components/ok-editor/slash-items.tsx b/docs/src/components/ok-editor/slash-items.tsx
new file mode 100644
index 000000000..6369797c9
--- /dev/null
+++ b/docs/src/components/ok-editor/slash-items.tsx
@@ -0,0 +1,136 @@
+'use client';
+
+import type { Editor } from '@tiptap/react';
+import {
+ BarChart3,
+ Code2,
+ Heading1,
+ Heading2,
+ Heading3,
+ List,
+ ListOrdered,
+ ListTodo,
+ type LucideIcon,
+ Minus,
+ Quote,
+} from 'lucide-react';
+
+export interface SlashItem {
+ name: string;
+ label: string;
+ icon: LucideIcon;
+ aliases?: string[];
+ command: (editor: Editor) => void;
+}
+
+const CHART_HTML = `<div style="font-family:system-ui,-apple-system,sans-serif;padding:13px 16px 11px;color:var(--foreground)">
+ <h3 style="margin:0 0 16px;font-size:15px;font-weight:500">Revenue by region</h3>
+ <div id="bars" style="display:flex;align-items:flex-end;gap:14px;height:170px"></div>
+ <script>
+ var data = [['North', 42], ['South', 58], ['East', 71], ['West', 64], ['Central', 80]];
+ var max = Math.max.apply(null, data.map(function (d) { return d[1]; }));
+ document.getElementById('bars').innerHTML = data.map(function (d, i) {
+ return '<div style="flex:1;display:flex;flex-direction:column;align-items:center;' +
+ 'gap:6px;height:100%;justify-content:flex-end">' +
+ '<span style="font-size:12px;color:var(--muted-foreground)">' + d[1] + '</span>' +
+ '<div style="width:100%;height:' + (d[1] / max * 100) + '%;' +
+ 'background:var(--chart-' + (i + 1) + ');' +
+ 'border-radius:var(--radius) var(--radius) 0 0"></div>' +
+ '<span style="font-size:12px;color:var(--muted-foreground)">' + d[0] + '</span>' +
+ '</div>';
+ }).join('');
+ </script>
+</div>`;
+
+const SLASH_ITEMS: readonly SlashItem[] = [
+ {
+ name: 'heading1',
+ label: 'Heading 1',
+ icon: Heading1,
+ aliases: ['h1', 'title'],
+ command: (e) => e.chain().focus().toggleHeading({ level: 1 }).run(),
+ },
+ {
+ name: 'heading2',
+ label: 'Heading 2',
+ icon: Heading2,
+ aliases: ['h2'],
+ command: (e) => e.chain().focus().toggleHeading({ level: 2 }).run(),
+ },
+ {
+ name: 'heading3',
+ label: 'Heading 3',
+ icon: Heading3,
+ aliases: ['h3'],
+ command: (e) => e.chain().focus().toggleHeading({ level: 3 }).run(),
+ },
+ {
+ name: 'bulletList',
+ label: 'Bullet List',
+ icon: List,
+ aliases: ['ul', 'unordered'],
+ command: (e) => e.chain().focus().toggleBulletList().run(),
+ },
+ {
+ name: 'orderedList',
+ label: 'Numbered List',
+ icon: ListOrdered,
+ aliases: ['ol', 'ordered', 'numbered'],
+ command: (e) => e.chain().focus().toggleOrderedList().run(),
+ },
+ {
+ name: 'taskList',
+ label: 'Task List',
+ icon: ListTodo,
+ aliases: ['todo', 'checklist', 'checkbox'],
+ command: (e) => e.chain().focus().toggleTaskList().run(),
+ },
+ {
+ name: 'blockquote',
+ label: 'Quote',
+ icon: Quote,
+ aliases: ['quote'],
+ command: (e) => e.chain().focus().toggleBlockquote().run(),
+ },
+ {
+ name: 'codeBlock',
+ label: 'Code Block',
+ icon: Code2,
+ aliases: ['code', 'fence'],
+ command: (e) => e.chain().focus().toggleCodeBlock({ language: 'js' }).run(),
+ },
+ {
+ name: 'separator',
+ label: 'Separator',
+ icon: Minus,
+ aliases: ['hr', 'divider', 'rule'],
+ command: (e) => e.chain().focus().setHorizontalRule().run(),
+ },
+ {
+ name: 'chart',
+ label: 'Chart',
+ icon: BarChart3,
+ aliases: ['embed', 'graph', 'html'],
+ command: (e) =>
+ e
+ .chain()
+ .focus()
+ .insertContent({
+ type: 'codeBlock',
+ attrs: { language: 'html', meta: 'preview h=230' },
+ content: [{ type: 'text', text: CHART_HTML }],
+ })
+ .run(),
+ },
+];
+
+export function filterSlashItems(query: string): SlashItem[] {
+ if (!query) return [...SLASH_ITEMS];
+ const q = query.toLowerCase();
+ return SLASH_ITEMS.filter(
+ (item) =>
+ item.label.toLowerCase().includes(q) ||
+ item.name.toLowerCase().includes(q) ||
+ item.aliases?.some((a) => a.toLowerCase().includes(q)),
+ );
+}
diff --git a/docs/src/components/ok-editor/slash-menu.tsx b/docs/src/components/ok-editor/slash-menu.tsx
new file mode 100644
index 000000000..71cb72a6d
--- /dev/null
+++ b/docs/src/components/ok-editor/slash-menu.tsx
@@ -0,0 +1,45 @@
+'use client';
+
+import type { SlashItem } from './slash-items';
+
+export interface SlashMenuProps {
+ items: SlashItem[];
+ selectedIndex: number;
+ onSelect: (item: SlashItem) => void;
+ onHoverIndex: (index: number) => void;
+}
+
+export function SlashMenu({ items, selectedIndex, onSelect, onHoverIndex }: SlashMenuProps) {
+ if (items.length === 0) {
+ return (
+ <div className="ok-slash-empty" role="status">
+ No results
+ </div>
+ );
+ }
+ return (
+ <div className="ok-slash-menu" role="listbox" aria-label="Insert block">
+ {items.map((item, i) => {
+ const Icon = item.icon;
+ return (
+ <button
+ type="button"
+ key={item.name}
+ role="option"
+ aria-selected={i === selectedIndex}
+ data-active={i === selectedIndex}
+ className="ok-slash-item"
+ onMouseDown={(e) => {
+ e.preventDefault();
+ onSelect(item);
+ }}
+ onMouseEnter={() => onHoverIndex(i)}
+ >
+ <Icon className="ok-slash-item-icon" />
+ <span>{item.label}</span>
+ </button>
+ );
+ })}
+ </div>
+ );
+}
diff --git a/docs/src/components/ok-editor/source-editor.tsx b/docs/src/components/ok-editor/source-editor.tsx
new file mode 100644
index 000000000..d129ba181
--- /dev/null
+++ b/docs/src/components/ok-editor/source-editor.tsx
@@ -0,0 +1,63 @@
+'use client';
+
+import { defaultKeymap, history, historyKeymap, indentWithTab } from '@codemirror/commands';
+import { markdown } from '@codemirror/lang-markdown';
+import { defaultHighlightStyle, syntaxHighlighting } from '@codemirror/language';
+import { EditorState } from '@codemirror/state';
+import { EditorView, keymap } from '@codemirror/view';
+import { type RefObject, useEffect, useRef } from 'react';
+
+const cmTheme = EditorView.theme({
+ '&': { backgroundColor: 'transparent', color: 'var(--slide-text)' },
+ '&.cm-focused': { outline: 'none' },
+ '.cm-content': {
+ fontFamily: 'var(--font-mono)',
+ fontSize: '0.8125rem',
+ lineHeight: '1.7',
+ padding: '0',
+ caretColor: 'var(--slide-text)',
+ },
+ '.cm-line': { padding: '0' },
+ '.cm-cursor': { borderLeftColor: 'var(--slide-text)' },
+ '.cm-selectionBackground, &.cm-focused .cm-selectionBackground': {
+ backgroundColor: 'color-mix(in oklab, var(--primary) 18%, transparent)',
+ },
+});
+
+export function SourceEditor({
+ initialDoc,
+ viewRef,
+}: {
+ initialDoc: string;
+ viewRef: RefObject<EditorView | null>;
+}) {
+ const hostRef = useRef<HTMLDivElement>(null);
+
+ // biome-ignore lint/correctness/useExhaustiveDependencies: mount-once — parent re-mounts with a fresh initialDoc each source-mode entry; viewRef is a stable ref. Reacting would rebuild the CodeMirror view mid-edit.
+ useEffect(() => {
+ const host = hostRef.current;
+ if (!host) return;
+ const view = new EditorView({
+ parent: host,
+ state: EditorState.create({
+ doc: initialDoc,
+ extensions: [
+ history(),
+ keymap.of([...defaultKeymap, ...historyKeymap, indentWithTab]),
+ markdown(),
+ syntaxHighlighting(defaultHighlightStyle, { fallback: true }),
+ EditorView.lineWrapping,
+ cmTheme,
+ ],
+ }),
+ });
+ viewRef.current = view;
+ view.focus();
+ return () => {
+ view.destroy();
+ viewRef.current = null;
+ };
+ }, []);
+
+ return <div ref={hostRef} className="ok-source-host" />;
+}
diff --git a/docs/src/components/ui/dropdown-menu.tsx b/docs/src/components/ui/dropdown-menu.tsx
new file mode 100644
index 000000000..a5f436162
--- /dev/null
+++ b/docs/src/components/ui/dropdown-menu.tsx
@@ -0,0 +1,228 @@
+'use client';
+
+import { CheckIcon, ChevronRightIcon, CircleIcon } from 'lucide-react';
+import { DropdownMenu as DropdownMenuPrimitive } from 'radix-ui';
+import type * as React from 'react';
+
+import { cn } from '@/lib/utils';
+
+function DropdownMenu({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Root>) {
+ return <DropdownMenuPrimitive.Root data-slot="dropdown-menu" {...props} />;
+}
+
+function DropdownMenuPortal({
+ ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Portal>) {
+ return <DropdownMenuPrimitive.Portal data-slot="dropdown-menu-portal" {...props} />;
+}
+
+function DropdownMenuTrigger({
+ ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Trigger>) {
+ return <DropdownMenuPrimitive.Trigger data-slot="dropdown-menu-trigger" {...props} />;
+}
+
+function DropdownMenuContent({
+ className,
+ sideOffset = 4,
+ ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Content>) {
+ return (
+ <DropdownMenuPrimitive.Portal>
+ <DropdownMenuPrimitive.Content
+ data-slot="dropdown-menu-content"
+ sideOffset={sideOffset}
+ className={cn(
+ 'z-50 max-h-(--radix-dropdown-menu-content-available-height) min-w-[8rem] origin-(--radix-dropdown-menu-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-md border bg-slide-bg-elevated p-1 text-slide-text shadow-md data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95',
+ className,
+ )}
+ {...props}
+ />
+ </DropdownMenuPrimitive.Portal>
+ );
+}
+
+function DropdownMenuGroup({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Group>) {
+ return <DropdownMenuPrimitive.Group data-slot="dropdown-menu-group" {...props} />;
+}
+
+function DropdownMenuItem({
+ className,
+ inset,
+ variant = 'default',
+ ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Item> & {
+ inset?: boolean;
+ variant?: 'default' | 'destructive';
+}) {
+ return (
+ <DropdownMenuPrimitive.Item
+ data-slot="dropdown-menu-item"
+ data-inset={inset}
+ data-variant={variant}
+ className={cn(
+ "relative flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none focus:bg-slide-text/[0.06] focus:text-slide-text data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[inset]:pl-8 data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 data-[variant=destructive]:focus:text-destructive dark:data-[variant=destructive]:focus:bg-destructive/20 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 [&_svg:not([class*='text-'])]:text-slide-muted data-[variant=destructive]:*:[svg]:text-destructive!",
+ className,
+ )}
+ {...props}
+ />
+ );
+}
+
+function DropdownMenuCheckboxItem({
+ className,
+ children,
+ checked,
+ ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.CheckboxItem>) {
+ return (
+ <DropdownMenuPrimitive.CheckboxItem
+ data-slot="dropdown-menu-checkbox-item"
+ className={cn(
+ "relative flex cursor-default items-center gap-2 rounded-sm py-1.5 pr-2 pl-8 text-sm outline-hidden select-none focus:bg-slide-text/[0.06] focus:text-slide-text data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+ className,
+ )}
+ checked={checked}
+ {...props}
+ >
+ <span className="pointer-events-none absolute left-2 flex size-3.5 items-center justify-center">
+ <DropdownMenuPrimitive.ItemIndicator>
+ <CheckIcon className="size-4" />
+ </DropdownMenuPrimitive.ItemIndicator>
+ </span>
+ {children}
+ </DropdownMenuPrimitive.CheckboxItem>
+ );
+}
+
+function DropdownMenuRadioGroup({
+ ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.RadioGroup>) {
+ return <DropdownMenuPrimitive.RadioGroup data-slot="dropdown-menu-radio-group" {...props} />;
+}
+
+function DropdownMenuRadioItem({
+ className,
+ children,
+ ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.RadioItem>) {
+ return (
+ <DropdownMenuPrimitive.RadioItem
+ data-slot="dropdown-menu-radio-item"
+ className={cn(
+ "relative flex cursor-default items-center gap-2 rounded-sm py-1.5 pr-2 pl-8 text-sm outline-hidden select-none focus:bg-slide-text/[0.06] focus:text-slide-text data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+ className,
+ )}
+ {...props}
+ >
+ <span className="pointer-events-none absolute left-2 flex size-3.5 items-center justify-center">
+ <DropdownMenuPrimitive.ItemIndicator>
+ <CircleIcon className="size-2 fill-current" />
+ </DropdownMenuPrimitive.ItemIndicator>
+ </span>
+ {children}
+ </DropdownMenuPrimitive.RadioItem>
+ );
+}
+
+function DropdownMenuLabel({
+ className,
+ inset,
+ ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Label> & {
+ inset?: boolean;
+}) {
+ return (
+ <DropdownMenuPrimitive.Label
+ data-slot="dropdown-menu-label"
+ data-inset={inset}
+ className={cn('px-2 py-1.5 text-sm font-medium data-[inset]:pl-8', className)}
+ {...props}
+ />
+ );
+}
+
+function DropdownMenuSeparator({
+ className,
+ ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Separator>) {
+ return (
+ <DropdownMenuPrimitive.Separator
+ data-slot="dropdown-menu-separator"
+ className={cn('-mx-1 my-1 h-px bg-slide-border', className)}
+ {...props}
+ />
+ );
+}
+
+function DropdownMenuShortcut({ className, ...props }: React.ComponentProps<'span'>) {
+ return (
+ <span
+ data-slot="dropdown-menu-shortcut"
+ className={cn('ml-auto text-xs tracking-widest text-slide-muted', className)}
+ {...props}
+ />
+ );
+}
+
+function DropdownMenuSub({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Sub>) {
+ return <DropdownMenuPrimitive.Sub data-slot="dropdown-menu-sub" {...props} />;
+}
+
+function DropdownMenuSubTrigger({
+ className,
+ inset,
+ children,
+ ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.SubTrigger> & {
+ inset?: boolean;
+}) {
+ return (
+ <DropdownMenuPrimitive.SubTrigger
+ data-slot="dropdown-menu-sub-trigger"
+ data-inset={inset}
+ className={cn(
+ "flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none focus:bg-slide-text/[0.06] focus:text-slide-text data-[inset]:pl-8 data-[state=open]:bg-slide-text/[0.06] data-[state=open]:text-slide-text [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 [&_svg:not([class*='text-'])]:text-slide-muted",
+ className,
+ )}
+ {...props}
+ >
+ {children}
+ <ChevronRightIcon className="ml-auto size-4" />
+ </DropdownMenuPrimitive.SubTrigger>
+ );
+}
+
+function DropdownMenuSubContent({
+ className,
+ ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.SubContent>) {
+ return (
+ <DropdownMenuPrimitive.SubContent
+ data-slot="dropdown-menu-sub-content"
+ className={cn(
+ 'z-50 min-w-[8rem] origin-(--radix-dropdown-menu-content-transform-origin) overflow-hidden rounded-md border bg-slide-bg-elevated p-1 text-slide-text shadow-lg data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95',
+ className,
+ )}
+ {...props}
+ />
+ );
+}
+
+export {
+ DropdownMenu,
+ DropdownMenuCheckboxItem,
+ DropdownMenuContent,
+ DropdownMenuGroup,
+ DropdownMenuItem,
+ DropdownMenuLabel,
+ DropdownMenuPortal,
+ DropdownMenuRadioGroup,
+ DropdownMenuRadioItem,
+ DropdownMenuSeparator,
+ DropdownMenuShortcut,
+ DropdownMenuSub,
+ DropdownMenuSubContent,
+ DropdownMenuSubTrigger,
+ DropdownMenuTrigger,
+};
diff --git a/docs/src/components/ui/tooltip.tsx b/docs/src/components/ui/tooltip.tsx
new file mode 100644
index 000000000..7dfde15a1
--- /dev/null
+++ b/docs/src/components/ui/tooltip.tsx
@@ -0,0 +1,53 @@
+'use client';
+
+import { Tooltip as TooltipPrimitive } from 'radix-ui';
+import type * as React from 'react';
+
+import { cn } from '@/lib/utils';
+
+function TooltipProvider({
+ delayDuration = 0,
+ ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
+ return (
+ <TooltipPrimitive.Provider
+ data-slot="tooltip-provider"
+ delayDuration={delayDuration}
+ {...props}
+ />
+ );
+}
+
+function Tooltip({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Root>) {
+ return <TooltipPrimitive.Root data-slot="tooltip" {...props} />;
+}
+
+function TooltipTrigger({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
+ return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />;
+}
+
+function TooltipContent({
+ className,
+ sideOffset = 0,
+ children,
+ ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Content>) {
+ return (
+ <TooltipPrimitive.Portal>
+ <TooltipPrimitive.Content
+ data-slot="tooltip-content"
+ sideOffset={sideOffset}
+ className={cn(
+ 'z-50 w-fit origin-(--radix-tooltip-content-transform-origin) animate-in rounded-md bg-slide-text px-3 py-1.5 text-xs text-balance text-slide-bg fade-in-0 zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
+ className,
+ )}
+ {...props}
+ >
+ {children}
+ <TooltipPrimitive.Arrow className="z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px] bg-slide-text fill-slide-text" />
+ </TooltipPrimitive.Content>
+ </TooltipPrimitive.Portal>
+ );
+}
+
+export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger };
diff --git a/docs/tsconfig.json b/docs/tsconfig.json
index 4c18a4f4f..b4b6ecbc4 100644
--- a/docs/tsconfig.json
+++ b/docs/tsconfig.json
@@ -4,6 +4,10 @@
"target": "ESNext",
"module": "esnext",
"lib": ["dom", "dom.iterable", "esnext"],
+ // @inkeep/open-knowledge-core resolves to its TS source (exports `types` →
+ // ./src/index.ts), whose internal imports carry explicit .ts extensions —
+ // same flag core/app set to consume it.
+ "allowImportingTsExtensions": true,
"allowJs": true,
"noEmit": true,
"jsx": "react-jsx",
diff --git a/knip.config.ts b/knip.config.ts
index e2a5643d0..eb5629fb6 100644
--- a/knip.config.ts
+++ b/knip.config.ts
@@ -18,6 +18,7 @@ export default {
ignoreIssues: {
'packages/app/src/locales/**': ['files'],
'packages/app/src/components/ui/*': ['exports'],
+ 'docs/src/components/ui/*': ['exports'],
'docs/source.config.ts': ['exports'],
'packages/app/src/editor/extensions/internal-link.ts': ['exports', 'types'],
'packages/app/src/editor/clipboard/serialize.ts': ['types'],