@miethe/ui 0.2.0 → 0.6.0

package/README.md

@@ -71,17 +71,37 @@ Or reference the workspace package directly in `package.json`:
 
 ## Subpath Imports
 
-The package is organized into seven submodules with tree-shakeable exports:
+The package is organized into eight submodules with tree-shakeable exports.
+
+**IMPORTANT: Server Component Rule**
+
+Never import from the root barrel (`@miethe/ui`) in a React Server Component. All re-exports lack a `'use client'` directive and will fail in server-component-only files. Use subpath imports instead:
+
+```typescript
+// ✗ Server component — do not use root barrel
+import { FileTree, ContentPane } from '@miethe/ui';
+
+// ✓ Server component — use subpath imports
+import { FileTree, ContentPane } from '@miethe/ui/content-viewer';
+```
+
+Client components can safely use root barrel imports (the `'use client'` directive in submodules propagates to consumers).
+
+**Available Subpaths**:
 
 ```typescript
 // Content viewer components
-import { FileTree, ContentPane, ContentViewerProvider } from '@miethe/ui/content-viewer';
+import { FileTree, ContentPane, ArticleViewer, ContentViewerProvider } from '@miethe/ui/content-viewer';
 
 // Diff viewing components
 import { DiffViewer, DiffViewerSkeleton } from '@miethe/ui/diff';
 
+// Discovery card (compact artifact discovery / search contexts)
+import { DiscoveryCard } from '@miethe/ui/discovery';
+import type { DiscoveryCardProps, AgentDiscoveryCandidate } from '@miethe/ui/discovery';
+
 // Editor components
-import { MarkdownEditor, SplitPreview } from '@miethe/ui/editor';
+import { MarkdownEditor, SplitPreview, CodeEditor } from '@miethe/ui/editor';
 
 // Display components
 import { FrontmatterDisplay, FilePreviewPane } from '@miethe/ui/display';
@@ -136,6 +156,52 @@ module.exports = {
 
 **Important**: Without Tailwind CSS configured, components will render with no styles. Components use semantic Tailwind classes like `text-muted-foreground` and `bg-background` — ensure your Tailwind config includes these classes (standard in shadcn/ui projects).
 
+### Required shadcn-Compatible CSS Variables
+
+Define these CSS variables at `:root` or an appropriate ancestor element. These variables control the color palette for all UI components:
+
+```css
+:root {
+  --background: 0 0% 100%;
+  --foreground: 0 0% 3.6%;
+  --muted: 0 0% 96.1%;
+  --muted-foreground: 0 0% 45.1%;
+  --card: 0 0% 100%;
+  --card-foreground: 0 0% 3.6%;
+  --border: 0 0% 89.8%;
+  --ring: 0 0% 3.6%;
+  --primary: 0 0% 9%;
+  --accent: 0 84.6% 60.2%;
+  --accent-foreground: 0 0% 100%;
+  --secondary: 0 0% 14.9%;
+  --secondary-foreground: 0 0% 100%;
+  --destructive: 0 84.3% 60.2%;
+  --input: 0 0% 89.8%;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --background: 0 0% 3.6%;
+    --foreground: 0 0% 98%;
+    --muted: 0 0% 14.9%;
+    --muted-foreground: 0 0% 63.9%;
+    --card: 0 0% 3.6%;
+    --card-foreground: 0 0% 98%;
+    --border: 0 0% 14.9%;
+    --ring: 0 84.6% 60.2%;
+    --primary: 0 0% 98%;
+    --accent: 0 84.6% 60.2%;
+    --accent-foreground: 0 0% 9%;
+    --secondary: 0 0% 85.1%;
+    --secondary-foreground: 0 0% 9%;
+    --destructive: 0 84.3% 60.2%;
+    --input: 0 0% 14.9%;
+  }
+}
+```
+
+All components degrade gracefully if some variables are missing — the browser will use default colors. Define only the ones you need to customize.
+
 ### Dark Mode
 
 Components support dark mode via the Tailwind `dark:` variant. Enable dark mode in your Tailwind config:
@@ -163,6 +229,54 @@ Then add the `dark` class to your root HTML element to activate dark mode styles
 
 Or use a theme provider component that toggles the class dynamically based on user preference.
 
+### CodeMirror Deduplication
+
+CodeMirror 6 requires exactly **one** `@codemirror/state` instance in the dependency tree. If multiple versions are installed, the editor will fail silently or behave unpredictably.
+
+**Verify Installation**:
+
+```bash
+npm ls @codemirror/state
+# or
+yarn why @codemirror/state
+# or
+pnpm ls @codemirror/state
+```
+
+If you see multiple versions, force deduplication in `package.json`:
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "@codemirror/state": "^6.4.0"
+    }
+  }
+}
+```
+
+For yarn, use `resolutions`:
+
+```json
+{
+  "resolutions": {
+    "@codemirror/state": "^6.4.0"
+  }
+}
+```
+
+For npm, add an `overrides` field (npm v8.3.0+):
+
+```json
+{
+  "overrides": {
+    "@codemirror/state": "^6.4.0"
+  }
+}
+```
+
+After updating, reinstall and verify the deduplicated list shows only one entry.
+
 ## Quick Start
 
 ### 1. Create an Adapter
