@startsimpli/ui 0.4.65 → 0.4.67

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.65",
+  "version": "0.4.67",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/components/navigation/__tests__/navigation.test.tsx

@@ -128,7 +128,10 @@ describe('Sidebar', () => {
     ]
     render(<Sidebar appName="App" sections={customSections} />)
     const activeLink = screen.getByText('Active Link').closest('a')
-    expect(activeLink).toHaveClass('bg-primary-600')
+    // Semantic token, not a numeric ramp — `bg-primary-600` is undefined in apps
+    // that only declare --color-primary, so the active pill vanished (startsim-1f3n).
+    expect(activeLink).toHaveClass('bg-primary')
+    expect(activeLink).toHaveClass('text-primary-foreground')
   })
 
   it('inactive link uses gray text', () => {
@@ -154,7 +157,7 @@ describe('Sidebar', () => {
     ]
     render(<Sidebar appName="App" sections={customSections} />)
     const homeLink = screen.getByText('Home').closest('a')
-    expect(homeLink).not.toHaveClass('bg-primary-600')
+    expect(homeLink).not.toHaveClass('bg-primary')
   })
 })
 

package/src/components/navigation/app-shell.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { useEffect, type ReactNode } from 'react';
+import { useEffect, useState, type ReactNode } from 'react';
 import { useAuth, buildCentralAuthUrl } from '@startsimpli/auth';
 import { LogOut, User } from 'lucide-react';
 import { Sidebar, SidebarLayout, type SidebarSection } from './sidebar';
