@startsimpli/ui 0.4.52 → 0.4.53

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.52",
+  "version": "0.4.53",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -41,8 +41,8 @@
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@startsimpli/auth": "0.4.29",
-    "@startsimpli/api": "0.5.44"
+    "@startsimpli/api": "0.5.44",
+    "@startsimpli/auth": "0.4.29"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {

package/src/catalog/catalog.ts

@@ -181,6 +181,15 @@ export const UI_CATALOG: CatalogEntry[] = [
     dataNeeds: 'A type with long-text / structured (json) fields to edit (optionally a source-list field).',
     source: { export: 'DocumentEditor', from: '@startsimpli/ui/document-editor' },
   },
+  {
+    id: 'validation-checklist',
+    category: 'component',
+    title: 'Validation checklist',
+    description:
+      "A pass/warn/fail review panel for an AI-generated content record: renders the deterministic auto-checks (word-count bands, hype-word scan, approved-source allow-list) as a green/amber/red checklist, surfaces the buried AI judge verdict (per-dimension scores + an expandable issues list), and supports a reasoned reviewer override. Its runContentChecks util RE-RUNS the deterministic checks over the reviewer's *edited* fields, so validation tracks the current draft, not the stale original — pair it with the document-editor to review-and-accept a content draft.",
+    dataNeeds: 'A content type carrying a judge verdict + auto-checks (and the editable content fields to recheck).',
+    source: { export: 'ValidationChecklist', from: '@startsimpli/ui' },
+  },
   {
     id: 'chat',
     category: 'component',

package/src/components/index.ts

@@ -168,3 +168,8 @@ export type {
 
 // Record detail read-view
 export * from './record-detail'
+
+// Content validation toolkit (768w.16.10.1) — ValidationChecklist + the pure
+// runContentChecks recompute util. Light (React + lucide only), so it ships on
+// the main barrel rather than a subpath.
+export * from './validation'

package/src/components/validation/ValidationChecklist.tsx

@@ -0,0 +1,270 @@
+import * as React from 'react';
+import {
+  CheckCircle2,
+  AlertTriangle,
+  XCircle,
+  ChevronDown,
+  ChevronRight,
+  ShieldCheck,
+  ShieldAlert,
+} from 'lucide-react';
+import { cn } from '../../lib/utils';
+import { overallStatus, type CheckStatus, type ContentCheck } from './checks';
+
+/** Redundant (color + icon + label) tone per check status — never color alone. */
+const CHECK_TONE: Record<CheckStatus, { label: string; dot: string; text: string; softBg: string; Icon: typeof CheckCircle2 }> = {
+  pass: { label: 'Passing', dot: 'bg-emerald-500', text: 'text-emerald-700', softBg: 'bg-emerald-50', Icon: CheckCircle2 },
+  warn: { label: 'Warnings', dot: 'bg-amber-500', text: 'text-amber-700', softBg: 'bg-amber-50', Icon: AlertTriangle },
+  fail: { label: 'Failing', dot: 'bg-red-500', text: 'text-red-700', softBg: 'bg-red-50', Icon: XCircle },
+};
+
+/** One issue the AI judge raised against a guardrail. */
+export interface JudgeIssue {
+  guardrail?: string;
+  severity?: string;
+  problem?: string;
+  fix?: string;
+}
+
+/** The AI judge's output stored alongside the content record. */
+export interface JudgeVerdict {
+  /** Overall verdict word (e.g. "approve", "revise", "reject"). */
+  verdict?: string;
+  /** Per-dimension scores, keyed by dimension name. */
+  scores?: Record<string, unknown>;
+  /** Specific problems the judge flagged. */
+  issues?: JudgeIssue[];
+  /** One-line prose summary. */
+  summary?: string;
+}
+
+/** Reviewer's manual override of the automated checks. */
+export interface ValidationOverride {
+  overridden: boolean;
+  reason?: string;
+}
+
+export interface ValidationChecklistProps {
+  /** The (recomputed) deterministic checks to render. */
+  checks: ContentCheck[];
+  /** The AI judge output — renders a verdict badge, scores, and issues. */
+  judgeVerdict?: JudgeVerdict;
+  /** Current override state. When set, the overall pill reflects it. */
+  override?: ValidationOverride;
+  /** Provide to make the override affordance interactive. Omit → read-only. */
+  onOverride?: (next: ValidationOverride) => void;
+  title?: string;
+  className?: string;
+}
+
+/** A tone pill naming the roll-up state. */
+function StatusPill({ status, label }: { status: CheckStatus; label?: string }) {
+  const tone = CHECK_TONE[status];
+  const Icon = tone.Icon;
+  return (
+    <span className={cn('inline-flex items-center gap-1.5 rounded-full px-2.5 py-0.5 text-xs font-medium', tone.softBg, tone.text)}>
+      <Icon className="w-3.5 h-3.5" aria-hidden="true" />
+      {label ?? tone.label}
+    </span>
+  );
+}
+
+/** Colour a judge verdict word without needing to know the exact vocabulary. */
+function verdictStatus(verdict?: string): CheckStatus {
+  const v = (verdict ?? '').toLowerCase();
+  if (/pass|approve|accept|ok|good/.test(v)) return 'pass';
+  if (/fail|reject|block|deny|bad/.test(v)) return 'fail';
+  return 'warn';
+}
+
+/**
+ * Presentational, bring-your-own-data validation panel (768w.16.10.1).
+ *
+ * Surfaces the buried machine review of an AI-generated content record as a
+ * scannable pass/warn/fail checklist plus the AI judge's verdict — so a Foundry
+ * tenant can accept/reject in one glance. Stateless except for local UI toggles
+ * (expand issues, edit override reason); the app owns the data and persistence.
+ */
+export function ValidationChecklist({
+  checks,
+  judgeVerdict,
+  override,
+  onOverride,
+  title = 'Validation',
+  className,
+}: ValidationChecklistProps) {
+  const overall = overallStatus(checks);
+  const [issuesOpen, setIssuesOpen] = React.useState(false);
+  const [overrideOpen, setOverrideOpen] = React.useState(false);
+  const [reason, setReason] = React.useState(override?.reason ?? '');
+
+  const counts = React.useMemo(
+    () => ({
+      pass: checks.filter((c) => c.status === 'pass').length,
+      warn: checks.filter((c) => c.status === 'warn').length,
+      fail: checks.filter((c) => c.status === 'fail').length,
+    }),
+    [checks],
+  );
+
+  const issues = judgeVerdict?.issues ?? [];
+  const scoreEntries = judgeVerdict?.scores ? Object.entries(judgeVerdict.scores) : [];
+
+  return (
+    <div className={cn('rounded-xl border bg-card text-card-foreground shadow p-5 space-y-4', className)}>
+      {/* Header: title + overall pill */}
+      <div className="flex items-center justify-between gap-3">
+        <div className="flex items-center gap-2 min-w-0">
+          <ShieldCheck className="w-4 h-4 text-gray-400 flex-shrink-0" aria-hidden="true" />
+          <h3 className="text-sm font-semibold text-gray-900 truncate">{title}</h3>
+        </div>
+        <div className="flex items-center gap-2 flex-shrink-0">
+          {override?.overridden && (
+            <span className="inline-flex items-center gap-1 rounded-full bg-indigo-50 px-2 py-0.5 text-xs font-medium text-indigo-700">
+              <ShieldAlert className="w-3 h-3" aria-hidden="true" />
+              Overridden
+            </span>
+          )}
+          <StatusPill status={override?.overridden ? 'pass' : overall} label={`${counts.pass}/${checks.length} passing`} />
+        </div>
+      </div>
+
+      {/* Checks list */}
+      {checks.length === 0 ? (
+        <p className="text-sm text-gray-500 py-2 text-center">No checks to show.</p>
+      ) : (
+        <ul className="space-y-1.5">
+          {checks.map((check) => {
+            const tone = CHECK_TONE[check.status];
+            const Icon = tone.Icon;
+            return (
+              <li key={check.id} className="flex items-center gap-2.5 text-sm">
+                <span className={cn('inline-block w-2 h-2 rounded-full flex-shrink-0', tone.dot)} aria-hidden="true" />
+                <Icon className={cn('w-4 h-4 flex-shrink-0', tone.text)} aria-hidden="true" />
+                <span className="text-gray-900">{check.label}</span>
+                {check.detail && <span className="text-gray-500 truncate">— {check.detail}</span>}
+                <span className="sr-only">{tone.label}</span>
+              </li>
+            );
+          })}
+        </ul>
+      )}
+
+      {/* AI judge section */}
+      {judgeVerdict && (
+        <div className="rounded-lg border bg-gray-50/60 p-3 space-y-3">
+          <div className="flex items-center justify-between gap-3">
+            <span className="text-xs font-semibold uppercase tracking-wide text-gray-500">AI judge</span>
+            {judgeVerdict.verdict && <StatusPill status={verdictStatus(judgeVerdict.verdict)} label={judgeVerdict.verdict} />}
+          </div>
+
+          {judgeVerdict.summary && <p className="text-sm text-gray-700">{judgeVerdict.summary}</p>}
+
+          {scoreEntries.length > 0 && (
+            <dl className="flex flex-wrap gap-2">
+              {scoreEntries.map(([dim, val]) => (
+                <div key={dim} className="rounded-md bg-white border px-2 py-1 text-xs">
+                  <dt className="text-gray-500">{dim}</dt>
+                  <dd className="font-medium text-gray-900">{String(val)}</dd>
+                </div>
+              ))}
+            </dl>
+          )}
+
+          {issues.length > 0 && (
+            <div>
+              <button
+                type="button"
+                onClick={() => setIssuesOpen((o) => !o)}
+                className="flex items-center gap-1 text-xs font-medium text-gray-600 hover:text-gray-900"
+                aria-expanded={issuesOpen}
+              >
+                {issuesOpen ? <ChevronDown className="w-3.5 h-3.5" aria-hidden="true" /> : <ChevronRight className="w-3.5 h-3.5" aria-hidden="true" />}
+                {issues.length} issue{issues.length === 1 ? '' : 's'}
+              </button>
+              {issuesOpen && (
+                <ul className="mt-2 space-y-2">
+                  {issues.map((issue, i) => (
+                    <li key={i} className="rounded-md border bg-white p-2 text-xs space-y-1">
+                      <div className="flex items-center gap-2">
+                        {issue.guardrail && <span className="font-medium text-gray-900">{issue.guardrail}</span>}
+                        {issue.severity && (
+                          <span className="rounded bg-gray-100 px-1.5 py-0.5 text-[10px] uppercase tracking-wide text-gray-600">{issue.severity}</span>
+                        )}
+                      </div>
+                      {issue.problem && <p className="text-gray-700">{issue.problem}</p>}
+                      {issue.fix && <p className="text-gray-500">Fix: {issue.fix}</p>}
+                    </li>
+                  ))}
+                </ul>
+              )}
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Override affordance — interactive only when onOverride is provided */}
+      {onOverride && (
+        <div className="border-t pt-3">
+          {override?.overridden ? (
+            <div className="flex items-start justify-between gap-3 text-sm">
+              <div className="min-w-0">
+                <p className="font-medium text-gray-900">Checks overridden</p>
+                {override.reason && <p className="text-gray-500 break-words">{override.reason}</p>}
+              </div>
+              <button
+                type="button"
+                onClick={() => onOverride({ overridden: false })}
+                className="text-xs font-medium text-gray-500 hover:text-gray-900 flex-shrink-0"
+              >
+                Clear
+              </button>
+            </div>
+          ) : overrideOpen ? (
+            <div className="space-y-2">
+              <label className="text-xs font-medium text-gray-600" htmlFor="validation-override-reason">
+                Reason for overriding checks
+              </label>
+              <textarea
+                id="validation-override-reason"
+                value={reason}
+                onChange={(e) => setReason(e.target.value)}
+                rows={2}
+                className="w-full rounded-md border px-2 py-1 text-sm"
+                placeholder="Why is this content acceptable despite the failing checks?"
+              />
+              <div className="flex items-center gap-2">
+                <button
+                  type="button"
+                  disabled={reason.trim().length === 0}
+                  onClick={() => {
+                    onOverride({ overridden: true, reason: reason.trim() });
+                    setOverrideOpen(false);
+                  }}
+                  className="rounded-md bg-gray-900 px-2.5 py-1 text-xs font-medium text-white disabled:opacity-40"
+                >
+                  Override
+                </button>
+                <button
+                  type="button"
+                  onClick={() => setOverrideOpen(false)}
+                  className="text-xs font-medium text-gray-500 hover:text-gray-900"
+                >
+                  Cancel
+                </button>
+              </div>
+            </div>
+          ) : (
+            <button
+              type="button"
+              onClick={() => setOverrideOpen(true)}
+              className="text-xs font-medium text-gray-600 hover:text-gray-900"
+            >
+              Override checks (with reason)
+            </button>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/validation/__tests__/ValidationChecklist.test.tsx

@@ -0,0 +1,84 @@
+import * as React from 'react';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { ValidationChecklist } from '../ValidationChecklist';
+import type { ContentCheck } from '../checks';
+
+const checks: ContentCheck[] = [
+  { id: 'blog-words', label: 'Blog word count', status: 'pass', detail: '450 words' },
+  { id: 'linkedin-words', label: 'LinkedIn word count', status: 'warn', detail: '100 words' },
+  { id: 'no-hype', label: 'No hype words', status: 'fail', detail: 'revolutionary' },
+];
+
+describe('ValidationChecklist', () => {
+  it('renders every check with its label and detail', () => {
+    render(<ValidationChecklist checks={checks} />);
+    expect(screen.getByText('Blog word count')).toBeInTheDocument();
+    expect(screen.getByText('— 450 words')).toBeInTheDocument();
+    expect(screen.getByText('No hype words')).toBeInTheDocument();
+  });
+
+  it('summarises passing count in the overall pill', () => {
+    render(<ValidationChecklist checks={checks} />);
+    expect(screen.getByText('1/3 passing')).toBeInTheDocument();
+  });
+
+  it('renders the judge verdict, scores, and expandable issues', () => {
+    render(
+      <ValidationChecklist
+        checks={checks}
+        judgeVerdict={{
+          verdict: 'revise',
+          summary: 'Reads well but sourcing is thin.',
+          scores: { clarity: 8, accuracy: 6 },
+          issues: [{ guardrail: 'sourcing', severity: 'high', problem: 'Unsupported claim', fix: 'Add a citation' }],
+        }}
+      />,
+    );
+    expect(screen.getByText('AI judge')).toBeInTheDocument();
+    expect(screen.getByText('revise')).toBeInTheDocument();
+    expect(screen.getByText('Reads well but sourcing is thin.')).toBeInTheDocument();
+    expect(screen.getByText('clarity')).toBeInTheDocument();
+
+    // issues collapsed by default, expand on click
+    expect(screen.queryByText('Unsupported claim')).not.toBeInTheDocument();
+    fireEvent.click(screen.getByText('1 issue'));
+    expect(screen.getByText('Unsupported claim')).toBeInTheDocument();
+    expect(screen.getByText('Fix: Add a citation')).toBeInTheDocument();
+  });
+
+  it('is read-only when no onOverride is provided', () => {
+    render(<ValidationChecklist checks={checks} />);
+    expect(screen.queryByText('Override checks (with reason)')).not.toBeInTheDocument();
+  });
+
+  it('drives the override flow when onOverride is provided', () => {
+    const onOverride = jest.fn();
+    render(<ValidationChecklist checks={checks} onOverride={onOverride} />);
+
+    fireEvent.click(screen.getByText('Override checks (with reason)'));
+    const textarea = screen.getByLabelText('Reason for overriding checks');
+    // empty reason keeps the confirm disabled
+    expect(screen.getByRole('button', { name: 'Override' })).toBeDisabled();
+
+    fireEvent.change(textarea, { target: { value: 'Client approved the exception.' } });
+    fireEvent.click(screen.getByRole('button', { name: 'Override' }));
+    expect(onOverride).toHaveBeenCalledWith({ overridden: true, reason: 'Client approved the exception.' });
+  });
+
+  it('shows an overridden banner and can clear the override', () => {
+    const onOverride = jest.fn();
+    render(
+      <ValidationChecklist
+        checks={checks}
+        override={{ overridden: true, reason: 'Approved by editor.' }}
+        onOverride={onOverride}
+      />,
+    );
+    expect(screen.getByText('Checks overridden')).toBeInTheDocument();
+    expect(screen.getByText('Approved by editor.')).toBeInTheDocument();
+    expect(screen.getByText('Overridden')).toBeInTheDocument();
+
+    fireEvent.click(screen.getByText('Clear'));
+    expect(onOverride).toHaveBeenCalledWith({ overridden: false });
+  });
+});

package/src/components/validation/__tests__/checks.test.ts

@@ -0,0 +1,191 @@
+import {
+  runContentChecks,
+  overallStatus,
+  wordCount,
+  tagCount,
+  extractUrls,
+  hostOf,
+  DEFAULT_HYPE_WORDS,
+  type ContentCheck,
+} from '../checks';
+
+/** Build a string of exactly `n` whitespace-delimited words. */
+const words = (n: number) => Array.from({ length: n }, (_, i) => `w${i}`).join(' ');
+const find = (checks: ContentCheck[], id: string) => checks.find((c) => c.id === id);
+
+describe('word/tag helpers', () => {
+  it('wordCount handles empty, whitespace, and normal input', () => {
+    expect(wordCount(undefined)).toBe(0);
+    expect(wordCount('')).toBe(0);
+    expect(wordCount('   ')).toBe(0);
+    expect(wordCount('one two   three')).toBe(3);
+    expect(wordCount(words(462))).toBe(462);
+  });
+
+  it('tagCount splits on commas and ignores empties', () => {
+    expect(tagCount(undefined)).toBe(0);
+    expect(tagCount('')).toBe(0);
+    expect(tagCount('a, b, c')).toBe(3);
+    expect(tagCount('a,,b, ,c,')).toBe(3);
+  });
+});
+
+describe('runContentChecks — field presence', () => {
+  it('emits no checks for an empty fields object (no approvedHosts)', () => {
+    expect(runContentChecks({})).toEqual([]);
+  });
+
+  it('only emits a check for a field that is present', () => {
+    const checks = runContentChecks({ blog: words(450) });
+    expect(checks.map((c) => c.id).sort()).toEqual(['blog-words', 'no-hype']);
+  });
+});
+
+describe('word-count bands', () => {
+  it('blog: in-band 400–500 passes, outside warns, with a "N words" detail', () => {
+    expect(find(runContentChecks({ blog: words(450) }), 'blog-words')).toMatchObject({ status: 'pass', detail: '450 words' });
+    expect(find(runContentChecks({ blog: words(300) }), 'blog-words')).toMatchObject({ status: 'warn', detail: '300 words' });
+    expect(find(runContentChecks({ blog: words(600) }), 'blog-words')!.status).toBe('warn');
+    // inclusive edges
+    expect(find(runContentChecks({ blog: words(400) }), 'blog-words')!.status).toBe('pass');
+    expect(find(runContentChecks({ blog: words(500) }), 'blog-words')!.status).toBe('pass');
+  });
+
+  it('linkedin: default band 150–250', () => {
+    expect(find(runContentChecks({ linkedin: words(200) }), 'linkedin-words')!.status).toBe('pass');
+    expect(find(runContentChecks({ linkedin: words(100) }), 'linkedin-words')!.status).toBe('warn');
+  });
+
+  it('headline: default band 8–12 words', () => {
+    expect(find(runContentChecks({ headline: words(10) }), 'headline-words')!.status).toBe('pass');
+    expect(find(runContentChecks({ headline: words(5) }), 'headline-words')!.status).toBe('warn');
+    expect(find(runContentChecks({ headline: words(20) }), 'headline-words')!.status).toBe('warn');
+  });
+
+  it('honours a custom band override', () => {
+    const c = find(runContentChecks({ blog: words(100) }, { blogWords: [50, 150] }), 'blog-words');
+    expect(c!.status).toBe('pass');
+  });
+});
+
+describe('tag count and meta length', () => {
+  it('tags: default band 4–6', () => {
+    expect(find(runContentChecks({ tags: 'a,b,c,d,e' }), 'tags-count')).toMatchObject({ status: 'pass', detail: '5 tags' });
+    expect(find(runContentChecks({ tags: 'a,b' }), 'tags-count')!.status).toBe('warn');
+    expect(find(runContentChecks({ tags: 'a,b,c,d,e,f,g' }), 'tags-count')!.status).toBe('warn');
+  });
+
+  it('meta description: default band 150–160 chars', () => {
+    const inBand = 'x'.repeat(155);
+    const tooShort = 'x'.repeat(120);
+    expect(find(runContentChecks({ metaDescription: inBand }), 'meta-length')).toMatchObject({ status: 'pass', detail: '155 chars' });
+    expect(find(runContentChecks({ metaDescription: tooShort }), 'meta-length')!.status).toBe('warn');
+  });
+});
+
+describe('[link] placeholder', () => {
+  it('passes when present, warns when absent', () => {
+    expect(find(runContentChecks({ linkedin: 'read more [link] now' }), 'link-placeholder')!.status).toBe('pass');
+    expect(find(runContentChecks({ linkedin: 'no placeholder here' }), 'link-placeholder')).toMatchObject({
+      status: 'warn',
+      detail: 'no [link] found',
+    });
+  });
+
+  it('is skipped when requireLink is false', () => {
+    expect(find(runContentChecks({ linkedin: 'no placeholder' }, { requireLink: false }), 'link-placeholder')).toBeUndefined();
+  });
+});
+
+describe('no-hype', () => {
+  it('fails when a hype word appears (case-insensitive) across headline/blog/linkedin', () => {
+    const c = find(runContentChecks({ headline: 'A REVOLUTIONARY launch', blog: words(450) }), 'no-hype');
+    expect(c!.status).toBe('fail');
+    expect(c!.detail).toContain('revolutionary');
+  });
+
+  it('detects multi-word and hyphenated hype phrases', () => {
+    expect(find(runContentChecks({ blog: 'the best-in-class widget' }), 'no-hype')!.status).toBe('fail');
+    expect(find(runContentChecks({ blog: 'the most attractive option' }), 'no-hype')!.status).toBe('fail');
+  });
+
+  it('passes clean prose', () => {
+    expect(find(runContentChecks({ blog: 'a measured, factual paragraph about widgets' }), 'no-hype')!.status).toBe('pass');
+  });
+
+  it('honours a custom hype list', () => {
+    expect(find(runContentChecks({ blog: 'totally banana content' }, { hypeWords: ['banana'] }), 'no-hype')!.status).toBe('fail');
+    // default hype words no longer apply when overridden
+    expect(find(runContentChecks({ blog: 'revolutionary content' }, { hypeWords: ['banana'] }), 'no-hype')!.status).toBe('pass');
+  });
+
+  it('ships a non-empty default hype list', () => {
+    expect(DEFAULT_HYPE_WORDS.length).toBeGreaterThan(5);
+    expect(DEFAULT_HYPE_WORDS).toContain('game-changing');
+  });
+});
+
+describe('approved sources', () => {
+  const approvedHosts = ['example.com', 'gov.uk'];
+
+  it('is skipped entirely when approvedHosts is omitted', () => {
+    expect(find(runContentChecks({ sources: 'https://example.com/a' }), 'approved-sources')).toBeUndefined();
+  });
+
+  it('passes when every host is approved (www. stripped)', () => {
+    const c = find(runContentChecks({ sources: 'https://www.example.com/a https://gov.uk/b' }, { approvedHosts }), 'approved-sources');
+    expect(c!.status).toBe('pass');
+  });
+
+  it('fails when any host is not on the allow-list', () => {
+    const c = find(runContentChecks({ sources: 'https://example.com/a https://sketchy.io/x' }, { approvedHosts }), 'approved-sources');
+    expect(c!.status).toBe('fail');
+    expect(c!.detail).toContain('sketchy.io');
+    expect(c!.detail).not.toContain('example.com');
+  });
+
+  it('fails forum/social hosts even if listed', () => {
+    const c = find(
+      runContentChecks({ sources: 'https://reddit.com/r/x' }, { approvedHosts: ['reddit.com'] }),
+      'approved-sources',
+    );
+    expect(c!.status).toBe('fail');
+    expect(c!.detail).toContain('reddit.com');
+  });
+
+  it('warns when there is no URL to check', () => {
+    expect(find(runContentChecks({ sources: 'no links here' }, { approvedHosts }), 'approved-sources')).toMatchObject({
+      status: 'warn',
+      detail: 'no sources to check',
+    });
+    // sources field absent but allow-list present → still a warn (nothing to check)
+    expect(find(runContentChecks({}, { approvedHosts }), 'approved-sources')!.status).toBe('warn');
+  });
+
+  it('extractUrls + hostOf normalise correctly', () => {
+    expect(extractUrls('see https://a.com/x and http://b.org')).toEqual(['https://a.com/x', 'http://b.org']);
+    expect(extractUrls('none')).toEqual([]);
+    expect(hostOf('https://www.Example.com/path')).toBe('example.com');
+    expect(hostOf('not a url')).toBe('');
+  });
+});
+
+describe('overallStatus', () => {
+  const mk = (status: ContentCheck['status']): ContentCheck => ({ id: status, label: status, status });
+
+  it('fail beats warn beats pass; empty is pass', () => {
+    expect(overallStatus([])).toBe('pass');
+    expect(overallStatus([mk('pass'), mk('pass')])).toBe('pass');
+    expect(overallStatus([mk('pass'), mk('warn')])).toBe('warn');
+    expect(overallStatus([mk('warn'), mk('fail')])).toBe('fail');
+  });
+
+  it('rolls up a realistic mixed run', () => {
+    const checks = runContentChecks(
+      { blog: words(450), linkedin: 'a revolutionary post [link]', tags: 'a,b,c,d,e' },
+      {},
+    );
+    // blog pass, linkedin word-count warn (2 words), link pass, hype fail, tags pass
+    expect(overallStatus(checks)).toBe('fail');
+  });
+});

package/src/components/validation/checks.ts

@@ -0,0 +1,240 @@
+/**
+ * Deterministic content checks (768w.16.10.1) — pure + framework-free.
+ *
+ * A Foundry tenant reviews AI-generated content before accepting it. The n8n
+ * pipeline that produced the content also ran a set of deterministic
+ * auto-checks (word-count bands, hype-word scan, approved-source allow-list)
+ * and stored their result on the record. This module re-implements the SAME
+ * logic so the client can RECOMPUTE the checks against the reviewer's *edited*
+ * content — validation reflects the current draft, not the stale original.
+ *
+ * Keep this identical to the n8n judge's deterministic logic so client +
+ * pipeline always agree. No React, no DOM — importable from a Node/LLM route.
+ */
+
+/** A single check's outcome. Green / amber / red, encoded redundantly in the UI. */
+export type CheckStatus = 'pass' | 'warn' | 'fail';
+
+/** One deterministic check result. */
+export interface ContentCheck {
+  /** Stable id for the check (e.g. `blog-words`, `no-hype`). */
+  id: string;
+  /** Human label shown in the checklist. */
+  label: string;
+  status: CheckStatus;
+  /** Short human explanation (e.g. "462 words", "unapproved: reddit.com"). */
+  detail?: string;
+}
+
+/**
+ * The content fields a record can expose for checking. All optional — a check
+ * is only emitted for a field that is present (an app without a `blog` field
+ * never gets a spurious blog check). `tags` and `sources` are flat strings
+ * (comma-separated tags, whitespace/URL-bearing sources) to match how the
+ * pipeline stores them.
+ */
+export interface ContentFields {
+  blog?: string;
+  linkedin?: string;
+  headline?: string;
+  tags?: string;
+  metaDescription?: string;
+  sources?: string;
+}
+
+/** An inclusive `[min, max]` band. */
+export type Band = [min: number, max: number];
+
+/**
+ * Tunable thresholds. Everything has a sensible default EXCEPT `approvedHosts`:
+ * the source allow-list is deliberately app-injected (no hardcoded list here),
+ * so the approved-sources check is skipped entirely when it is omitted.
+ */
+export interface ContentChecksConfig {
+  /** Blog word-count band (default 400–500). */
+  blogWords?: Band;
+  /** LinkedIn word-count band (default 150–250). */
+  linkedinWords?: Band;
+  /** Headline word-count band (default 8–12). */
+  headlineWords?: Band;
+  /** Tag-count band (default 4–6). */
+  tagsCount?: Band;
+  /** Meta-description character band (default 150–160). */
+  metaChars?: Band;
+  /** Require a `[link]` placeholder in the LinkedIn post (default true). */
+  requireLink?: boolean;
+  /** Override the hype-word blocklist. */
+  hypeWords?: string[];
+  /** Approved source hosts (no `www.`). REQUIRED to run the source check. */
+  approvedHosts?: string[];
+}
+
+/**
+ * The default hype/marketing-fluff blocklist. If ANY appears in the content the
+ * hype check FAILS. Matches the n8n judge's list — keep the two in sync.
+ */
+export const DEFAULT_HYPE_WORDS: string[] = [
+  'game-changing',
+  'gamechanging',
+  'revolutionary',
+  'world-leading',
+  'world leading',
+  'unprecedented',
+  'undisputed',
+  'transformational',
+  'groundbreaking',
+  'ground-breaking',
+  'best-in-class',
+  'unmatched',
+  'unrivalled',
+  'unrivaled',
+  'on earth',
+  'most attractive',
+];
+
+/** Forum / social hosts that are never an acceptable source, allow-list or not. */
+const FORUM_SOCIAL = /reddit|quora|facebook|twitter|forum/i;
+
+const DEFAULTS = {
+  blogWords: [400, 500] as Band,
+  linkedinWords: [150, 250] as Band,
+  headlineWords: [8, 12] as Band,
+  tagsCount: [4, 6] as Band,
+  metaChars: [150, 160] as Band,
+};
+
+/** Count words in a string — whitespace-delimited, empty → 0. */
+export function wordCount(text: string | null | undefined): number {
+  if (!text) return 0;
+  return text.trim().split(/\s+/).filter(Boolean).length;
+}
+
+/** Count comma-separated tags in a flat string, ignoring empties. */
+export function tagCount(tags: string | null | undefined): number {
+  if (!tags) return 0;
+  return tags
+    .split(',')
+    .map((t) => t.trim())
+    .filter(Boolean).length;
+}
+
+/** pass when `n` is inside the inclusive band, else warn. */
+function bandStatus(n: number, [min, max]: Band): CheckStatus {
+  return n >= min && n <= max ? 'pass' : 'warn';
+}
+
+/** Pull http(s) URLs out of a free-text sources string. */
+export function extractUrls(text: string | null | undefined): string[] {
+  if (!text) return [];
+  return text.match(/https?:\/\/[^\s"'<>)\]]+/gi) ?? [];
+}
+
+/** Normalise a URL to its bare host (lowercased, `www.` stripped). '' if unparseable. */
+export function hostOf(url: string): string {
+  try {
+    return new URL(url).hostname.toLowerCase().replace(/^www\./, '');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Recompute every deterministic content check over `fields`. Pure. A check is
+ * emitted only when its underlying field is present; the approved-sources check
+ * is emitted only when `config.approvedHosts` is supplied.
+ */
+export function runContentChecks(fields: ContentFields, config: ContentChecksConfig = {}): ContentCheck[] {
+  const checks: ContentCheck[] = [];
+  const {
+    blogWords = DEFAULTS.blogWords,
+    linkedinWords = DEFAULTS.linkedinWords,
+    headlineWords = DEFAULTS.headlineWords,
+    tagsCount = DEFAULTS.tagsCount,
+    metaChars = DEFAULTS.metaChars,
+    requireLink = true,
+    hypeWords = DEFAULT_HYPE_WORDS,
+    approvedHosts,
+  } = config;
+
+  // Word-count bands.
+  if (fields.headline !== undefined) {
+    const n = wordCount(fields.headline);
+    checks.push({ id: 'headline-words', label: 'Headline length', status: bandStatus(n, headlineWords), detail: `${n} words` });
+  }
+  if (fields.blog !== undefined) {
+    const n = wordCount(fields.blog);
+    checks.push({ id: 'blog-words', label: 'Blog word count', status: bandStatus(n, blogWords), detail: `${n} words` });
+  }
+  if (fields.linkedin !== undefined) {
+    const n = wordCount(fields.linkedin);
+    checks.push({ id: 'linkedin-words', label: 'LinkedIn word count', status: bandStatus(n, linkedinWords), detail: `${n} words` });
+  }
+
+  // Tag count.
+  if (fields.tags !== undefined) {
+    const n = tagCount(fields.tags);
+    checks.push({ id: 'tags-count', label: 'Tag count', status: bandStatus(n, tagsCount), detail: `${n} tags` });
+  }
+
+  // Meta description length (characters).
+  if (fields.metaDescription !== undefined) {
+    const len = fields.metaDescription.trim().length;
+    checks.push({ id: 'meta-length', label: 'Meta description length', status: bandStatus(len, metaChars), detail: `${len} chars` });
+  }
+
+  // `[link]` placeholder present in the LinkedIn post.
+  if (requireLink && fields.linkedin !== undefined) {
+    const has = fields.linkedin.includes('[link]');
+    checks.push({
+      id: 'link-placeholder',
+      label: '[link] placeholder in LinkedIn',
+      status: has ? 'pass' : 'warn',
+      detail: has ? undefined : 'no [link] found',
+    });
+  }
+
+  // No hype words — scan headline + blog + linkedin, lowercased.
+  const hasProse = fields.headline !== undefined || fields.blog !== undefined || fields.linkedin !== undefined;
+  if (hasProse) {
+    const haystack = [fields.headline, fields.blog, fields.linkedin]
+      .filter((s): s is string => typeof s === 'string')
+      .join('\n')
+      .toLowerCase();
+    const found = hypeWords.filter((w) => haystack.includes(w.toLowerCase()));
+    checks.push({
+      id: 'no-hype',
+      label: 'No hype words',
+      status: found.length > 0 ? 'fail' : 'pass',
+      detail: found.length > 0 ? found.join(', ') : undefined,
+    });
+  }
+
+  // Approved sources — only when the app supplied an allow-list.
+  if (approvedHosts !== undefined) {
+    const approved = new Set(approvedHosts.map((h) => h.toLowerCase().replace(/^www\./, '')));
+    const hosts = extractUrls(fields.sources).map(hostOf).filter(Boolean);
+    if (hosts.length === 0) {
+      checks.push({ id: 'approved-sources', label: 'Approved sources', status: 'warn', detail: 'no sources to check' });
+    } else {
+      const bad = Array.from(new Set(hosts.filter((h) => !approved.has(h) || FORUM_SOCIAL.test(h))));
+      checks.push({
+        id: 'approved-sources',
+        label: 'Approved sources',
+        status: bad.length > 0 ? 'fail' : 'pass',
+        detail: bad.length > 0 ? `unapproved: ${bad.join(', ')}` : `${hosts.length} source${hosts.length === 1 ? '' : 's'} ok`,
+      });
+    }
+  }
+
+  return checks;
+}
+
+/**
+ * Roll a list of checks up to one status: fail if any fails, else warn if any
+ * warns, else pass (empty → pass).
+ */
+export function overallStatus(checks: ContentCheck[]): CheckStatus {
+  if (checks.some((c) => c.status === 'fail')) return 'fail';
+  if (checks.some((c) => c.status === 'warn')) return 'warn';
+  return 'pass';
+}

package/src/components/validation/index.ts

@@ -0,0 +1,36 @@
+/**
+ * @startsimpli/ui validation toolkit (768w.16.10.1).
+ *
+ * Surfaces a Foundry tenant's machine review of AI-generated content — the AI
+ * judge verdict plus deterministic auto-checks — as a pass/warn/fail checklist,
+ * and RECOMPUTES the deterministic checks over the reviewer's *edited* content
+ * (so validation tracks the current draft, not the stale original).
+ *
+ * `checks.ts` is pure + framework-free (importable in a Node/LLM/n8n context);
+ * `ValidationChecklist` is presentational + BYO-data. Light-weight (React +
+ * lucide only), so it rides the main components barrel like the health blocks —
+ * no dedicated subpath (unlike document-editor, which is subpathed only because
+ * it drags react-markdown).
+ */
+export {
+  runContentChecks,
+  overallStatus,
+  wordCount,
+  tagCount,
+  extractUrls,
+  hostOf,
+  DEFAULT_HYPE_WORDS,
+  type ContentCheck,
+  type ContentFields,
+  type ContentChecksConfig,
+  type CheckStatus,
+  type Band,
+} from './checks';
+
+export { ValidationChecklist } from './ValidationChecklist';
+export type {
+  ValidationChecklistProps,
+  JudgeVerdict,
+  JudgeIssue,
+  ValidationOverride,
+} from './ValidationChecklist';