@actuate-media/cms-admin 0.68.0 → 0.69.1

package/src/components/seo/RedirectEditorPane.tsx

@@ -0,0 +1,271 @@
+'use client'
+
+/**
+ * Inline redirect editor pane — design-parity replacement for the old
+ * `RedirectEditorDrawer` overlay. Rendered inside an `<InspectorPane>` beside
+ * the redirect rules table. Same fields, validation, and create/update save
+ * paths as the drawer; only the presentation pattern changed.
+ */
+import { useState } from 'react'
+import { Trash2 } from 'lucide-react'
+import { toast } from 'sonner'
+import {
+  createRedirectRule,
+  updateRedirectRule,
+  type RedirectRule,
+  type RedirectRulePayload,
+  type RedirectStatusCode,
+} from '../../lib/seo-service.js'
+import {
+  InspectorPaneBody,
+  InspectorPaneFooter,
+  InspectorPaneHeader,
+  InspectorPaneSection,
+} from '../ui/InspectorPane.js'
+import { Toggle } from '../ui/Toggle.js'
+
+const STATUS_CODES: { value: RedirectStatusCode; label: string }[] = [
+  { value: 301, label: '301 — Permanent' },
+  { value: 302, label: '302 — Temporary' },
+  { value: 307, label: '307 — Temporary (preserve method)' },
+  { value: 308, label: '308 — Permanent (preserve method)' },
+  { value: 410, label: '410 — Gone (no destination)' },
+]
+
+const inputCls =
+  'w-full rounded-[7px] border border-[var(--bdr)] bg-[var(--card)] px-2.5 py-1.5 text-[12.5px] text-[var(--txt)] placeholder:text-[var(--muted)] focus:border-[var(--acc)] focus:outline-none'
+
+const labelCls = 'mb-1 block text-[11.5px] font-medium text-[var(--sub)]'
+
+function normalizePath(p: string): string {
+  const t = p.trim()
+  if (!t) return ''
+  if (/^https?:\/\//i.test(t)) return t
+  return t.startsWith('/') ? t : `/${t}`
+}
+
+function PaneToggleRow({
+  label,
+  hint,
+  checked,
+  onCheckedChange,
+  variant,
+}: {
+  label: string
+  hint?: string
+  checked: boolean
+  onCheckedChange: (checked: boolean) => void
+  variant?: 'enabled'
+}) {
+  return (
+    <div className="flex items-center justify-between gap-3 py-1.5">
+      <div className="min-w-0">
+        <div className="text-[12.5px] font-medium text-[var(--txt)]">{label}</div>
+        {hint && <div className="text-[11px] text-[var(--muted)]">{hint}</div>}
+      </div>
+      <Toggle
+        checked={checked}
+        onCheckedChange={onCheckedChange}
+        variant={variant}
+        aria-label={label}
+      />
+    </div>
+  )
+}
+
+export interface RedirectEditorPaneProps {
+  /** null = create mode */
+  rule: RedirectRule | null
+  onClose: () => void
+  /** Called after a successful save so the list can refetch / close the pane. */
+  onSaved?: () => void
+  /** Ask the parent to confirm-and-delete this rule (edit mode only). */
+  onDelete?: (rule: RedirectRule) => void
+}
+
+export function RedirectEditorPane({ rule, onClose, onSaved, onDelete }: RedirectEditorPaneProps) {
+  // The parent keys this pane by rule id, so initializing from props is safe.
+  const [form, setForm] = useState<RedirectRulePayload>(() =>
+    rule
+      ? {
+          type: rule.type,
+          fromPath: rule.fromPath,
+          toPath: rule.toPath,
+          enabled: rule.enabled,
+          preserveQuery: rule.preserveQuery,
+          notes: rule.notes ?? '',
+        }
+      : {
+          type: 301,
+          fromPath: '',
+          toPath: '',
+          enabled: true,
+          preserveQuery: false,
+          notes: '',
+        },
+  )
+  const [saving, setSaving] = useState(false)
+  const [clientError, setClientError] = useState<string | null>(null)
+
+  const isGone = form.type === 410
+  const update = (patch: Partial<RedirectRulePayload>) => setForm((f) => ({ ...f, ...patch }))
+
+  async function handleSave() {
+    const fromPath = normalizePath(form.fromPath)
+    const toPath = isGone ? '' : normalizePath(form.toPath)
+    if (!fromPath) {
+      setClientError('Source path is required.')
+      return
+    }
+    if (!isGone && !toPath) {
+      setClientError('Destination is required for redirect status codes.')
+      return
+    }
+    if (!isGone && fromPath === toPath) {
+      setClientError('Source and destination cannot be identical (would create a loop).')
+      return
+    }
+    setClientError(null)
+    setSaving(true)
+    const payload: RedirectRulePayload = { ...form, fromPath, toPath }
+    const res = rule
+      ? await updateRedirectRule(rule.id, payload)
+      : await createRedirectRule(payload)
+    setSaving(false)
+    if (res.error) {
+      toast.error(res.error)
+      return
+    }
+    toast.success(rule ? 'Redirect updated.' : 'Redirect created.')
+    onSaved?.()
+  }
+
+  return (
+    <>
+      <InspectorPaneHeader onClose={onClose} closeLabel="Close redirect editor">
+        <div className="truncate text-[13.5px] font-semibold text-[var(--txt)]">
+          {rule ? 'Edit redirect' : 'New redirect'}
+        </div>
+        {rule && (
+          <div className="mt-0.5 truncate font-mono text-[11.5px] text-[var(--muted)]">
+            {rule.fromPath}
+          </div>
+        )}
+      </InspectorPaneHeader>
+
+      <InspectorPaneBody>
+        {clientError && (
+          <div className="px-4 pt-3.5">
+            <p
+              className="rounded-[7px] bg-[var(--err-l)] px-3 py-2 text-[12px] text-[var(--err)]"
+              role="alert"
+            >
+              {clientError}
+            </p>
+          </div>
+        )}
+
+        <InspectorPaneSection title="Rule">
+          <div className="mb-3">
+            <label className={labelCls} htmlFor="redir-type">
+              Status code
+            </label>
+            <select
+              id="redir-type"
+              className={inputCls}
+              value={form.type}
+              onChange={(e) => update({ type: Number(e.target.value) as RedirectStatusCode })}
+            >
+              {STATUS_CODES.map((s) => (
+                <option key={s.value} value={s.value}>
+                  {s.label}
+                </option>
+              ))}
+            </select>
+          </div>
+
+          <div className="mb-3">
+            <label className={labelCls} htmlFor="redir-from">
+              Source path
+            </label>
+            <input
+              id="redir-from"
+              className={inputCls}
+              value={form.fromPath}
+              onChange={(e) => update({ fromPath: e.target.value })}
+              placeholder="/old-path"
+            />
+          </div>
+
+          {!isGone && (
+            <div className="mb-3 last:mb-0">
+              <label className={labelCls} htmlFor="redir-to">
+                Destination
+              </label>
+              <input
+                id="redir-to"
+                className={inputCls}
+                value={form.toPath}
+                onChange={(e) => update({ toPath: e.target.value })}
+                placeholder="/new-path or https://example.com/page"
+              />
+            </div>
+          )}
+        </InspectorPaneSection>
+
+        <InspectorPaneSection title="Options">
+          <PaneToggleRow
+            label="Enabled"
+            checked={!!form.enabled}
+            onCheckedChange={(v) => update({ enabled: v })}
+            variant="enabled"
+          />
+          {!isGone && (
+            <PaneToggleRow
+              label="Preserve query string"
+              hint="Append the original query params to the destination."
+              checked={!!form.preserveQuery}
+              onCheckedChange={(v) => update({ preserveQuery: v })}
+            />
+          )}
+          <div className="mt-2">
+            <label className={labelCls} htmlFor="redir-notes">
+              Notes <span className="font-normal text-[var(--muted)]">(optional)</span>
+            </label>
+            <input
+              id="redir-notes"
+              className={inputCls}
+              value={form.notes ?? ''}
+              onChange={(e) => update({ notes: e.target.value })}
+              placeholder="Why this redirect exists"
+            />
+          </div>
+        </InspectorPaneSection>
+      </InspectorPaneBody>
+
+      <InspectorPaneFooter>
+        <div className="flex items-center gap-2">
+          {rule && onDelete && (
+            <button
+              type="button"
+              onClick={() => onDelete(rule)}
+              disabled={saving}
+              aria-label={`Delete redirect ${rule.fromPath}`}
+              className="flex h-9 w-9 shrink-0 items-center justify-center rounded-[7px] border border-[var(--bdr)] text-[var(--err)] transition-colors duration-[var(--motion-fast)] hover:bg-[var(--err-l)] focus-visible:ring-2 focus-visible:ring-[var(--ring)] focus-visible:outline-none disabled:opacity-50"
+            >
+              <Trash2 size={16} aria-hidden />
+            </button>
+          )}
+          <button
+            type="button"
+            onClick={() => void handleSave()}
+            disabled={saving}
+            className="bg-primary text-primary-foreground min-w-0 flex-1 rounded-[7px] px-3 py-2 text-[13px] font-semibold transition-colors duration-[var(--motion-fast)] hover:opacity-90 focus-visible:ring-2 focus-visible:ring-[var(--ring)] focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50"
+          >
+            {saving ? 'Saving…' : rule ? 'Save changes' : 'Create redirect'}
+          </button>
+        </div>
+      </InspectorPaneFooter>
+    </>
+  )
+}

package/src/components/seo/SeoEditorPane.tsx

@@ -523,7 +523,7 @@ export function SeoEditorPane({ entityType, entityId, onClose, onSaved }: SeoEdi
           type="button"
           onClick={() => void handleSave()}
           disabled={saving || loading || !!error}
-          className="w-full rounded-[7px] bg-[var(--acc)] px-3 py-2 text-[13px] font-semibold text-white transition-colors duration-[var(--motion-fast)] hover:opacity-90 focus-visible:ring-2 focus-visible:ring-[var(--ring)] focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50"
+          className="bg-primary text-primary-foreground w-full rounded-[7px] px-3 py-2 text-[13px] font-semibold transition-colors duration-[var(--motion-fast)] hover:opacity-90 focus-visible:ring-2 focus-visible:ring-[var(--ring)] focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50"
         >
           {saving ? 'Saving…' : 'Save Changes'}
         </button>

package/src/components/ui/DataTable.tsx

@@ -59,7 +59,7 @@ export function DataTable({
   return (
     <div className="overflow-x-auto rounded-lg border border-[var(--border)]">
       <table className="w-full text-left text-sm">
-        <thead className="border-b border-[var(--border)] bg-[var(--muted)]">
+        <thead className="bg-muted border-b border-[var(--border)]">
           <tr>
             <th className="w-10 px-4 py-3">
               <input
@@ -146,7 +146,7 @@ function RowActionsMenu({ actions, row }: { actions: RowAction[]; row: Row }) {
           <button
             key={action.key}
             onClick={() => action.onClick(row)}
-            className="rounded p-1 text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--foreground)]"
+            className="hover:bg-muted rounded p-1 text-[var(--muted-foreground)] hover:text-[var(--foreground)]"
             aria-label={action.label}
             title={action.label}
           >
@@ -155,7 +155,7 @@ function RowActionsMenu({ actions, row }: { actions: RowAction[]; row: Row }) {
         ))}
       <button
         onClick={() => setOpen((o) => !o)}
-        className="rounded p-1 hover:bg-[var(--muted)]"
+        className="hover:bg-muted rounded p-1"
         aria-label="More actions"
       >
         <MoreVerticalIcon />

package/src/components/ui/Skeleton.tsx

@@ -10,10 +10,10 @@ export function Skeleton({ variant = 'text', lines = 3, className = '' }: Skelet
   if (variant === 'card') {
     return (
       <div className={`animate-pulse rounded-lg border border-[var(--border)] p-5 ${className}`}>
-        <div className="mb-3 h-4 w-1/3 rounded bg-[var(--muted)]" />
+        <div className="bg-muted mb-3 h-4 w-1/3 rounded" />
         <div className="space-y-2">
-          <div className="h-3 w-full rounded bg-[var(--muted)]" />
-          <div className="h-3 w-2/3 rounded bg-[var(--muted)]" />
+          <div className="bg-muted h-3 w-full rounded" />
+          <div className="bg-muted h-3 w-2/3 rounded" />
         </div>
       </div>
     )
@@ -24,10 +24,10 @@ export function Skeleton({ variant = 'text', lines = 3, className = '' }: Skelet
       <div className={`animate-pulse ${className}`}>
         {Array.from({ length: lines }, (_, i) => (
           <div key={i} className="flex gap-4 border-b border-[var(--border)] px-4 py-3">
-            <div className="h-4 w-8 rounded bg-[var(--muted)]" />
-            <div className="h-4 flex-1 rounded bg-[var(--muted)]" />
-            <div className="h-4 w-20 rounded bg-[var(--muted)]" />
-            <div className="h-4 w-24 rounded bg-[var(--muted)]" />
+            <div className="bg-muted h-4 w-8 rounded" />
+            <div className="bg-muted h-4 flex-1 rounded" />
+            <div className="bg-muted h-4 w-20 rounded" />
+            <div className="bg-muted h-4 w-24 rounded" />
           </div>
         ))}
       </div>
@@ -39,7 +39,7 @@ export function Skeleton({ variant = 'text', lines = 3, className = '' }: Skelet
       {Array.from({ length: lines }, (_, i) => (
         <div
           key={i}
-          className="h-3 rounded bg-[var(--muted)]"
+          className="bg-muted h-3 rounded"
           style={{ width: `${Math.max(40, 100 - i * 15)}%` }}
         />
       ))}

package/src/components/ui/Toggle.tsx

@@ -26,7 +26,7 @@ const toggleTrack = cv(
 )
 
 const toggleThumb = cv(
-  'pointer-events-none block rounded-full bg-white shadow-[0_1px_3px_rgba(0,0,0,0.2)] transition-transform duration-[var(--motion-base)]',
+  'pointer-events-none block rounded-full bg-[var(--toggle-thumb)] shadow-[0_1px_3px_rgba(0,0,0,0.2)] transition-transform duration-[var(--motion-base)]',
   {
     variants: {
       size: {

package/src/fields/BlockBuilderField.tsx

@@ -114,7 +114,7 @@ function BlockField({ field, value, onChange }: BlockFieldProps) {
           {field.required && <span className="ml-0.5 text-[var(--destructive)]">*</span>}
         </label>
         <div className="flex items-center gap-3 rounded-md border border-dashed border-[var(--border)] p-3">
-          <div className="flex h-12 w-12 shrink-0 items-center justify-center rounded-md bg-[var(--muted)]">
+          <div className="bg-muted flex h-12 w-12 shrink-0 items-center justify-center rounded-md">
             <Image className="h-5 w-5 text-[var(--muted-foreground)]" />
           </div>
           <span className="text-sm text-[var(--muted-foreground)]">

package/src/fields/MediaField.tsx

@@ -18,7 +18,7 @@ export function MediaField({ label, value, onChange, required, helpText }: Media
 
       {value ? (
         <div className="flex items-center gap-3 rounded-md border border-[var(--border)] p-3">
-          <div className="h-16 w-16 shrink-0 rounded-md bg-[var(--muted)]" />
+          <div className="bg-muted h-16 w-16 shrink-0 rounded-md" />
           <div className="flex-1">
             <p className="text-sm font-medium">{value.filename}</p>
             <button

package/src/fields/PropInput.tsx

@@ -302,7 +302,7 @@ function LiteralDisplay({
   return (
     <div className="text-sm">
       <div className="mb-1">{label}</div>
-      <div className="rounded-md border border-dashed border-[var(--border)] bg-[var(--muted)] px-3 py-2 text-xs text-[var(--muted-foreground)]">
+      <div className="bg-muted rounded-md border border-dashed border-[var(--border)] px-3 py-2 text-xs text-[var(--muted-foreground)]">
         Fixed: <code>{String(literal)}</code>
       </div>
     </div>

package/src/hooks/useIdleLogout.ts

@@ -1,13 +1,31 @@
 'use client'
 
-import { useEffect, useRef } from 'react'
+import { useCallback, useEffect, useRef } from 'react'
 
 /** How often the idle checker wakes up to compare against the deadline. */
 const CHECK_INTERVAL_MS = 30_000
 
+export interface UseIdleLogoutOptions {
+  enabled: boolean
+  timeoutMs: number
+  onIdle: () => void
+  /**
+   * How long before the idle deadline to fire `onWarn` (so the UI can show a
+   * "you're about to be signed out" prompt). Ignored unless `onWarn` is set
+   * or when it doesn't fit inside `timeoutMs`.
+   */
+  warningMs?: number
+  /** Fired once when the session enters the warning window. */
+  onWarn?: () => void
+  /** Fired when activity resumes after `onWarn` (dismiss the prompt). */
+  onWarnCancelled?: () => void
+}
+
 /**
  * Signs the user out after `timeoutMs` of no user activity, when enabled by
- * the Settings → Security "Idle auto-logout" policy.
+ * the Settings → Security "Idle auto-logout" policy. Optionally fires a
+ * warning `warningMs` before the deadline so the UI can offer a
+ * "Stay signed in" action (the returned `stayActive` resets the clock).
  *
  * Deliberately lightweight: activity events only stamp a ref (no state, no
  * re-renders), and a single coarse interval compares the last-activity stamp
@@ -17,31 +35,53 @@ const CHECK_INTERVAL_MS = 30_000
  *
  * All listeners and the interval are torn down on unmount or when disabled.
  */
-export function useIdleLogout(options: {
-  enabled: boolean
-  timeoutMs: number
-  onIdle: () => void
-}): void {
-  const { enabled, timeoutMs } = options
-  // Keep the latest callback without re-subscribing listeners on every render.
+export function useIdleLogout(options: UseIdleLogoutOptions): { stayActive: () => void } {
+  const { enabled, timeoutMs, warningMs } = options
+  // Keep the latest callbacks without re-subscribing listeners on every render.
   const onIdleRef = useRef(options.onIdle)
   onIdleRef.current = options.onIdle
+  const onWarnRef = useRef(options.onWarn)
+  onWarnRef.current = options.onWarn
+  const onWarnCancelledRef = useRef(options.onWarnCancelled)
+  onWarnCancelledRef.current = options.onWarnCancelled
+
+  // The effect re-assigns this so `stayActive` always resets the live timer.
+  const resetRef = useRef<() => void>(() => undefined)
 
   useEffect(() => {
-    if (!enabled || timeoutMs <= 0 || typeof window === 'undefined') return
+    if (!enabled || timeoutMs <= 0 || typeof window === 'undefined') {
+      resetRef.current = () => undefined
+      return
+    }
 
     let lastActivity = Date.now()
     let fired = false
+    let warned = false
+
+    // Only meaningful when a warn callback exists and the window fits.
+    const effectiveWarningMs =
+      onWarnRef.current && warningMs && warningMs > 0 && warningMs < timeoutMs ? warningMs : 0
 
     const markActivity = () => {
       lastActivity = Date.now()
+      if (warned && !fired) {
+        warned = false
+        onWarnCancelledRef.current?.()
+      }
     }
+    resetRef.current = markActivity
 
     const checkIdle = () => {
       if (fired) return
-      if (Date.now() - lastActivity >= timeoutMs) {
+      const idleFor = Date.now() - lastActivity
+      if (idleFor >= timeoutMs) {
         fired = true
         onIdleRef.current()
+        return
+      }
+      if (effectiveWarningMs > 0 && !warned && idleFor >= timeoutMs - effectiveWarningMs) {
+        warned = true
+        onWarnRef.current?.()
       }
     }
 
@@ -64,14 +104,26 @@ export function useIdleLogout(options: {
     }
     document.addEventListener('visibilitychange', onVisibility)
 
-    const interval = window.setInterval(checkIdle, Math.min(CHECK_INTERVAL_MS, timeoutMs))
+    // Tick often enough to hit the warning window, not just the deadline.
+    const tick =
+      effectiveWarningMs > 0
+        ? Math.min(CHECK_INTERVAL_MS, timeoutMs, effectiveWarningMs)
+        : Math.min(CHECK_INTERVAL_MS, timeoutMs)
+    const interval = window.setInterval(checkIdle, tick)
 
     return () => {
+      resetRef.current = () => undefined
       for (const event of activityEvents) {
         window.removeEventListener(event, markActivity)
       }
       document.removeEventListener('visibilitychange', onVisibility)
       window.clearInterval(interval)
     }
-  }, [enabled, timeoutMs])
+  }, [enabled, timeoutMs, warningMs])
+
+  const stayActive = useCallback(() => {
+    resetRef.current()
+  }, [])
+
+  return { stayActive }
 }

package/src/layout/Header.tsx

@@ -127,8 +127,8 @@ export function Header({
                 className="hover:bg-accent flex items-center gap-1.5 rounded-lg p-1 transition-colors"
                 aria-label="Account menu"
               >
-                <div className="flex h-8 w-8 items-center justify-center rounded-full bg-[var(--acc)]">
-                  <span className="text-xs font-semibold text-white">{initial}</span>
+                <div className="bg-primary flex h-8 w-8 items-center justify-center rounded-full">
+                  <span className="text-primary-foreground text-xs font-semibold">{initial}</span>
                 </div>
                 <ChevronDown
                   className="text-muted-foreground hidden h-4 w-4 sm:block"

package/src/router/index.ts

@@ -1,6 +1,6 @@
 'use client'
 
-import { useState, useCallback, useEffect, useRef } from 'react'
+import { useState, useCallback, useEffect, useMemo, useRef } from 'react'
 
 interface RouteParams {
   [key: string]: string
@@ -14,6 +14,15 @@ function stripBase(pathname: string, basePath: string): string {
   return '/'
 }
 
+/**
+ * Parse the query string out of an admin path (`/pages/new?parent=abc`) or a
+ * raw search string (`?parent=abc`) into `URLSearchParams`. Pure helper for
+ * view components that only receive `currentPath` / `onNavigate` props.
+ */
+export function parseRouteQuery(path: string): URLSearchParams {
+  return new URLSearchParams(path.split('#')[0]!.split('?')[1] ?? '')
+}
+
 export function useAdminRouter(basePath = '/admin', serverPath = '/') {
   const [currentPath, setCurrentPath] = useState(serverPath)
   const baseRef = useRef(basePath)
@@ -21,7 +30,10 @@ export function useAdminRouter(basePath = '/admin', serverPath = '/') {
 
   useEffect(() => {
     if (typeof window !== 'undefined') {
-      const browserPath = stripBase(window.location.pathname, basePath)
+      // Include the query string so state-bearing URLs (`/pages/new?parent=x`,
+      // `/settings?tab=users`) survive hard reloads. matchRoute strips the
+      // query before matching, so `/?foo=1` still resolves to `/`.
+      const browserPath = stripBase(window.location.pathname, basePath) + window.location.search
       if (browserPath !== currentPath) {
         setCurrentPath(browserPath)
       }
@@ -30,7 +42,9 @@ export function useAdminRouter(basePath = '/admin', serverPath = '/') {
 
   useEffect(() => {
     function onPopState() {
-      setCurrentPath(stripBase(window.location.pathname, baseRef.current))
+      // Query string included for the same reason as the mount sync above —
+      // back/forward must restore deep-link state, not just the pathname.
+      setCurrentPath(stripBase(window.location.pathname, baseRef.current) + window.location.search)
     }
     window.addEventListener('popstate', onPopState)
     return () => window.removeEventListener('popstate', onPopState)
@@ -92,5 +106,12 @@ export function useAdminRouter(basePath = '/admin', serverPath = '/') {
     [currentPath],
   )
 
-  return { currentPath, navigate, matchRoute, buildHref }
+  // Raw query string of the current route (`?tab=users`), or '' when absent.
+  // Views wanting parsed params can pass it (or currentPath) to parseRouteQuery.
+  const search = useMemo(() => {
+    const queryIndex = currentPath.indexOf('?')
+    return queryIndex === -1 ? '' : currentPath.slice(queryIndex).split('#')[0]!
+  }, [currentPath])
+
+  return { currentPath, search, navigate, matchRoute, buildHref }
 }

package/src/styles/actuate-tokens.css

@@ -63,6 +63,10 @@
   --motion-fast: 0.12s;
   --motion-base: 0.18s;
   --motion-layout: 0.22s cubic-bezier(0.4, 0, 0.2, 1);
+
+  /* Controls — the toggle thumb stays white in both modes per the design
+     system (.tog-thumb { background: #fff }), tokenized for themeability. */
+  --toggle-thumb: #ffffff;
 }
 
 .dark .actuate-admin,

package/src/styles/theme.css

@@ -19,7 +19,13 @@
   --primary-foreground: #ffffff;
   --secondary: var(--acc-l);
   --secondary-foreground: var(--txt);
-  --muted: color-mix(in srgb, var(--bdr) 55%, var(--card));
+  /*
+   * IMPORTANT: never redefine --muted here. The raw design token --muted
+   * (actuate-tokens.css) is a faint TEXT color used by design-parity
+   * surfaces via text-[var(--muted)]. The muted SURFACE used by the
+   * Tailwind bg-muted utility is a separate private token below.
+   */
+  --surface-muted: color-mix(in srgb, var(--bdr) 55%, var(--card));
   --muted-foreground: var(--sub);
   --accent: var(--acc-l);
   --accent-foreground: var(--acc);
@@ -68,7 +74,7 @@
   --info-foreground: #0d0c18;
   --destructive-foreground: #0d0c18;
   --sidebar-primary-foreground: #0d0c18;
-  --muted: color-mix(in srgb, var(--bdr) 40%, var(--card));
+  --surface-muted: color-mix(in srgb, var(--bdr) 40%, var(--card));
 }
 
 @theme inline {
@@ -82,7 +88,7 @@
   --color-primary-foreground: var(--primary-foreground);
   --color-secondary: var(--secondary);
   --color-secondary-foreground: var(--secondary-foreground);
-  --color-muted: var(--muted);
+  --color-muted: var(--surface-muted);
   --color-muted-foreground: var(--muted-foreground);
   --color-accent: var(--accent);
   --color-accent-foreground: var(--accent-foreground);

package/src/views/DocumentEdit.tsx

@@ -321,7 +321,7 @@ export function DocumentEdit({
         <div className="flex items-center gap-2">
           <button
             onClick={() => setShowPreview((v) => !v)}
-            className="inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-sm text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--foreground)]"
+            className="hover:bg-muted inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-sm text-[var(--muted-foreground)] hover:text-[var(--foreground)]"
             title={showPreview ? 'Hide preview' : 'Show preview'}
           >
             {showPreview ? <EyeOff className="h-4 w-4" /> : <Eye className="h-4 w-4" />}
@@ -331,7 +331,7 @@ export function DocumentEdit({
             <>
               <button
                 onClick={() => setShowShareLink(true)}
-                className="inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-sm text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--foreground)]"
+                className="hover:bg-muted inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-sm text-[var(--muted-foreground)] hover:text-[var(--foreground)]"
                 title="Share a signed preview link for the current draft"
               >
                 <Share2 className="h-4 w-4" />
@@ -339,7 +339,7 @@ export function DocumentEdit({
               </button>
               <button
                 onClick={() => setShowVersions(true)}
-                className="inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-sm text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--foreground)]"
+                className="hover:bg-muted inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-sm text-[var(--muted-foreground)] hover:text-[var(--foreground)]"
                 title="Version history"
               >
                 <Clock className="h-4 w-4" />
@@ -347,7 +347,7 @@ export function DocumentEdit({
               </button>
               <button
                 onClick={handleDuplicate}
-                className="inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-sm text-[var(--muted-foreground)] hover:bg-[var(--muted)] hover:text-[var(--foreground)]"
+                className="hover:bg-muted inline-flex items-center gap-1.5 rounded-md px-3 py-1.5 text-sm text-[var(--muted-foreground)] hover:text-[var(--foreground)]"
                 title="Duplicate this document"
               >
                 <Copy className="h-4 w-4" />