@@ -283,6 +397,67 @@ export function FilePreviewExample() {
 
 ## Components API
 
+### DiscoveryCard
+
+Compact single-tier artifact card for discovery and search result contexts. Designed for reuse across `/discover` and marketplace search results pages.
+
+**Props:**
+
+```typescript
+interface DiscoveryCardProps {
+  candidate: AgentDiscoveryCandidate;        // The discovery candidate to display
+  isSelected: boolean;                        // Selection state (affects styling)
+  onToggleSelect: (candidate) => void;       // Called when checkbox is toggled
+  onOpenDetail: (candidate) => void;         // Called when card is clicked
+  onImport: (candidate) => void;             // Called when Import button is clicked
+  onDeploy: (candidate) => void;             // Called when Deploy button is clicked
+  isImporting?: boolean;                     // Show loading state on Import
+  isDeploying?: boolean;                     // Show loading state on Deploy
+  importDisabled?: boolean;                  // Disable Import button
+  deployDisabled?: boolean;                  // Disable Deploy button
+  className?: string;                        // Additional className
+}
+```
+
+**Features:**
+
+- Fixed-height card (min 160px) with left-border type color from `typeBarColors`
+- Three zones: header (type icon + name + badges) | content (description + marketplace source + score bar) | actions (checkbox + import/deploy buttons)
+- Source-aware rendering: shows collection/marketplace/web badges and source links
+- Trust tier badge with icon (trusted, candidate, unverified, quarantined)
+- Relevance score bar (0.0–1.0 displayed as 0–100%)
+- Selection state with ring styling
+- No app-hook coupling: all data and handlers passed as props
+
+**Design Contract:**
+
+- Parent grid must use `auto-rows-fr` for uniform row heights
+- Type colors from `@miethe/ui/utils` (`typeBarColors`, `TYPE_BAR_FALLBACK`)
+- Icon colors from component-local `TYPE_ICON_*` maps (semi-transparent variants)
+
+**Example:**
+
+```typescript
+import { DiscoveryCard } from '@miethe/ui/discovery';
+
+<div className="grid grid-cols-3 auto-rows-fr gap-4">
+  {candidates.map((candidate) => (
+    <DiscoveryCard
+      key={candidate.name}
+      candidate={candidate}
+      isSelected={selected.has(candidate.name)}
+      onToggleSelect={handleSelect}
+      onOpenDetail={handleDetail}
+      onImport={handleImport}
+      onDeploy={handleDeploy}
+      isImporting={importing === candidate.name}
+    />
+  ))}
+</div>
+```
+
+**Full Documentation:** See `src/discovery/README.md` for complete API reference, zone architecture, accessibility notes, and marketplace reuse guidance.
+
 ### DiffViewer
 
 A side-by-side unified diff viewer with file browser sidebar and optional sync conflict resolution actions.
@@ -485,6 +660,252 @@ interface FileTreeProps {
 />
 ```
 
+### ArticleViewer
+
+Read-only markdown and HTML renderer with frontmatter support, callouts, and typography variants.
+
+**Props:**
+
+```typescript
+interface ArticleViewerProps {
+  /**
+   * The raw content string to render.
+   * For markdown, the full remark pipeline (GFM + directives) is applied.
+   * YAML frontmatter (if present) is extracted and not rendered as content.
+   */
+  content: string;
+
+  /**
+   * Format of the content. Defaults to `"auto"` which detects markdown
+   * by looking for common markdown patterns.
+   * @default "auto"
+   */
+  format?: 'markdown' | 'html' | 'auto';
+
+  /**
+   * Typography variant. Applies a CSS class (`cv-variant-{name}`) to the root
+   * element. Each variant relies on CSS custom properties at document root.
+   * See the CSS-Variable Contract below for the full list of expected variables.
+   * @default undefined (no variant class applied)
+   */
+  variant?: 'editorial' | 'compact' | 'technical';
+
+  /**
+   * Controls visibility of the YAML frontmatter header above article content.
+   * - `"show"` — header rendered, expanded by default
+   * - `"collapse"` — header rendered, collapsed by default
+   * - `"hide"` — header omitted entirely
+   * Has no effect if the content has no frontmatter.
+   * @default "hide"
+   */
+  frontmatter?: 'show' | 'collapse' | 'hide';
+
+  /**
+   * Override map for sub-components rendered by ArticleViewer.
+   * - Callout keys (`note`, `reference`, `warning`, `info`): override default callout renderers
+   * - `FrontmatterHeader`: override the default frontmatter header component
+   *
+   * Any key not provided falls back to the default implementation.
+   */
+  components?: {
+    note?: React.ComponentType<CalloutProps>;
+    reference?: React.ComponentType<CalloutProps>;
+    warning?: React.ComponentType<CalloutProps>;
+    info?: React.ComponentType<CalloutProps>;
+    FrontmatterHeader?: React.ComponentType<FrontmatterHeaderProps>;
+  };
+
+  /**
+   * Whether to sanitize HTML content (applies to `format="html"` and auto-detected HTML).
+   * When `true` (default for HTML input), `rehype-sanitize@6` strips XSS vectors:
+   * `<script>`, event handlers (`onclick`, `onerror`, …), `javascript:` and unsafe
+   * `data:` URLs, `<iframe>`, `<object>`, `<embed>`, and `<svg>` containing scripts.
+   *
+   * Set to `false` **only** when the HTML source is fully trusted (e.g., content
+   * compiled by the MeatyWiki engine through Portal's controlled pipeline).
+   * Never set `false` for user-supplied or third-party content.
+   *
+   * @default true (for format="html" / auto-detected HTML), false (for format="markdown")
+   */
+  sanitize?: boolean;
+
+  /**
+   * Enable opt-in syntax highlighting for fenced code blocks via lowlight.
+   * When `false` (default), code blocks render as styled monospace plain text.
+   * When `true`, dynamically imports lowlight (~15KB gzip) and applies highlighting.
+   *
+   * @default false
+   */
+  codeHighlight?: boolean;
+
+  /**
+   * Automatically generate `id` attributes on heading elements (h1–h6)
+   * using a GitHub-compatible slug algorithm.
+   * @default true
+   */
+  generateHeadingIds?: boolean;
+
+  /**
+   * When `true`, suppress all content rendering and show an accessible
+   * skeleton/placeholder instead.
+   * @default false
+   */
+  isLoading?: boolean;
+
+  /**
+   * Render an accessible error message instead of content.
+   * Accepts either a `string` message or an `Error` object.
+   * @default undefined
+   */
+  error?: string | Error | null;
+
+  /**
+   * Callback invoked when a rendering error occurs.
+   */
+  onError?: (error: Error) => void;
+
+  /**
+   * Additional CSS class names applied to the root wrapper element.
+   */
+  className?: string;
+}
+```
+
+**Features:**
+
+- Full CommonMark + GitHub-Flavored Markdown (tables, task lists, strikethrough, blockquotes, code blocks, links, lists)
+- Callout directives: `::: note`, `::: reference`, `::: warning`, `::: info` with customizable components
+- YAML frontmatter parsing and optional display via collapsible header
+- HTML input support with XSS sanitization (default ON; opt-out for trusted sources)
+- Typography variants (CSS-variable-driven): editorial, compact, technical
+- Syntax highlighting (opt-in, lowlight-based)
+- Heading anchor links (auto-generated IDs)
+- Loading and error states
+- Fully typed TypeScript exports
+- Zero React Markdown coupling (pure remark pipeline)
+
+**CSS-Variable Contract:**
+
+When using `variant="editorial"`, define these variables at `:root` or a suitable ancestor:
+
+```css
+:root {
+  /* Typography */
+  --cv-editorial-h1-font: Fraunces, Georgia, serif;
+  --cv-editorial-h1-size: 2.25rem;
+  --cv-editorial-h2-font: Fraunces, Georgia, serif;
+  --cv-editorial-h2-size: 1.875rem;
+  --cv-editorial-body-font: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  --cv-editorial-body-size: 1rem;
+  --cv-editorial-body-line-height: 1.75;
+  
+  /* Quotes & blockquotes */
+  --cv-editorial-quote-color: #64748b;
+  --cv-editorial-quote-font-style: italic;
+  
+  /* Callout colors */
+  --cv-callout-note-accent: #0ea5e9;
+  --cv-callout-note-bg: #f0f9ff;
+  --cv-callout-reference-accent: #64748b;
+  --cv-callout-reference-bg: #f1f5f9;
+  --cv-callout-warning-accent: #f59e0b;
+  --cv-callout-warning-bg: #fffbeb;
+  --cv-callout-info-accent: #0ea5e9;
+  --cv-callout-info-bg: #f0f9ff;
+}
+```
+
+Analogous `--cv-compact-*` and `--cv-technical-*` sets follow the same pattern. Missing variables are silently ignored — browser defaults apply.
+
+**Examples:**
+
+```typescript
+import { ArticleViewer } from '@miethe/ui/content-viewer';
+
+// Basic markdown rendering
+<ArticleViewer
+  content="# Hello\n\nThis is **bold** and *italic*."
+  format="markdown"
+/>
+
+// With frontmatter display
+<ArticleViewer
+  content={`---
+title: My Article
+date: 2026-04-24
+tags: [markdown, ui]
+---
+
+# Article title
+
+Content here...`}
+  frontmatter="show"
+  variant="editorial"
+/>
+
+// With callouts
+<ArticleViewer
+  content={`# Document
+
+::: note
+This is a note callout.
+:::
+
+::: warning
+This is a warning.
+:::`}
+  format="markdown"
+/>
+
+// With callout override
+<ArticleViewer
+  content={markdown}
+  components={{
+    note: CustomNoteCallout,
+    warning: CustomWarningCallout,
+  }}
+/>
+
+// HTML input with sanitization (default ON)
+<ArticleViewer
+  content="<p>This <script>alert('xss')</script> is <strong>safe</strong>.</p>"
+  format="html"
+  sanitize={true}
+/>
+
+// Trusted engine-compiled HTML (sanitization OFF)
+<ArticleViewer
+  content={engineOutput}
+  format="html"
+  sanitize={false}
+/>
+
+// With syntax highlighting
+<ArticleViewer
+  content={`\`\`\`typescript
+function hello(name: string) {
+  console.log('Hello', name);
+}
+\`\`\``}
+  codeHighlight={true}
+/>
+
+// Typography variant with custom CSS variables
+<ArticleViewer
+  content={markdown}
+  variant="editorial"
+/>
+{/* In your globals.css: */}
+{/* :root { --cv-editorial-body-font: 'Libre Baskerville', serif; ... } */}
+```
+
+**Sanitization Notes:**
+
+- By default, HTML input is sanitized via `rehype-sanitize@6`, which strips script tags, event handlers, unsafe URLs, and dangerous elements
+- Markdown input (via `react-markdown`) is inherently safe — the sanitization prop has no effect on markdown
+- For pre-compiled engine output (trusted source), set `sanitize={false}` to skip sanitization overhead
+- For user-supplied or third-party HTML, always use `sanitize={true}` (the default)
+
 ### ContentPane
 
 Display and edit file content with syntax highlighting, markdown preview, and optional editing.
@@ -499,6 +920,8 @@ interface ContentPaneProps {
   error?: string | null;         // Error message to display
   readOnly?: boolean;            // Hide edit/save buttons (default: false)
   truncationInfo?: TruncationInfo; // Info about truncated files
+  codeHighlight?: boolean;       // Enable syntax highlighting (opt-in, requires lowlight)
+  renderBinaryPreview?: (ext: string, content: string | Uint8Array) => ReactNode | null; // Custom binary preview
   // Lifted edit state
   isEditing?: boolean;           // True when in edit mode
   editedContent?: string;        // Content being edited
@@ -513,12 +936,66 @@ interface ContentPaneProps {
 **Features:**
 
 - Breadcrumb navigation for file paths
-- Syntax highlighting for code files
+- Syntax highlighting for code files (opt-in via `codeHighlight` prop)
 - Markdown split-preview (editor + preview) for `.md` files
 - Optional frontmatter display
-- Edit mode for supported file types
+- Edit mode for supported file types (.md, .ts, .tsx, .js, .jsx, .py, .json, .css)
 - Truncation warning for large files
 - Lazy-loaded CodeMirror editor (bundle cost only on demand)
+- Custom binary/image preview via `renderBinaryPreview` render-prop
+
+**Code Highlighting (Optional)**:
+
+Enable syntax highlighting for non-markdown code blocks:
+
+```typescript
+import { ContentPane } from '@miethe/ui/content-viewer';
+
+<ContentPane
+  path="src/utils.ts"
+  content={tsCode}
+  codeHighlight={true}
+/>
+```
+
+Requires `lowlight` (v2 or v3) installed:
+
+```bash
+npm install lowlight
+```
+
+Import a highlight.js theme CSS:
+
+```typescript
+// In your app layout or CSS file
+import 'highlight.js/styles/github.css';  // Light mode
+// or
+import 'highlight.js/styles/github-dark.css';  // Dark mode
+```
+
+Without lowlight installed, code renders as plain text (no error).
+
+**Custom Binary Previews**:
+
+Provide a render-prop for custom binary/image/PDF previews:
+
+```typescript
+<ContentPane
+  path={path}
+  content={content}
+  renderBinaryPreview={(ext, content) => {
+    if (ext === 'pdf') {
+      return <PdfViewer content={content} />;  // Your custom viewer
+    }
+    if (ext === 'png' || ext === 'jpg') {
+      return <img src={`data:image/${ext};base64,${content}`} />;
+    }
+    return null;  // Fall through to text view
+  }}
+/>
+```
+
+Returning `null` from the render-prop falls through to the default text display.
 
 **Example:**
 
@@ -599,7 +1076,7 @@ interface SplitPreviewProps {
 
 ### MarkdownEditor
 
-CodeMirror-based markdown editor for editing `.md` files. Also lazy-loaded.
+CodeMirror-based markdown editor for editing `.md` files. Also lazy-loaded with reactive dark-mode support.
 
 **Props:**
 
@@ -611,6 +1088,78 @@ interface MarkdownEditorProps {
 }
 ```
 
+**Features:**
+
+- Live theme switching (tracks OS `prefers-color-scheme` changes at runtime)
+- Full markdown syntax support
+- Lazy-loaded for optimal bundle size
+
+### CodeEditor
+
+CodeMirror 6 editor for non-markdown code files (.ts, .tsx, .js, .jsx, .py, .json, .css). Exported from `@miethe/ui/editor`.
+
+**Import:**
+
+```typescript
+import { CodeEditor } from '@miethe/ui/editor';
+```
+
+**Props:**
+
+```typescript
+interface CodeEditorProps {
+  initialContent: string;                           // Initial code content
+  onChange: (content: string) => void;              // Called on every keystroke
+  readOnly?: boolean;                               // Disable editing (default: false)
+  language?: LanguageSupport;                       // CodeMirror language extension (optional)
+  className?: string;                               // Additional CSS classes
+}
+```
+
+**Features:**
+
+- Language detection by file extension
+- Syntax highlighting (via language extensions)
+- Reactive dark-mode support
+- Full keyboard navigation
+- Lazy-loaded via dynamic import
+
+**Example:**
+
+```typescript
+import { CodeEditor } from '@miethe/ui/editor';
+import { javascript } from '@codemirror/lang-javascript';
+import { python } from '@codemirror/lang-python';
+
+// With auto-detected language
+<CodeEditor
+  initialContent="const x = 42;"
+  onChange={(content) => console.log(content)}
+/>
+
+// With explicit language
+<CodeEditor
+  initialContent="def hello(): pass"
+  onChange={setCode}
+  language={python()}
+/>
+```
+
+**ContentPane Integration:**
+
+ContentPane automatically routes non-markdown editable files to CodeEditor:
+
+```typescript
+// ContentPane detects .ts/.tsx/.js/.jsx/.py/.json/.css files
+// and uses CodeEditor instead of MarkdownEditor when editing
+<ContentPane
+  path="src/utils.ts"
+  content={tsCode}
+  isEditing={true}
+  onEditChange={setCode}
+/>
+```
+
 ## Primitives API (`@miethe/ui/primitives`)
 
 Reusable UI primitives extracted from SkillMeat components. All primitives are production-ready, fully accessible, and compose with shadcn/ui components.
@@ -701,6 +1250,125 @@ interface ModalHeaderProps {
 - Consistent styling with SkillMeat modals
 - Accessible heading semantic
 
+### CreateEntityDialog
+
+Schema-driven creation dialog for entities. Dynamically renders form fields from an `EntityFormSchema` definition using react-hook-form for state management and per-field validation.
+
+**Import:**
+```typescript
+import { CreateEntityDialog } from '@miethe/ui/primitives';
+import type { EntityFormSchema, FieldDef } from '@miethe/ui/primitives';
+```
+
+**Modes:**
+
+1. **Simple** — Flat list of fields
+2. **Tabs** — Fields grouped into tabs
+3. **Composite** — Tabs + member picker + review step
+
+**Simple Mode Example:**
+
+```typescript
+<CreateEntityDialog
+  open={isOpen}
+  onOpenChange={setIsOpen}
+  title="Create Skill"
+  description="Add a new skill to your collection"
+  schema={{
+    mode: 'simple',
+    fields: [
+      { name: 'name', label: 'Name', type: 'text', required: true },
+      { name: 'description', label: 'Description', type: 'textarea' },
+      { name: 'tags', label: 'Tags', type: 'tags', options: [
+        { label: 'Important', value: 'important' },
+      ]},
+    ],
+    collection: { enabled: true, required: true, collapsible: true },
+  }}
+  collections={[
+    { id: 'col-1', name: 'My Collection' },
+  ]}
+  onSubmit={async (values) => {
+    await api.createSkill(values);
+  }}
+  submitLabel="Create"
+/>
+```
+
+**Tabs Mode Example:**
+
+```typescript
+<CreateEntityDialog
+  open={isOpen}
+  onOpenChange={setIsOpen}
+  title="Create Project"
+  schema={{
+    mode: 'tabs',
+    tabs: [
+      {
+        id: 'basic',
+        label: 'Basic Info',
+        fields: [
+          { name: 'name', label: 'Name', type: 'text', required: true },
+        ],
+      },
+      {
+        id: 'details',
+        label: 'Details',
+        fields: [
+          { name: 'description', label: 'Description', type: 'textarea' },
+        ],
+      },
+    ],
+    collection: { enabled: true },
+  }}
+  collections={collections}
+  onSubmit={async (values) => {
+    await api.createProject(values);
+  }}
+/>
+```
+
+**Composite Mode:**
+
+Composite mode adds a `members` picker and optional `renderReviewStep`. Selected member IDs are passed to `onMemberIdsChange`.
+
+```typescript
+schema={{
+  mode: 'composite',
+  tabs: [...],
+  members: {
+    entityType: 'skill',
+    label: 'Skills',
+    validateMin: 1,
+    validateMax: 10,
+  },
+  renderReviewStep: ({ values, memberIds }) => (
+    <div>Review: {values.name} with {memberIds.length} skills</div>
+  ),
+}}
+memberIds={selectedIds}
+onMemberIdsChange={setSelectedIds}
+```
+
+**CollectionPicker Sub-component:**
+
+The `CollectionPicker` component is embedded in simple/tabs/composite modes when `collection.enabled: true`.
+
+**Props:**
+```typescript
+interface CollectionPickerConfig {
+  enabled: boolean;           // Show picker
+  required?: boolean;         // Mandatory before submit
+  collapsible?: boolean;      // User can collapse/expand
+  defaultCollectionId?: string; // Pre-select a collection
+}
+```
+
+**Entity Type Registry:**
+
+Some entity types are disabled in the internal type registry (see `src/primitives/CreateEntityDialog.tsx`). Check runtime behavior or the source before creating forms for edge-case entity types.
+
 ### TabNavigation
 
 Horizontal tab list component for BaseArtifactModal and custom tab interfaces. Supports icons and keyboard navigation.
@@ -797,6 +1465,93 @@ import { LockIcon } from '@miethe/ui/primitives';
 </div>
 ```
 
+## Planning Primitives (`@miethe/ui/primitives`)
+
+Five status and metadata display primitives extracted from the CCDash Planning Control Plane (PCP-709). These are generic enough to be reused across any planning-adjacent feature.
+
+### StatusChip
+
+Five-variant status chip (neutral / ok / warn / error / info) as an inline-flex badge. Accepts an optional `tooltip` rendered as a `title` attribute.
+
+```typescript
+import { StatusChip } from '@miethe/ui/primitives';
+
+<StatusChip label="pending" variant="warn" tooltip="Waiting on upstream" />
+```
+
+**Variants:** `neutral` (slate) | `ok` (emerald) | `warn` (amber) | `error` (rose) | `info` (blue)
+
+### EffectiveStatusChips
+
+Renders a raw status chip plus an optional effective status chip when the two differ. The raw chip gains a hover tooltip showing provenance source and reason when `provenance` is supplied.
+
+```typescript
+import { EffectiveStatusChips } from '@miethe/ui/primitives';
+
+<EffectiveStatusChips
+  rawStatus="pending"
+  effectiveStatus="blocked"
+  isMismatch
+  provenance={{ source: 'derived', reason: 'Blocked by upstream task', evidence: [] }}
+/>
+```
+
+### MismatchBadge
+
+Amber mismatch indicator in two modes: compact inline chip or full banner with title, reason, and evidence label chips.
+
+```typescript
+import { MismatchBadge } from '@miethe/ui/primitives';
+
+// Compact inline chip (for card/list contexts)
+<MismatchBadge state="stale" reason="Status diverged from progress" compact />
+
+// Full banner (for detail headers)
+<MismatchBadge
+  state="mismatched"
+  reason="Progress says done but PRD is pending"
+  evidenceLabels={['PRD-outdated', 'progress-diverged']}
+/>
+```
+
+### BatchReadinessPill
+
+Wraps `StatusChip` to show batch readiness state (`ready` / `blocked` / `waiting` / `unknown`) with optional blocking node/task IDs displayed below the chip.
+
+```typescript
+import { BatchReadinessPill } from '@miethe/ui/primitives';
+
+<BatchReadinessPill
+  readinessState="blocked"
+  blockingNodeIds={['prd-auth', 'prd-onboarding']}
+  blockingTaskIds={['TASK-2.1']}
+/>
+```
+
+### PlanningNodeTypeIcon
+
+Maps a `PlanningNodeType` string to a lucide-react icon. Supports 7 node types: `design_spec`, `prd`, `implementation_plan`, `progress`, `context`, `tracker`, `report`. Accepts `size` (default 13) and `className` props.
+
+```typescript
+import { PlanningNodeTypeIcon } from '@miethe/ui/primitives';
+import type { PlanningNodeType } from '@miethe/ui/primitives';
+
+<PlanningNodeTypeIcon type="prd" size={16} className="text-blue-400" />
+```
+
+### Variant Helpers
+
+```typescript
+import { statusVariant, readinessVariant } from '@miethe/ui/primitives';
+import type { StatusChipVariant, ReadinessVariant } from '@miethe/ui/primitives';
+
+// Map any status string to a StatusChip variant
+const variant = statusVariant('in_progress'); // → 'ok'
+const readiness = readinessVariant('blocked'); // → 'error'
+```
+
+---
+
 ## Filters API (`@miethe/ui/filters`)
 
 Reusable filter components for building toolbar filter bars. All components are pure presentational — consumers provide data via props.
@@ -891,6 +1646,86 @@ import { SortDropdown } from '@miethe/ui/filters';
 
 Clicking an already-selected field toggles the order.
 
+### FilterBar & Filter Slot System
+
+Reusable filter bar with search, sort, view toggle, and pluggable slot registry. Renders a horizontal toolbar with four zones (left → right): search input, conditional filter slots, sort dropdown, and view toggle.
+
+**Basic Usage:**
+
+```tsx
+import { FilterBar } from '@miethe/ui/filters';
+
+<FilterBar
+  searchValue={searchValue}
+  onSearchChange={setSearchValue}
+  sortField="name"
+  sortOrder="asc"
+  onSortChange={(field, order) => { /* ... */ }}
+  view="grid"
+  onViewChange={(mode) => { /* ... */ }}
+  filterSlots={slots}
+  conditionContext={{ pageId: 'artifacts' }}
+/>
+```
+
+**Slot Registration Example:**
+
+```tsx
+import type { FilterSlotConfig } from '@miethe/ui/filters';
+
+const filterSlots: FilterSlotConfig[] = [
+  {
+    id: 'trust-filter',
+    label: 'Trust Level',
+    component: <TrustLevelSelect selected={trust} onChange={setTrust} />,
+    condition: (ctx) => ctx.pageId === 'marketplace-sources',
+  },
+  {
+    id: 'type-filter',
+    label: 'Type',
+    component: <TypeSelect selected={types} onChange={setTypes} />,
+  },
+];
+```
+
+**Interface Definitions:**
+
+```typescript
+export interface FilterSlotConditionContext {
+  pageId: string;                 // Stable identifier (e.g. "artifacts", "marketplace")
+  edition?: string;               // Backend edition: "local" or "enterprise"
+}
+
+export interface FilterSlotConfig {
+  id: string;                     // Unique slot identifier
+  label: string;                  // Human-readable label for accessibility
+  component: React.ReactNode;     // React node to render when slot is active
+  condition?: (ctx: FilterSlotConditionContext) => boolean;  // Optional visibility predicate
+}
+
+export interface FilterBarProps {
+  searchValue: string;
+  onSearchChange: (value: string) => void;
+  searchPlaceholder?: string;
+  searchAriaLabel?: string;
+  filterSlots?: FilterSlotConfig[];
+  conditionContext?: FilterSlotConditionContext;
+  sort?: FilterBarSortProps;
+  viewToggle?: {
+    value: 'grid' | 'list';
+    onChange: (mode: 'grid' | 'list') => void;
+    enabled?: boolean;
+  };
+  className?: string;
+}
+```
+
+**Accessibility:**
+
+The FilterBar renders a `role="search"` landmark region with a configurable `aria-label`. Slot authors should include `aria-label` on interactive elements (selects, popovers) to support screen readers. Condition predicates are evaluated synchronously at render time without side effects.
+
+**Source:** `skillmeat/web/packages/ui/src/filters/`
+
 ## Bulk Actions API (`@miethe/ui/bulk-actions`)
 
 Floating toolbar component for multi-select interfaces. Displays a bottom-fixed action bar with selection count and action buttons when items are selected.
@@ -1444,20 +2279,39 @@ The adapter encodes a composite key (sourceId + artifactPath) into a single stri
 
 ### Lazy-Loaded Editor Bundle
 
-The CodeMirror editor (used in `SplitPreview` and `MarkdownEditor`) is lazy-loaded and only fetched when needed:
+The CodeMirror editor (used in `SplitPreview`, `MarkdownEditor`, and `CodeEditor`) is lazy-loaded and only fetched when needed:
 
-- **Markdown files in edit mode**: Editor chunk downloaded
-- **Non-markdown files**: Editor never downloaded
+- **Markdown files in edit mode**: MarkdownEditor chunk downloaded
+- **Non-markdown files in edit mode** (.ts, .tsx, .js, .jsx, .py, .json, .css): CodeEditor chunk downloaded
 - **Read-only mode**: Editor chunk may still load for markdown files (preview uses a lighter markdown renderer)
 
 This significantly reduces the initial bundle size for consumers. If you're only using `FileTree` and `ContentPane` for viewing, you may never download the editor.
 
+### Optional Syntax Highlighting
+
+Syntax highlighting via `lowlight` is completely optional:
+
+- **ArticleViewer** `codeHighlight` prop: Defaults to `false`; dynamically imports lowlight (~15KB gzip) when enabled
+- **ContentPane** `codeHighlight` prop: Defaults to `false`; gracefully degrades to plain text if lowlight is not installed
+
+Both use **lowlight** (the same optional peer dependency) for a single, consistent highlighting engine across the package.
+
+Install lowlight only if you want to enable code highlighting:
+
+```bash
+npm install lowlight
+```
+
+Without lowlight, code renders as plain text with no error or warning.
+
 ### Component Structure
 
 - **`FileTree`** - ~8 KB gzipped (fully bundled, no lazy loading)
 - **`ContentPane`** - ~5 KB gzipped (fully bundled)
 - **`FrontmatterDisplay`** - ~2 KB gzipped (fully bundled)
 - **`SplitPreview` + `MarkdownEditor`** (lazy) - ~50 KB gzipped (on demand)
+- **`CodeEditor`** (lazy) - ~40 KB gzipped (on demand, only for editing non-markdown files)
+- **`lowlight`** (optional) - ~15 KB gzipped (only when syntax highlighting is enabled)
 
 ## Accessibility