@@ -52,6 +52,9 @@ export function AppShell({
   children,
 }: AppShellProps) {
   const { user, isLoading, logout } = useAuth();
+  // Owned here so the content spacer shrinks with the rail — the Sidebar used to
+  // keep this private, so "Collapse" narrowed the rail and left a dead 16rem gap.
+  const [collapsed, setCollapsed] = useState(false);
 
   const signin = (returnTo: string) => buildCentralAuthUrl('signin', { app, returnTo });
 
@@ -112,8 +115,15 @@ export function AppShell({
 
   return (
     <>
-      <Sidebar appName={appName} sections={sections} userDropdown={userDropdown} collapsible />
-      <SidebarLayout>{children}</SidebarLayout>
+      <Sidebar
+        appName={appName}
+        sections={sections}
+        userDropdown={userDropdown}
+        collapsible
+        collapsed={collapsed}
+        onCollapsedChange={setCollapsed}
+      />
+      <SidebarLayout collapsed={collapsed}>{children}</SidebarLayout>
     </>
   );
 }

package/src/components/navigation/grouped-nav.tsx

@@ -69,7 +69,7 @@ function linkClasses(active: boolean, indented: boolean) {
     'flex items-center gap-3 px-3 py-2 rounded-md text-sm font-medium transition-colors',
     indented && 'pl-9',
     active
-      ? 'bg-primary-600 text-white'
+      ? 'bg-primary text-primary-foreground'
       : 'text-gray-700 hover:bg-gray-100 hover:text-gray-900',
   )
 }
@@ -175,7 +175,7 @@ function NavGroup({
           type="button"
           onClick={() => setOpen((o) => !o)}
           aria-expanded={expanded}
-          className="w-full flex items-center justify-between gap-2 px-3 py-1.5 rounded-md hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-primary-500"
+          className="w-full flex items-center justify-between gap-2 px-3 py-1.5 rounded-md hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-ring"
         >
           {heading}
           <ChevronDown

package/src/components/navigation/sidebar.tsx

@@ -40,9 +40,17 @@ export interface SidebarProps {
    */
   collapsible?: boolean;
   /**
-   * Default collapsed state
+   * Default collapsed state (uncontrolled)
    */
   defaultCollapsed?: boolean;
+  /**
+   * Controlled collapsed state. Pass with onCollapsedChange when the surrounding
+   * layout also needs to know (see AppShell — the content spacer must shrink with
+   * the rail, otherwise "Collapse" only narrows the rail and leaves a dead gap).
+   */
+  collapsed?: boolean;
+  /** Fires whenever the collapse toggle is used. */
+  onCollapsedChange?: (collapsed: boolean) => void;
 }
 
 export function Sidebar({
@@ -52,9 +60,16 @@ export function Sidebar({
   className,
   collapsible = true,
   defaultCollapsed = false,
+  collapsed: controlledCollapsed,
+  onCollapsedChange,
 }: SidebarProps) {
   const pathname = usePathname();
-  const [collapsed, setCollapsed] = useState(defaultCollapsed);
+  const [internalCollapsed, setInternalCollapsed] = useState(defaultCollapsed);
+  const collapsed = controlledCollapsed ?? internalCollapsed;
+  const setCollapsed = (next: boolean) => {
+    if (controlledCollapsed === undefined) setInternalCollapsed(next);
+    onCollapsedChange?.(next);
+  };
 
   const isActivePath = (href: string) => {
     if (href === '/') {
@@ -76,7 +91,7 @@ export function Sidebar({
         <Link
           href="/"
           className={cn(
-            'font-bold hover:text-primary-400 transition-colors',
+            'font-bold transition-colors hover:text-primary',
             collapsed ? 'text-lg' : 'text-xl'
           )}
         >
@@ -103,7 +118,7 @@ export function Sidebar({
                     className={cn(
                       'flex items-center gap-3 px-3 py-2 rounded-md text-sm font-medium transition-colors',
                       isActive
-                        ? 'bg-primary-600 text-white'
+                        ? 'bg-primary text-primary-foreground shadow-sm'
                         : 'text-gray-300 hover:bg-gray-800 hover:text-white',
                       collapsed && 'justify-center'
                     )}
@@ -163,7 +178,7 @@ export interface SidebarLayoutProps {
 
 export function SidebarLayout({ children, collapsed = false }: SidebarLayoutProps) {
   return (
-    <div className="flex h-screen bg-gray-50">
+    <div className="flex h-screen bg-background">
       {/* Spacer for fixed sidebar */}
       <div className={cn('flex-shrink-0 transition-all duration-200', collapsed ? 'w-20' : 'w-64')} />
 

package/src/components/settings/SettingsCard.tsx

@@ -8,24 +8,32 @@ export interface SettingsCardProps {
   children?: React.ReactNode
 }
 
+/**
+ * A titled settings panel with an optional trailing action.
+ *
+ * Theme-driven surfaces (startsim-1f3n): it used to hard-code
+ * `bg-white text-gray-900`, which ignored every app's palette and was
+ * unreadable in dark mode. Now it renders on the `card` token like the rest of
+ * the system.
+ */
 export function SettingsCard({ title, description, icon: Icon, action, children }: SettingsCardProps) {
   return (
-    <div className="rounded-xl border bg-white text-gray-900 shadow-sm">
-      <div className="flex items-start justify-between p-6">
-        <div className="flex items-start gap-4">
+    <div className="rounded-xl border border-border bg-card text-card-foreground shadow-sm">
+      <div className="flex flex-wrap items-start justify-between gap-4 p-6">
+        <div className="flex min-w-0 items-start gap-4">
           {Icon && (
-            <div className="flex h-10 w-10 items-center justify-center rounded-lg bg-gray-100">
-              <Icon className="h-5 w-5 text-gray-600" />
+            <div className="flex h-10 w-10 shrink-0 items-center justify-center rounded-lg bg-primary/10">
+              <Icon className="h-5 w-5 text-primary" />
             </div>
           )}
-          <div>
+          <div className="min-w-0">
             <h3 className="font-semibold leading-none tracking-tight">{title}</h3>
             {description && (
-              <p className="text-sm text-gray-500 mt-1.5">{description}</p>
+              <p className="mt-1.5 text-sm text-muted-foreground">{description}</p>
             )}
           </div>
         </div>
-        {action && <div className="flex-shrink-0 ml-4">{action}</div>}
+        {action && <div className="shrink-0">{action}</div>}
       </div>
       {children && <div className="px-6 pb-6 pt-0">{children}</div>}
     </div>

package/src/components/team/InviteMemberDialog.tsx

@@ -32,6 +32,12 @@ export interface InviteMemberDialogProps {
   triggerLabel?: string
   /** Title in the modal header. */
   title?: string
+  /** Submit button label. Override when the backend adds directly rather than
+   *  emailing an invite (e.g. Foundry: "Add member"). */
+  submitLabel?: string
+  /** Confirmation line after a successful submit. Receives the email so the
+   *  caller can match its own semantics ("Added ada@x to this foundry"). */
+  successMessage?: (email: string) => string
   /** Default role pre-selected. */
   defaultRole?: TeamRole
   /** Available roles in the dropdown. Defaults to admin/member/viewer (no owner). */
@@ -48,6 +54,8 @@ export function InviteMemberDialog({
   onInvited,
   triggerLabel = 'Invite member',
   title = 'Invite a teammate',
+  submitLabel = 'Send invitation',
+  successMessage = (email) => `Invitation sent to ${email}`,
   defaultRole = 'member',
   availableRoles = ['admin', 'member', 'viewer'],
   classNames,
@@ -95,7 +103,7 @@ export function InviteMemberDialog({
       if (onSubmit) {
         invited = await onSubmit({ email: email.trim(), teamId, role })
       }
-      setSuccess(`Invitation sent to ${email.trim()}`)
+      setSuccess(successMessage(email.trim()))
       setEmail('')
       onInvited?.(invited)
     } catch (err) {
@@ -170,7 +178,7 @@ export function InviteMemberDialog({
                   className={cls.submitButton}
                   disabled={submitting}
                 >
-                  {submitting ? 'Sending…' : 'Send invitation'}
+                  {submitting ? 'Saving…' : submitLabel}
                 </button>
               </div>
             </form>

package/src/components/team/MembersTable.tsx

@@ -77,7 +77,12 @@ export function MembersTable({
               </td>
             </tr>
           )}
-          {members.map((m) => (
+          {members.map((m) => {
+            const displayName = userDisplayName(m.user) || m.userId
+            // Members with no name fall back to their email, so printing the
+            // email underneath stacked the same string on itself.
+            const secondary = m.user?.email && m.user.email !== displayName ? m.user.email : null
+            return (
             <tr key={m.id} className={cls.row}>
               <td className={cls.cell}>
                 <div className="flex items-center gap-3">
@@ -93,13 +98,9 @@ export function MembersTable({
                       {userInitials(m.user)}
                     </span>
                   )}
-                  <div className="flex flex-col">
-                    <span className={cls.name}>
-                      {userDisplayName(m.user) || m.userId}
-                    </span>
-                    {m.user?.email && (
-                      <span className={cls.email}>{m.user.email}</span>
-                    )}
+                  <div className="flex min-w-0 flex-col">
+                    <span className={cls.name}>{displayName}</span>
+                    {secondary && <span className={cls.email}>{secondary}</span>}
                   </div>
                 </div>
               </td>
@@ -130,7 +131,8 @@ export function MembersTable({
                 </td>
               )}
             </tr>
-          ))}
+            )
+          })}
         </tbody>
       </table>
     </div>

package/src/components/team/__tests__/team-components.test.tsx

@@ -73,6 +73,27 @@ describe('MembersTable', () => {
     expect(container.firstChild).toHaveClass('my-root-class')
   })
 
+  it('does not print the email twice when it is also the display name', () => {
+    // Foundry maps control-plane members with an email and no name, so
+    // userDisplayName() falls back to the email — the row used to stack the
+    // same string on itself. startsim-1f3n.4.
+    render(
+      <MembersTable
+        members={[
+          {
+            id: 'u1',
+            userId: 'u1',
+            teamId: 't1',
+            role: 'owner',
+            joinedAt: '2025-01-01',
+            user: { id: 'u1', email: 'qosha@debugg.ai' },
+          },
+        ]}
+      />
+    )
+    expect(screen.getAllByText('qosha@debugg.ai')).toHaveLength(1)
+  })
+
   it('shows the empty state when no members', () => {
     render(<MembersTable members={[]} />)
     expect(screen.getByText('No members yet.')).toBeInTheDocument()

package/src/components/team/__tests__/theme-tokens.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Theme-token guard for the team/settings surfaces (startsim-1f3n.1).
+ *
+ * These components ship default Tailwind classes. The only colors an app is
+ * guaranteed to have are the semantic tokens from packages/ui/theme/contract.css
+ * (--primary, --card, --border, --muted-foreground, …). Apps do NOT all define a
+ * numeric palette ramp: apps/foundry defines `--color-primary` with no
+ * `--color-primary-600`, so in Tailwind v4 `bg-primary-600` generates no rule at
+ * all — the Invite member button rendered as white text on a white card, i.e.
+ * invisible.
+ *
+ * Hard-coded `gray-*` / `bg-white` are the same class of bug one step quieter:
+ * the classes exist, but they ignore the app's theme and are unreadable in dark
+ * mode. Shared components must be theme-driven, not palette-driven.
+ */
+
+import { INVITE_DIALOG_DEFAULTS } from '../invite-member-dialog-default-class-names'
+import { MEMBERS_TABLE_DEFAULTS } from '../members-table-default-class-names'
+import { ROLE_SELECTOR_DEFAULTS } from '../role-selector-default-class-names'
+import { PENDING_INVITE_DEFAULTS } from '../pending-invitation-callout-default-class-names'
+import { LEAVE_DIALOG_DEFAULTS } from '../leave-team-dialog-default-class-names'
+import { ORG_SWITCHER_DEFAULTS } from '../org-switcher-default-class-names'
+import { DOMAIN_CLAIM_DEFAULTS } from '../domain-claim-card-default-class-names'
+import { TEAM_SETTINGS_PAGE_DEFAULTS } from '../pages/team-settings-page-default-class-names'
+import { DOMAINS_SETTINGS_PAGE_DEFAULTS } from '../pages/domains-settings-page-default-class-names'
+
+const MAPS: Record<string, Record<string, string>> = {
+  INVITE_DIALOG_DEFAULTS,
+  MEMBERS_TABLE_DEFAULTS,
+  ROLE_SELECTOR_DEFAULTS,
+  PENDING_INVITE_DEFAULTS,
+  LEAVE_DIALOG_DEFAULTS,
+  ORG_SWITCHER_DEFAULTS,
+  DOMAIN_CLAIM_DEFAULTS,
+  TEAM_SETTINGS_PAGE_DEFAULTS,
+  DOMAINS_SETTINGS_PAGE_DEFAULTS,
+}
+
+/** `bg-primary-600`, `text-primary-700`, `focus:border-primary-500`, … */
+const PRIMARY_RAMP = /(^|:)[a-z-]*-primary-\d{2,3}\b/
+/** `text-gray-500`, `bg-white`, `divide-gray-100`, … — theme-blind surfaces. */
+const RAW_SURFACE = /(^|:)(bg|text|border|divide|ring)-(gray|slate|zinc|neutral|stone)-\d{2,3}\b|(^|:)bg-white\b/
+
+function offenders(map: Record<string, string>, pattern: RegExp): string[] {
+  return Object.entries(map)
+    .flatMap(([slot, value]) =>
+      String(value)
+        .split(/\s+/)
+        .filter((cls) => pattern.test(cls))
+        .map((cls) => `${slot}: ${cls}`),
+    )
+}
+
+describe('team surfaces are theme-driven', () => {
+  it.each(Object.keys(MAPS))(
+    '%s uses no numeric primary ramp (undefined in token-only apps like foundry)',
+    (name) => {
+      expect(offenders(MAPS[name], PRIMARY_RAMP)).toEqual([])
+    },
+  )
+
+  it.each(Object.keys(MAPS))('%s uses no theme-blind gray/white surfaces', (name) => {
+    expect(offenders(MAPS[name], RAW_SURFACE)).toEqual([])
+  })
+
+  it('the invite trigger is a filled primary button that is visible on a card', () => {
+    expect(INVITE_DIALOG_DEFAULTS.trigger).toContain('bg-primary')
+    expect(INVITE_DIALOG_DEFAULTS.trigger).toContain('text-primary-foreground')
+  })
+
+  it('dialog panels sit on the card surface, not hard-coded white', () => {
+    expect(INVITE_DIALOG_DEFAULTS.panel).toContain('bg-card')
+    expect(LEAVE_DIALOG_DEFAULTS.panel).toContain('bg-card')
+  })
+})
+

package/src/components/team/domain-claim-card-default-class-names.ts

@@ -1,4 +1,5 @@
-/** Default Tailwind classes for {@link DomainClaimCard}. startsim-o7s. */
+/** Default Tailwind classes for {@link DomainClaimCard}. startsim-o7s.
+ *  Semantic tokens only (startsim-1f3n) — theme-driven, dark-mode safe. */
 export interface DomainClaimCardClassNames {
   root?: string
   header?: string
@@ -20,26 +21,28 @@ export interface DomainClaimCardClassNames {
 }
 
 export const DOMAIN_CLAIM_DEFAULTS: Required<DomainClaimCardClassNames> = {
-  root: 'rounded-xl border border-gray-200 bg-white p-5',
+  root: 'rounded-xl border border-border bg-card p-5 text-card-foreground',
   header: 'flex items-center justify-between gap-3',
-  domain: 'text-base font-semibold text-gray-900',
+  domain: 'text-base font-semibold text-foreground',
   statusBadge: 'inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium',
-  statusVerified: 'bg-green-100 text-green-800',
-  statusUnverified: 'bg-yellow-100 text-yellow-800',
-  body: 'mt-4 space-y-3 text-sm text-gray-700',
-  sectionLabel: 'text-xs font-medium uppercase tracking-wide text-gray-500',
+  statusVerified:
+    'bg-emerald-500/10 text-emerald-700 dark:text-emerald-400',
+  statusUnverified:
+    'bg-amber-500/10 text-amber-700 dark:text-amber-400',
+  body: 'mt-4 space-y-3 text-sm text-foreground',
+  sectionLabel: 'text-xs font-medium uppercase tracking-wide text-muted-foreground',
   tokenRow: 'flex items-center gap-2',
   tokenCode:
-    'flex-1 rounded-md bg-gray-50 px-3 py-2 font-mono text-xs text-gray-900',
-  helpText: 'text-xs text-gray-500',
+    'flex-1 rounded-md bg-muted px-3 py-2 font-mono text-xs text-foreground',
+  helpText: 'text-xs text-muted-foreground',
   actions: 'mt-4 flex flex-wrap items-center gap-2',
   primaryButton:
-    'rounded-md bg-primary-600 px-3 py-1.5 text-sm font-semibold text-white hover:bg-primary-700 disabled:opacity-50',
+    'rounded-md bg-primary px-3 py-1.5 text-sm font-semibold text-primary-foreground shadow-sm transition-colors hover:bg-primary/90 disabled:opacity-50',
   secondaryButton:
-    'rounded-md border border-gray-300 px-3 py-1.5 text-sm font-medium text-gray-700 hover:bg-gray-50 disabled:opacity-50',
+    'rounded-md border border-border px-3 py-1.5 text-sm font-medium text-foreground transition-colors hover:bg-muted disabled:opacity-50',
   revokeButton:
-    'rounded-md border border-red-300 px-3 py-1.5 text-sm font-medium text-red-700 hover:bg-red-50 disabled:opacity-50',
-  errorText: 'mt-2 text-sm text-red-600',
+    'rounded-md border border-destructive/40 px-3 py-1.5 text-sm font-medium text-destructive transition-colors hover:bg-destructive/10 disabled:opacity-50',
+  errorText: 'mt-2 text-sm text-destructive',
   codeInput:
-    'w-24 rounded-md border border-gray-300 px-2 py-1.5 text-sm tracking-widest outline-none focus:border-primary-500 focus:ring-1 focus:ring-primary-500',
+    'w-24 rounded-md border border-input bg-background px-2 py-1.5 text-sm tracking-widest text-foreground outline-none focus:border-ring focus:ring-1 focus:ring-ring',
 }

package/src/components/team/invite-member-dialog-default-class-names.ts

@@ -1,4 +1,12 @@
-/** Default Tailwind classes for {@link InviteMemberDialog}. startsim-o7s. */
+/**
+ * Default Tailwind classes for {@link InviteMemberDialog}. startsim-o7s.
+ *
+ * Semantic tokens only (startsim-1f3n) — see packages/ui/theme/contract.css.
+ * A numeric ramp like `bg-primary-600` is NOT part of the contract: apps that
+ * define `--color-primary` alone (foundry, gen-ai-consulting, workflow-studio)
+ * generate no rule for it, which is how this trigger became an invisible
+ * white-on-white button in the Foundry control plane.
+ */
 export interface InviteMemberDialogClassNames {
   trigger?: string
   overlay?: string
@@ -18,24 +26,24 @@ export interface InviteMemberDialogClassNames {
 
 export const INVITE_DIALOG_DEFAULTS: Required<InviteMemberDialogClassNames> = {
   trigger:
-    'inline-flex items-center rounded-md bg-primary-600 px-3 py-2 text-sm font-semibold text-white hover:bg-primary-700',
+    'inline-flex items-center gap-1.5 rounded-md bg-primary px-3 py-2 text-sm font-semibold text-primary-foreground shadow-sm transition-colors hover:bg-primary/90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
   overlay:
     'fixed inset-0 z-50 flex items-center justify-center bg-black/50 p-4',
   panel:
-    'w-full max-w-md rounded-xl bg-white shadow-xl ring-1 ring-black/5',
-  header: 'border-b border-gray-100 px-6 py-4',
-  title: 'text-base font-semibold text-gray-900',
+    'w-full max-w-md rounded-xl border border-border bg-card text-card-foreground shadow-xl',
+  header: 'border-b border-border px-6 py-4',
+  title: 'text-base font-semibold text-foreground',
   body: 'space-y-4 px-6 py-4',
   fieldRow: '',
-  label: 'block text-sm font-medium text-gray-700 mb-1',
+  label: 'mb-1 block text-sm font-medium text-foreground',
   input:
-    'w-full rounded-lg border border-gray-300 px-3 py-2 text-sm outline-none focus:border-primary-500 focus:ring-1 focus:ring-primary-500',
-  errorText: 'text-sm text-red-600',
-  successText: 'text-sm text-green-600',
+    'w-full rounded-lg border border-input bg-background px-3 py-2 text-sm text-foreground placeholder:text-muted-foreground outline-none focus:border-ring focus:ring-1 focus:ring-ring',
+  errorText: 'text-sm text-destructive',
+  successText: 'text-sm text-emerald-600 dark:text-emerald-400',
   footer:
-    'flex items-center justify-end gap-2 border-t border-gray-100 px-6 py-3',
+    'flex items-center justify-end gap-2 border-t border-border px-6 py-3',
   cancelButton:
-    'rounded-md border border-gray-300 px-3 py-1.5 text-sm font-medium text-gray-700 hover:bg-gray-50',
+    'rounded-md border border-border px-3 py-1.5 text-sm font-medium text-foreground transition-colors hover:bg-muted',
   submitButton:
-    'rounded-md bg-primary-600 px-3 py-1.5 text-sm font-semibold text-white hover:bg-primary-700 disabled:opacity-50',
+    'rounded-md bg-primary px-3 py-1.5 text-sm font-semibold text-primary-foreground shadow-sm transition-colors hover:bg-primary/90 disabled:opacity-50',
 }

package/src/components/team/leave-team-dialog-default-class-names.ts

@@ -1,4 +1,5 @@
-/** Default Tailwind classes for {@link LeaveTeamDialog}. startsim-o7s. */
+/** Default Tailwind classes for {@link LeaveTeamDialog}. startsim-o7s.
+ *  Semantic tokens only (startsim-1f3n) — theme-driven, dark-mode safe. */
 export interface LeaveTeamDialogClassNames {
   trigger?: string
   overlay?: string
@@ -15,19 +16,20 @@ export interface LeaveTeamDialogClassNames {
 
 export const LEAVE_DIALOG_DEFAULTS: Required<LeaveTeamDialogClassNames> = {
   trigger:
-    'inline-flex items-center rounded-md border border-red-300 px-3 py-1.5 text-sm font-medium text-red-700 hover:bg-red-50',
+    'inline-flex items-center rounded-md border border-destructive/40 px-3 py-1.5 text-sm font-medium text-destructive transition-colors hover:bg-destructive/10',
   overlay:
     'fixed inset-0 z-50 flex items-center justify-center bg-black/50 p-4',
-  panel: 'w-full max-w-md rounded-xl bg-white shadow-xl ring-1 ring-black/5',
-  header: 'border-b border-gray-100 px-6 py-4',
-  title: 'text-base font-semibold text-gray-900',
-  body: 'space-y-3 px-6 py-4 text-sm text-gray-700',
-  warningText: 'text-sm text-gray-600',
-  errorText: 'text-sm text-red-600',
+  panel:
+    'w-full max-w-md rounded-xl border border-border bg-card text-card-foreground shadow-xl',
+  header: 'border-b border-border px-6 py-4',
+  title: 'text-base font-semibold text-foreground',
+  body: 'space-y-3 px-6 py-4 text-sm text-foreground',
+  warningText: 'text-sm text-muted-foreground',
+  errorText: 'text-sm text-destructive',
   footer:
-    'flex items-center justify-end gap-2 border-t border-gray-100 px-6 py-3',
+    'flex items-center justify-end gap-2 border-t border-border px-6 py-3',
   cancelButton:
-    'rounded-md border border-gray-300 px-3 py-1.5 text-sm font-medium text-gray-700 hover:bg-gray-50',
+    'rounded-md border border-border px-3 py-1.5 text-sm font-medium text-foreground transition-colors hover:bg-muted',
   confirmButton:
-    'rounded-md bg-red-600 px-3 py-1.5 text-sm font-semibold text-white hover:bg-red-700 disabled:opacity-50',
+    'rounded-md bg-destructive px-3 py-1.5 text-sm font-semibold text-destructive-foreground shadow-sm transition-colors hover:bg-destructive/90 disabled:opacity-50',
 }

package/src/components/team/members-table-default-class-names.ts

@@ -1,4 +1,5 @@
-/** Default Tailwind classes for {@link MembersTable}. startsim-o7s. */
+/** Default Tailwind classes for {@link MembersTable}. startsim-o7s.
+ *  Semantic tokens only (startsim-1f3n) — theme-driven, dark-mode safe. */
 export interface MembersTableClassNames {
   root?: string
   table?: string
@@ -18,22 +19,22 @@ export interface MembersTableClassNames {
 }
 
 export const MEMBERS_TABLE_DEFAULTS: Required<MembersTableClassNames> = {
-  root: 'w-full overflow-x-auto rounded-lg border border-gray-200',
-  table: 'w-full text-sm text-left',
-  thead: 'bg-gray-50 text-xs uppercase tracking-wide text-gray-500',
+  root: 'w-full overflow-x-auto rounded-lg border border-border bg-card',
+  table: 'w-full text-left text-sm',
+  thead: 'bg-muted/50 text-xs uppercase tracking-wide text-muted-foreground',
   headerRow: '',
-  th: 'px-4 py-2 font-medium',
-  tbody: 'divide-y divide-gray-100 bg-white',
-  row: 'hover:bg-gray-50',
+  th: 'px-4 py-2.5 font-medium',
+  tbody: 'divide-y divide-border',
+  row: 'transition-colors hover:bg-muted/40',
   cell: 'px-4 py-3 align-middle',
   avatar:
-    'flex h-8 w-8 items-center justify-center rounded-full bg-gray-100 text-xs font-medium text-gray-600',
-  name: 'font-medium text-gray-900',
-  email: 'text-gray-500',
+    'flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-primary/10 text-xs font-semibold text-primary',
+  name: 'font-medium text-foreground',
+  email: 'text-muted-foreground',
   roleBadge:
-    'inline-flex items-center rounded-full bg-gray-100 px-2 py-0.5 text-xs font-medium text-gray-700',
+    'inline-flex items-center rounded-full border border-border bg-muted px-2 py-0.5 text-xs font-medium text-muted-foreground',
   actions: 'flex items-center justify-end gap-2',
   removeButton:
-    'rounded-md border border-gray-300 px-2 py-1 text-xs text-gray-700 hover:bg-gray-100 disabled:opacity-50',
-  emptyRow: 'px-4 py-6 text-center text-sm text-gray-500',
+    'rounded-md border border-border px-2 py-1 text-xs text-muted-foreground transition-colors hover:border-destructive/40 hover:bg-destructive/10 hover:text-destructive disabled:opacity-50',
+  emptyRow: 'px-4 py-6 text-center text-sm text-muted-foreground',
 }

package/src/components/team/org-switcher-default-class-names.ts

@@ -1,4 +1,5 @@
-/** Default Tailwind classes for {@link OrgSwitcher}. startsim-o7s. */
+/** Default Tailwind classes for {@link OrgSwitcher}. startsim-o7s.
+ *  Semantic tokens only (startsim-1f3n) — theme-driven, dark-mode safe. */
 export interface OrgSwitcherClassNames {
   root?: string
   label?: string
@@ -7,7 +8,7 @@ export interface OrgSwitcherClassNames {
 
 export const ORG_SWITCHER_DEFAULTS: Required<OrgSwitcherClassNames> = {
   root: 'inline-flex items-center gap-2',
-  label: 'text-xs font-medium uppercase tracking-wide text-gray-500',
+  label: 'text-xs font-medium uppercase tracking-wide text-muted-foreground',
   select:
-    'rounded-md border border-gray-300 bg-white px-3 py-1.5 text-sm font-medium text-gray-900 outline-none focus:border-primary-500 focus:ring-1 focus:ring-primary-500',
+    'rounded-md border border-input bg-background px-3 py-1.5 text-sm font-medium text-foreground outline-none transition-colors focus:border-ring focus:ring-1 focus:ring-ring',
 }

package/src/components/team/pages/domains-settings-page-default-class-names.ts

@@ -60,30 +60,30 @@ export const DOMAINS_SETTINGS_PAGE_DEFAULTS: Required<
 > = {
   root: 'space-y-6',
   header: '',
-  backLink: 'text-sm text-primary-600 hover:underline',
+  backLink: 'text-sm text-primary hover:underline',
   titleRow: 'mt-2 flex items-center justify-between gap-4',
-  title: 'text-xl font-semibold text-gray-900',
-  subtitle: 'mt-1 text-sm text-gray-500',
+  title: 'text-xl font-semibold text-foreground',
+  subtitle: 'mt-1 text-sm text-muted-foreground',
 
   primaryButton:
-    'rounded-lg bg-primary-600 px-4 py-2 text-sm font-medium text-white hover:bg-primary-700 disabled:opacity-50',
+    'rounded-lg bg-primary px-4 py-2 text-sm font-medium text-primary-foreground shadow-sm transition-colors hover:bg-primary/90 disabled:opacity-50',
   input:
-    'w-full rounded-lg border border-gray-300 px-3 py-2 text-sm outline-none focus:border-primary-500 focus:ring-1 focus:ring-primary-500',
-  label: 'block text-sm font-medium text-gray-700',
-  formCard: 'rounded-xl border border-gray-200 bg-white p-4 space-y-3',
+    'w-full rounded-lg border border-input bg-background px-3 py-2 text-sm text-foreground placeholder:text-muted-foreground outline-none focus:border-ring focus:ring-1 focus:ring-ring',
+  label: 'block text-sm font-medium text-foreground',
+  formCard: 'space-y-3 rounded-xl border border-border bg-card p-4',
   formActions: 'flex gap-2',
   cancelButton:
-    'rounded-lg border border-gray-300 px-4 py-2 text-sm text-gray-700 hover:bg-gray-50',
+    'rounded-lg border border-border px-4 py-2 text-sm text-foreground transition-colors hover:bg-muted',
 
-  errorText: 'text-sm text-red-600',
-  loadingText: 'text-sm text-gray-500',
+  errorText: 'text-sm text-destructive',
+  loadingText: 'text-sm text-muted-foreground',
 
   emptyState:
-    'rounded-xl border border-dashed border-gray-300 bg-white p-10 text-center',
-  emptyText: 'text-sm text-gray-600',
+    'rounded-xl border border-dashed border-border bg-card p-10 text-center',
+  emptyText: 'text-sm text-muted-foreground',
 
   retryButton:
-    'rounded-lg border border-gray-300 px-3 py-1.5 text-sm text-gray-700 hover:bg-gray-50',
+    'rounded-lg border border-border px-3 py-1.5 text-sm text-foreground transition-colors hover:bg-muted',
 
   list: 'space-y-4',
 }

package/src/components/team/pages/team-settings-page-default-class-names.ts

@@ -82,35 +82,35 @@ export const TEAM_SETTINGS_PAGE_DEFAULTS: Required<
 > = {
   root: 'space-y-8',
   header: '',
-  backLink: 'text-sm text-primary-600 hover:underline',
-  title: 'mt-2 text-xl font-semibold text-gray-900',
-  subtitle: 'mt-1 text-sm text-gray-500',
+  backLink: 'text-sm text-primary hover:underline',
+  title: 'mt-2 text-xl font-semibold text-foreground',
+  subtitle: 'mt-1 text-sm text-muted-foreground',
 
   section: 'space-y-3',
   sectionHeader: 'flex items-center justify-between',
-  sectionHeading: 'text-sm font-semibold uppercase tracking-wide text-gray-500',
-  sectionBody: 'text-sm text-gray-500',
+  sectionHeading: 'text-sm font-semibold uppercase tracking-wide text-muted-foreground',
+  sectionBody: 'text-sm text-muted-foreground',
 
-  dangerDivider: 'space-y-3 border-t border-gray-200 pt-6',
+  dangerDivider: 'space-y-3 border-t border-border pt-6',
 
-  errorText: 'text-sm text-red-600',
-  loadingText: 'text-sm text-gray-500',
-  emptyText: 'text-sm text-gray-500',
+  errorText: 'text-sm text-destructive',
+  loadingText: 'text-sm text-muted-foreground',
+  emptyText: 'text-sm text-muted-foreground',
 
   retryButton:
-    'rounded-lg border border-gray-300 px-3 py-1.5 text-sm text-gray-700 hover:bg-gray-50',
+    'rounded-lg border border-border px-3 py-1.5 text-sm text-foreground transition-colors hover:bg-muted',
 
   invitationsTableWrapper:
-    'overflow-hidden rounded-xl border border-gray-200 bg-white',
+    'overflow-hidden rounded-xl border border-border bg-card',
   invitationsTable: 'w-full text-sm',
-  invitationsThead: 'bg-gray-50 text-left text-xs uppercase text-gray-500',
+  invitationsThead: 'bg-muted/50 text-left text-xs uppercase text-muted-foreground',
   invitationsTh: 'px-4 py-3 font-medium',
-  invitationsTbody: 'divide-y divide-gray-100',
-  invitationsEmailCell: 'px-4 py-3 text-gray-700',
+  invitationsTbody: 'divide-y divide-border',
+  invitationsEmailCell: 'px-4 py-3 text-foreground',
   invitationsRoleCell: 'px-4 py-3',
   invitationsRoleBadge:
-    'inline-flex items-center rounded-full bg-primary-50 px-2 py-0.5 text-xs font-medium text-primary-700',
-  invitationsExpiryCell: 'px-4 py-3 text-gray-500',
+    'inline-flex items-center rounded-full bg-primary/10 px-2 py-0.5 text-xs font-medium text-primary',
+  invitationsExpiryCell: 'px-4 py-3 text-muted-foreground',
   invitationsActionsCell: 'px-4 py-3 text-right',
-  invitationsRevokeButton: 'text-red-600 hover:underline text-sm',
+  invitationsRevokeButton: 'text-sm text-destructive hover:underline',
 }

package/src/components/team/pending-invitation-callout-default-class-names.ts

@@ -1,4 +1,6 @@
-/** Default Tailwind classes for {@link PendingInvitationCallout}. startsim-o7s. */
+/** Default Tailwind classes for {@link PendingInvitationCallout}. startsim-o7s.
+ *  Semantic tokens only (startsim-1f3n) — the callout picks up the app's brand
+ *  color instead of a hard-coded blue that clashes with every non-blue theme. */
 export interface PendingInvitationCalloutClassNames {
   root?: string
   message?: string
@@ -10,13 +12,13 @@ export interface PendingInvitationCalloutClassNames {
 }
 
 export const PENDING_INVITE_DEFAULTS: Required<PendingInvitationCalloutClassNames> = {
-  root: 'flex items-center gap-3 rounded-lg border border-blue-200 bg-blue-50 px-4 py-3',
-  message: 'flex-1 text-sm text-blue-900',
+  root: 'flex items-center gap-3 rounded-lg border border-primary/25 bg-primary/5 px-4 py-3',
+  message: 'flex-1 text-sm text-foreground',
   emphasized: 'font-semibold',
   actions: 'flex items-center gap-2',
   acceptButton:
-    'rounded-md bg-blue-600 px-3 py-1.5 text-sm font-semibold text-white hover:bg-blue-700 disabled:opacity-50',
+    'rounded-md bg-primary px-3 py-1.5 text-sm font-semibold text-primary-foreground shadow-sm transition-colors hover:bg-primary/90 disabled:opacity-50',
   declineButton:
-    'rounded-md border border-blue-300 px-3 py-1.5 text-sm font-medium text-blue-700 hover:bg-blue-100',
-  errorText: 'mt-2 text-sm text-red-600',
+    'rounded-md border border-border px-3 py-1.5 text-sm font-medium text-muted-foreground transition-colors hover:bg-muted hover:text-foreground',
+  errorText: 'mt-2 text-sm text-destructive',
 }

package/src/components/team/role-selector-default-class-names.ts

@@ -1,4 +1,5 @@
-/** Default Tailwind classes for {@link RoleSelector}. startsim-o7s. */
+/** Default Tailwind classes for {@link RoleSelector}. startsim-o7s.
+ *  Semantic tokens only (startsim-1f3n) — theme-driven, dark-mode safe. */
 export interface RoleSelectorClassNames {
   root?: string
   select?: string
@@ -7,5 +8,5 @@ export interface RoleSelectorClassNames {
 export const ROLE_SELECTOR_DEFAULTS: Required<RoleSelectorClassNames> = {
   root: 'inline-block',
   select:
-    'rounded-md border border-gray-300 bg-white px-2 py-1 text-sm text-gray-900 outline-none focus:border-primary-500 focus:ring-1 focus:ring-primary-500 disabled:cursor-not-allowed disabled:opacity-50',
+    'rounded-md border border-input bg-background px-2 py-1 text-sm text-foreground outline-none transition-colors focus:border-ring focus:ring-1 focus:ring-ring disabled:cursor-not-allowed disabled:opacity-50',
 }

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

@@ -284,3 +284,36 @@ describe('runContentChecks — locations (768w.16.15.3 jump-to-issue)', () => {
     expect(checks.some((c) => c.status !== 'pass')).toBe(true);
   });
 });
+
+describe('source-overlap check', () => {
+  const SRC =
+    'Saudi Arabia will apply excise tax to sweetened drinks from January 2026, Gulf News reported, adding another category to a tax architecture that already captures selected products across the Gulf region.';
+
+  it('is skipped when no sourceTexts are supplied', () => {
+    expect(find(runContentChecks({ blog: 'anything' }), 'source-overlap')).toBeUndefined();
+    expect(find(runContentChecks({ blog: 'anything' }, { sourceTexts: [] }), 'source-overlap')).toBeUndefined();
+  });
+
+  it('fails when the blog copies a long verbatim run from a source', () => {
+    const c = find(
+      runContentChecks(
+        { blog: 'Saudi Arabia will apply excise tax to sweetened drinks from January 2026, Gulf News reported.' },
+        { sourceTexts: [SRC] },
+      ),
+      'source-overlap',
+    );
+    expect(c!.status).toBe('fail');
+    expect(c!.locations?.[0].field).toBe('blog');
+  });
+
+  it('passes a genuine paraphrase', () => {
+    const c = find(
+      runContentChecks(
+        { blog: 'From 2026 the Kingdom widens its sugary-drink levy, a reminder Gulf tax rules vary by market.' },
+        { sourceTexts: [SRC] },
+      ),
+      'source-overlap',
+    );
+    expect(c!.status).toBe('pass');
+  });
+});

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

@@ -0,0 +1,58 @@
+import { verbatimOverlap, normWords } from '../overlap';
+
+const SOURCE = `Saudi Arabia will apply excise tax to sweetened drinks from January 2026,
+Gulf News reported, adding another category to a tax architecture that already
+captures selected products across the Gulf region. For businesses outside the region,
+the broader lesson is that excise tax in the GCC should be viewed as a shared framework
+with local variations that change launch economics.`;
+
+describe('normWords', () => {
+  it('lowercases, strips punctuation, collapses whitespace', () => {
+    expect(normWords('Hello,   WORLD! (2026)')).toEqual(['hello', 'world', '2026']);
+    expect(normWords('')).toEqual([]);
+    expect(normWords(null as unknown as string)).toEqual([]);
+  });
+});
+
+describe('verbatimOverlap', () => {
+  it('flags a long verbatim copy (whole sentence lifted from the source)', () => {
+    const copied = 'Saudi Arabia will apply excise tax to sweetened drinks from January 2026, Gulf News reported.';
+    const r = verbatimOverlap(copied, [SOURCE]);
+    expect(r.longestRunWords).toBeGreaterThanOrEqual(12);
+    expect(r.overlapRatio).toBeGreaterThan(0.5);
+    expect(r.sample).toContain('excise tax to sweetened drinks');
+  });
+
+  it('passes a genuine paraphrase of the same facts', () => {
+    const paraphrase =
+      'From 2026 the Kingdom broadens its excise regime to cover sugary beverages, a reminder that Gulf tax rules differ market by market.';
+    const r = verbatimOverlap(paraphrase, [SOURCE]);
+    expect(r.longestRunWords).toBeLessThan(6);
+    expect(r.overlapRatio).toBeLessThan(0.15);
+  });
+
+  it('ignores a short shared phrase (< minRun words)', () => {
+    // "excise tax" is shared but only 2 words — below the 6-word shingle.
+    const r = verbatimOverlap('Companies weighing excise tax exposure should plan ahead.', [SOURCE]);
+    expect(r.longestRunWords).toBe(0);
+  });
+
+  it('is case- and punctuation-insensitive', () => {
+    const copied = 'SHOULD BE VIEWED AS A SHARED FRAMEWORK — with local variations!!!';
+    const r = verbatimOverlap(copied, [SOURCE]);
+    expect(r.longestRunWords).toBeGreaterThanOrEqual(6);
+    expect(r.sample).toContain('shared framework');
+  });
+
+  it('returns zeros for empty candidate or no sources', () => {
+    expect(verbatimOverlap('', [SOURCE])).toEqual({ longestRunWords: 0, overlapRatio: 0, sample: '' });
+    expect(verbatimOverlap('anything here', [])).toEqual({ longestRunWords: 0, overlapRatio: 0, sample: '' });
+    expect(verbatimOverlap('anything here', [''])).toEqual({ longestRunWords: 0, overlapRatio: 0, sample: '' });
+  });
+
+  it('finds the copied span across multiple sources', () => {
+    const copied = 'a tax architecture that already captures selected products';
+    const r = verbatimOverlap(copied, ['unrelated text about camels', SOURCE]);
+    expect(r.longestRunWords).toBeGreaterThanOrEqual(7);
+  });
+});

package/src/components/validation/checks.ts

@@ -11,6 +11,7 @@
  * 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.
  */
+import { verbatimOverlap } from './overlap';
 
 /** A single check's outcome. Green / amber / red, encoded redundantly in the UI. */
 export type CheckStatus = 'pass' | 'warn' | 'fail';
@@ -90,6 +91,18 @@ export interface ContentChecksConfig {
   hypeWords?: string[];
   /** Approved source hosts (no `www.`). REQUIRED to run the source check. */
   approvedHosts?: string[];
+  /**
+   * The cited source articles' TEXT. REQUIRED to run the verbatim-overlap check —
+   * the guardrail against copying too much from a source. Omit it (or pass []) and
+   * the check is skipped (nothing to compare against).
+   */
+  sourceTexts?: string[];
+  /** Longest verbatim run (words) that FAILS the overlap check (default 15). */
+  overlapFailRun?: number;
+  /** Longest verbatim run (words) that WARNS (default 8). */
+  overlapWarnRun?: number;
+  /** Copied fraction (0–1) that FAILS regardless of run length (default 0.25). */
+  overlapFailRatio?: number;
 }
 
 /**
@@ -186,6 +199,10 @@ export function runContentChecks(fields: ContentFields, config: ContentChecksCon
     requireLink = true,
     hypeWords = DEFAULT_HYPE_WORDS,
     approvedHosts,
+    sourceTexts,
+    overlapFailRun = 15,
+    overlapWarnRun = 8,
+    overlapFailRatio = 0.25,
   } = config;
 
   // Word-count bands.
@@ -297,6 +314,51 @@ export function runContentChecks(fields: ContentFields, config: ContentChecksCon
     }
   }
 
+  // Verbatim overlap — the anti-plagiarism guardrail. Only when the caller supplied
+  // the cited source article TEXT. Scans blog + linkedin against the sources and
+  // reports the WORST offender (longest copied run / highest copied fraction).
+  if (sourceTexts !== undefined && sourceTexts.length > 0) {
+    const targets: Array<[keyof ContentFields, string | undefined]> = [
+      ['blog', fields.blog],
+      ['linkedin', fields.linkedin],
+    ];
+    let worstRun = 0;
+    let worstRatio = 0;
+    let worstField: keyof ContentFields | null = null;
+    let worstSample = '';
+    for (const [field, text] of targets) {
+      if (typeof text !== 'string' || !text.trim()) continue;
+      if (worstField === null) worstField = field; // at least one field present → emit (even a clean pass)
+      const o = verbatimOverlap(text, sourceTexts);
+      if (o.longestRunWords > worstRun) {
+        worstRun = o.longestRunWords;
+        worstField = field;
+        worstSample = o.sample;
+      }
+      if (o.overlapRatio > worstRatio) worstRatio = o.overlapRatio;
+    }
+    if (worstField !== null) {
+      const status: CheckStatus =
+        worstRun >= overlapFailRun || worstRatio >= overlapFailRatio
+          ? 'fail'
+          : worstRun >= overlapWarnRun
+            ? 'warn'
+            : 'pass';
+      checks.push({
+        id: 'source-overlap',
+        label: 'Original wording (not copied from sources)',
+        status,
+        detail:
+          status === 'pass'
+            ? `${worstRun}-word max run`
+            : `copies ${worstRun} consecutive words (${Math.round(worstRatio * 100)}% overlap)`,
+        ...(status !== 'pass'
+          ? { locations: [{ field: worstField, matches: worstSample ? [worstSample] : undefined }] }
+          : {}),
+      });
+    }
+  }
+
   return checks;
 }
 

package/src/components/validation/index.ts

@@ -28,6 +28,8 @@ export {
   type Band,
 } from './checks';
 
+export { verbatimOverlap, normWords, type OverlapResult } from './overlap';
+
 export { ValidationChecklist } from './ValidationChecklist';
 export type {
   ValidationChecklistProps,

package/src/components/validation/overlap.ts

@@ -0,0 +1,91 @@
+/**
+ * Verbatim-overlap detector (bd startsim-768w.18.16.1).
+ *
+ * Measures how much of a generated passage is copied VERBATIM from its source
+ * articles — the guardrail against plagiarism / SEO duplicate-content now that the
+ * writer is fed real article text. Pure + framework-free so it unit-tests in node.
+ *
+ * Method: word-shingle coverage. Both sides are normalised (lowercased, punctuation
+ * stripped, whitespace collapsed) to words; every `minRun`-word shingle of the
+ * sources goes in a set; each candidate position covered by an in-source shingle is
+ * marked "copied". From that we report the LONGEST consecutive copied run (words)
+ * and the fraction of the candidate that is copied. Short shared phrases (< minRun
+ * words) are deliberately invisible — quoting a handful of words is fine.
+ */
+
+export interface OverlapResult {
+  /** Longest run of consecutive candidate words copied verbatim from a source. */
+  longestRunWords: number;
+  /** Fraction (0–1) of candidate words that sit inside a copied run. */
+  overlapRatio: number;
+  /** The longest copied span (normalised words), for a human detail. '' when none. */
+  sample: string;
+}
+
+/** Lowercase, strip punctuation, collapse whitespace → word list. */
+export function normWords(s: string): string[] {
+  return String(s ?? '')
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s]/gu, ' ')
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+/**
+ * Verbatim overlap of `candidate` against `sources`. `minRun` (default 6) is the
+ * shingle size — the shortest copied run that counts (so ≤5-word coincidences /
+ * short quotes are ignored). Returns zeros for empty candidate or no sources.
+ */
+export function verbatimOverlap(
+  candidate: string,
+  sources: string[],
+  minRun = 6,
+): OverlapResult {
+  const cand = normWords(candidate);
+  const n = cand.length;
+  const empty: OverlapResult = { longestRunWords: 0, overlapRatio: 0, sample: '' };
+  if (n === 0 || minRun < 1) return empty;
+
+  const shingles = new Set<string>();
+  for (const src of sources ?? []) {
+    const w = normWords(src);
+    for (let i = 0; i + minRun <= w.length; i++) {
+      shingles.add(w.slice(i, i + minRun).join(' '));
+    }
+  }
+  if (shingles.size === 0) return empty;
+
+  const covered = new Array<boolean>(n).fill(false);
+  for (let i = 0; i + minRun <= n; i++) {
+    if (shingles.has(cand.slice(i, i + minRun).join(' '))) {
+      for (let j = i; j < i + minRun; j++) covered[j] = true;
+    }
+  }
+
+  let longest = 0;
+  let coveredCount = 0;
+  let cur = 0;
+  let curStart = 0;
+  let bestStart = -1;
+  let bestEnd = -1;
+  for (let i = 0; i < n; i++) {
+    if (covered[i]) {
+      coveredCount++;
+      if (cur === 0) curStart = i;
+      cur++;
+      if (cur > longest) {
+        longest = cur;
+        bestStart = curStart;
+        bestEnd = i;
+      }
+    } else {
+      cur = 0;
+    }
+  }
+
+  return {
+    longestRunWords: longest,
+    overlapRatio: coveredCount / n,
+    sample: longest > 0 ? cand.slice(bestStart, bestEnd + 1).join(' ') : '',
+  };
+}