@commonpub/layer 0.61.0 → 0.63.0

package/nuxt.config.ts

@@ -37,7 +37,7 @@ export default defineNuxtConfig({
         },
         {
           rel: 'stylesheet',
-          href: 'https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@0,9..144,300..900;1,9..144,300..900&family=Work+Sans:ital,wght@0,300..800;1,300..800&display=swap',
+          href: 'https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@0,9..144,300..900;1,9..144,300..900&family=Newsreader:ital,opsz,wght@0,6..72,300..700;1,6..72,300..700&family=Work+Sans:ital,wght@0,300..800;1,300..800&display=swap',
         },
       ],
     },
@@ -48,6 +48,8 @@ export default defineNuxtConfig({
     uiTheme('generics.css'),
     uiTheme('agora.css'),
     uiTheme('agora-dark.css'),
+    uiTheme('stoa.css'),
+    uiTheme('stoa-dark.css'),
     uiTheme('components.css'),
     uiTheme('prose.css'),
     uiTheme('layouts.css'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonpub/layer",
-  "version": "0.61.0",
+  "version": "0.63.0",
   "type": "module",
   "main": "./nuxt.config.ts",
   "files": [
@@ -54,15 +54,15 @@
     "vue-router": "^4.3.0",
     "zod": "^4.3.6",
     "@commonpub/auth": "0.8.0",
-    "@commonpub/editor": "0.7.11",
     "@commonpub/config": "0.19.0",
-    "@commonpub/protocol": "0.13.0",
+    "@commonpub/editor": "0.7.11",
+    "@commonpub/schema": "0.35.0",
+    "@commonpub/docs": "0.6.3",
     "@commonpub/learning": "0.5.2",
-    "@commonpub/server": "2.81.0",
-    "@commonpub/ui": "0.9.2",
-    "@commonpub/explainer": "0.7.15",
-    "@commonpub/schema": "0.34.0",
-    "@commonpub/docs": "0.6.3"
+    "@commonpub/server": "2.82.0",
+    "@commonpub/ui": "0.10.0",
+    "@commonpub/protocol": "0.13.0",
+    "@commonpub/explainer": "0.7.15"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",

package/server/api/public/v1/metrics/timeseries.get.ts

@@ -0,0 +1,41 @@
+import { getMetricsTimeseries, TIMESERIES_METRICS } from '@commonpub/server';
+import { z } from 'zod';
+
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+const DAY_MS = 86_400_000;
+
+const querySchema = z.object({
+  metric: z.enum(Object.keys(TIMESERIES_METRICS) as [string, ...string[]]),
+  interval: z.enum(['day', 'week', 'month']).default('day'),
+  from: z.string().regex(DAY).optional(),
+  to: z.string().regex(DAY).optional(),
+});
+
+/**
+ * GET /api/public/v1/metrics/timeseries
+ *
+ * Scope: read:analytics. Daily time-series from the `metrics_daily` rollups.
+ * `metric` is one of the registered series (users.total/new, content.total/new/
+ * views/likes/comments); `interval` buckets day|week|month. Defaults to the last
+ * 90 days. Engagement (views/likes/comments) series begin at the first rollup,
+ * surfaced via `since`.
+ */
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:analytics');
+  const parsed = querySchema.safeParse(getQuery(event));
+  if (!parsed.success) {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid query parameters', data: parsed.error.flatten() });
+  }
+  const { metric, interval } = parsed.data;
+
+  // Default to the last 90 days; clamp the span to 2 years to bound the scan.
+  const todayMs = Date.now();
+  const to = parsed.data.to ?? new Date(todayMs).toISOString().slice(0, 10);
+  let from = parsed.data.from ?? new Date(todayMs - 90 * DAY_MS).toISOString().slice(0, 10);
+  if (from > to) from = to;
+  const minFrom = new Date(new Date(`${to}T00:00:00Z`).getTime() - 730 * DAY_MS).toISOString().slice(0, 10);
+  if (from < minFrom) from = minFrom;
+
+  const db = useDB();
+  return await getMetricsTimeseries(db, { metric, interval, from, to });
+});

package/server/api/public/v1/openapi.json.get.ts

@@ -379,6 +379,9 @@ export default defineEventHandler((event) => {
       '/metrics/engagement': {
         get: { summary: 'Aggregate engagement ratios and funnels', security: [{ bearer: ['read:analytics'] }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: { type: 'object' } } } } } },
       },
+      '/metrics/timeseries': {
+        get: { summary: 'Daily time-series from rollups', security: [{ bearer: ['read:analytics'] }], parameters: [{ name: 'metric', in: 'query', required: true, schema: { type: 'string', enum: ['users.total', 'users.new', 'content.total', 'content.new', 'content.views', 'content.likes', 'content.comments'] } }, { name: 'interval', in: 'query', schema: { type: 'string', enum: ['day', 'week', 'month'] } }, { name: 'from', in: 'query', schema: { type: 'string', format: 'date' } }, { name: 'to', in: 'query', schema: { type: 'string', format: 'date' } }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: { type: 'object' } } } } } },
+      },
       '/metrics/federation': {
         get: { summary: 'Federation reach (opt-in; read:federation)', security: [{ bearer: ['read:federation'] }], parameters: [{ name: 'limit', in: 'query', schema: { type: 'integer' } }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: { type: 'object' } } } }, '404': { description: 'Federation reach metrics not enabled', content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } } } } },
       },

package/server/plugins/metrics-rollup.ts

@@ -0,0 +1,54 @@
+/**
+ * Daily analytics rollup worker (Phase 3).
+ *
+ * When `features.publicApi` is on, snapshots aggregate metrics into
+ * `metrics_daily` so `GET /api/public/v1/metrics/timeseries` has history. On the
+ * first ever run (empty table) it backfills the deterministic count-based series
+ * from timestamps. Runs are idempotent (upsert per day), so the periodic
+ * interval just refreshes today's row. Aggregates only — no per-user data.
+ */
+import { runDailyRollup, backfillMetricsDaily } from '@commonpub/server';
+import { metricsDaily } from '@commonpub/schema';
+
+const ROLLUP_INTERVAL_MS = 6 * 60 * 60 * 1000; // every 6h; refreshes today's snapshot
+
+export default defineNitroPlugin((nitro) => {
+  if (process.env.NODE_ENV === 'test') return;
+
+  let interval: ReturnType<typeof setInterval> | null = null;
+
+  const startupTimer = setTimeout(() => {
+    try {
+      const config = useConfig();
+      if (!config.features.publicApi) return; // no public API ⇒ no rollups needed
+      console.log(`[metrics-rollup] worker started (interval: ${ROLLUP_INTERVAL_MS}ms)`);
+      runRollup();
+      interval = setInterval(runRollup, ROLLUP_INTERVAL_MS);
+    } catch (err) {
+      console.error('[metrics-rollup] failed to start:', err instanceof Error ? err.message : err);
+    }
+  }, 15_000); // stagger after federation/registry workers
+
+  async function runRollup(): Promise<void> {
+    try {
+      const db = useDB();
+      const today = new Date().toISOString().slice(0, 10); // YYYY-MM-DD (UTC)
+      const [existing] = await db.select({ id: metricsDaily.id }).from(metricsDaily).limit(1);
+      if (!existing) {
+        const n = await backfillMetricsDaily(db);
+        console.log(`[metrics-rollup] backfilled ${n} historical rows`);
+      }
+      await runDailyRollup(db, today);
+    } catch (err) {
+      console.error('[metrics-rollup] run error:', err instanceof Error ? err.message : err);
+    }
+  }
+
+  nitro.hooks.hook('close', () => {
+    clearTimeout(startupTimer);
+    if (interval) {
+      clearInterval(interval);
+      interval = null;
+    }
+  });
+});

package/server/utils/instanceTheme.ts

@@ -29,8 +29,12 @@ let cacheTime = 0;
 async function loadThemeState(): Promise<CachedThemeState> {
   const db = useDB();
 
-  // 1. Default theme ID
-  let defaultTheme = 'base';
+  // 1. Default theme ID.
+  // Fallback is 'stoa' — the default CommonPub theme for fresh installs and any
+  // instance that has NOT explicitly set `theme.default` in the DB. Instances
+  // with an explicit setting (e.g. commonpub.io=agora-dark, branded instances)
+  // are unaffected; this only changes what an unconfigured instance shows.
+  let defaultTheme = 'stoa';
   try {
     const [row] = await db
       .select({ value: instanceSettings.value })

package/theme/stoa-dark.css

@@ -0,0 +1,153 @@
+@layer commonpub {
+/* ===========================================
+   CommonPub Stoa Theme — Dark
+   "The same walk, by lamplight."
+
+   Deep warm-black paper, brighter moss accent,
+   the same Fraunces / Newsreader / Work Sans
+   type and soft rounded geometry as Stoa Light.
+   Component overrides are shared from stoa.css
+   (both data-theme values are targeted there).
+   =========================================== */
+
+[data-theme="stoa-dark"] {
+  /* === SURFACES (warm near-black) === */
+  --bg: #15130d;
+  --surface: #1f1c14;
+  --surface2: #28241a;
+  --surface3: #332d20;
+
+  --color-surface: var(--surface);
+  --color-surface-alt: var(--surface2);
+  --color-surface-raised: var(--surface);
+  --color-surface-overlay: rgba(0, 0, 0, 0.6);
+  --color-surface-overlay-light: rgba(0, 0, 0, 0.45);
+  --color-surface-scrim: rgba(21, 19, 13, 0.8);
+  --color-surface-hover: var(--surface2);
+  --color-bg-subtle: var(--bg);
+
+  /* === TEXT (warm paper ink) === */
+  --text: #f1ebda;
+  --text-dim: #bcb4a2;
+  --text-faint: #8d8675;
+
+  --color-text: var(--text);
+  --color-text-secondary: var(--text-dim);
+  --color-text-muted: var(--text-faint);
+  --color-text-inverse: #15130d;
+
+  /* === BORDERS (warm hairlines) === */
+  --border: rgba(241, 235, 218, 0.24);
+  --border2: rgba(241, 235, 218, 0.13);
+
+  --color-border: var(--border2);
+  --color-border-strong: var(--border);
+  --color-border-focus: var(--accent);
+
+  /* === ACCENT (brighter moss for dark) === */
+  --accent: #5aa784;
+  --accent-bg: rgba(90, 167, 132, 0.14);
+  --accent-bg-strong: rgba(90, 167, 132, 0.24);
+  --accent-bg-heavy: rgba(90, 167, 132, 0.42);
+  --accent-bg-solid: rgba(90, 167, 132, 0.6);
+  --accent-border: rgba(90, 167, 132, 0.34);
+  --accent-focus-ring: 0 0 0 3px rgba(90, 167, 132, 0.2);
+
+  --color-primary: var(--accent);
+  --color-primary-hover: #79c4a0;
+  --color-primary-text: #0f140f;
+  --color-on-primary: #0f140f;
+  --color-accent: var(--accent);
+  --color-accent-hover: #79c4a0;
+  --color-accent-text: #0f140f;
+  --color-on-accent: #0f140f;
+  --color-accent-bg: var(--accent-bg);
+  --color-accent-border: var(--accent-border);
+
+  /* === SEMANTIC COLORS (dark warm) === */
+  --green: #5aa784;
+  --green-bg: rgba(90, 167, 132, 0.14);
+  --green-border: rgba(90, 167, 132, 0.32);
+
+  --yellow: #d6a259;
+  --yellow-bg: rgba(214, 162, 89, 0.13);
+  --yellow-border: rgba(214, 162, 89, 0.3);
+
+  --red: #d07c69;
+  --red-bg: rgba(208, 124, 105, 0.13);
+  --red-border: rgba(208, 124, 105, 0.3);
+
+  --purple: #a98cbe;
+  --purple-bg: rgba(169, 140, 190, 0.13);
+  --purple-border: rgba(169, 140, 190, 0.3);
+
+  --teal: #5fb3a6;
+  --teal-bg: rgba(95, 179, 166, 0.13);
+  --teal-border: rgba(95, 179, 166, 0.3);
+
+  --pink: #cd8aa0;
+  --pink-bg: rgba(205, 138, 160, 0.13);
+  --pink-border: rgba(205, 138, 160, 0.3);
+
+  --color-success: var(--green);
+  --color-warning: var(--yellow);
+  --color-error: var(--red);
+  --color-info: #82a2c0;
+  --color-success-bg: var(--green-bg);
+  --color-warning-bg: var(--yellow-bg);
+  --color-error-bg: var(--red-bg);
+  --color-info-bg: rgba(130, 162, 192, 0.13);
+
+  /* === OVERLAYS === */
+  --color-badge-overlay: rgba(241, 235, 218, 0.85);
+
+  /* === INTERACTIVE === */
+  --color-link: #79c4a0;
+  --color-link-hover: #9bd6bb;
+
+  /* === TYPOGRAPHY (same as light) === */
+  --font-sans: 'Work Sans', system-ui, -apple-system, sans-serif;
+  --font-mono: 'JetBrains Mono', ui-monospace, monospace;
+  --font-display: 'Fraunces', Georgia, 'Times New Roman', serif;
+  --font-read: 'Newsreader', Georgia, 'Times New Roman', serif;
+
+  --font-heading: var(--font-display);
+  --font-body: var(--font-sans);
+
+  --text-label: 0.6875rem;
+
+  --leading-tight: 1.16;
+  --leading-snug: 1.36;
+  --leading-normal: 1.62;
+  --leading-relaxed: 1.78;
+
+  --tracking-tight: -0.015em;
+  --tracking-normal: 0;
+  --tracking-wide: 0.04em;
+  --tracking-wider: 0.08em;
+  --tracking-widest: 0.14em;
+
+  /* === SHAPE (same rounded geometry) === */
+  --radius: 12px;
+  --radius-sm: 8px;
+  --radius-md: 14px;
+  --radius-lg: 20px;
+  --radius-xl: 28px;
+  --radius-2xl: 28px;
+
+  /* === SHADOWS (deeper for dark) === */
+  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.4);
+  --shadow-md: 0 2px 8px rgba(0, 0, 0, 0.45), 0 10px 24px rgba(0, 0, 0, 0.32);
+  --shadow-lg: 0 16px 40px rgba(0, 0, 0, 0.52), 0 4px 12px rgba(0, 0, 0, 0.36);
+  --shadow-xl: 0 26px 60px rgba(0, 0, 0, 0.6), 0 8px 18px rgba(0, 0, 0, 0.4);
+  --shadow-accent: 0 6px 20px rgba(90, 167, 132, 0.4);
+
+  /* === TRANSITIONS === */
+  --transition-fast: 140ms cubic-bezier(0.22, 1, 0.36, 1);
+  --transition-default: 200ms cubic-bezier(0.22, 1, 0.36, 1);
+  --transition-slow: 320ms cubic-bezier(0.4, 0, 0.2, 1);
+
+  /* === FOCUS === */
+  --focus-ring: 0 0 0 3px rgba(90, 167, 132, 0.28);
+}
+} /* end @layer commonpub — token overrides only */

package/theme/stoa.css

@@ -0,0 +1,361 @@
+@layer commonpub {
+/* ===========================================
+   CommonPub Stoa Theme — Light
+   "A covered walk for thinking in public."
+
+   Warm paper grounds, moss-green accent,
+   Fraunces display + Newsreader reading serif,
+   Work Sans UI. Soft rounded corners, gentle
+   blurred lifts (not the brutalist offset
+   shadow), hairline warm borders. A calm,
+   bookish, daylight aesthetic.
+   =========================================== */
+
+[data-theme="stoa"] {
+  /* === SURFACES (warm paper) === */
+  --bg: #f7f3ea;
+  --surface: #fffdf6;
+  --surface2: #eee8d9;
+  --surface3: #e4ddcb;
+
+  --color-surface: var(--surface);
+  --color-surface-alt: var(--surface2);
+  --color-surface-raised: var(--surface);
+  --color-surface-overlay: rgba(42, 38, 32, 0.5);
+  --color-surface-overlay-light: rgba(42, 38, 32, 0.4);
+  --color-surface-scrim: rgba(247, 243, 234, 0.78);
+  --color-surface-hover: var(--surface2);
+  --color-bg-subtle: var(--bg);
+
+  /* === TEXT (ink gradations) === */
+  --text: #2a2620;
+  --text-dim: #5a5247;
+  --text-faint: #8a8273;
+
+  --color-text: var(--text);
+  --color-text-secondary: var(--text-dim);
+  --color-text-muted: var(--text-faint);
+  --color-text-inverse: #fdfbf3;
+
+  /* === BORDERS (warm hairlines) === */
+  --border: rgba(42, 38, 32, 0.22);
+  --border2: rgba(42, 38, 32, 0.12);
+
+  --color-border: var(--border2);
+  --color-border-strong: var(--border);
+  --color-border-focus: var(--accent);
+
+  /* === ACCENT (moss green) === */
+  --accent: #3c8262;
+  --accent-bg: rgba(60, 130, 98, 0.12);
+  --accent-bg-strong: rgba(60, 130, 98, 0.2);
+  --accent-bg-heavy: rgba(60, 130, 98, 0.4);
+  --accent-bg-solid: rgba(60, 130, 98, 0.6);
+  --accent-border: rgba(60, 130, 98, 0.32);
+  --accent-focus-ring: 0 0 0 3px rgba(60, 130, 98, 0.18);
+
+  --color-primary: var(--accent);
+  --color-primary-hover: #2b6147;
+  --color-primary-text: #fdfbf3;
+  --color-on-primary: #fdfbf3;
+  --color-accent: var(--accent);
+  --color-accent-hover: #2b6147;
+  --color-accent-text: #fdfbf3;
+  --color-on-accent: #fdfbf3;
+  --color-accent-bg: var(--accent-bg);
+  --color-accent-border: var(--accent-border);
+
+  /* === SEMANTIC COLORS (warm) === */
+  --green: #3c8262;
+  --green-bg: rgba(60, 130, 98, 0.12);
+  --green-border: rgba(60, 130, 98, 0.3);
+
+  --yellow: #bd863a;
+  --yellow-bg: rgba(189, 134, 58, 0.1);
+  --yellow-border: rgba(189, 134, 58, 0.28);
+
+  --red: #b25a47;
+  --red-bg: rgba(178, 90, 71, 0.1);
+  --red-border: rgba(178, 90, 71, 0.28);
+
+  --purple: #7b6190;
+  --purple-bg: rgba(123, 97, 144, 0.1);
+  --purple-border: rgba(123, 97, 144, 0.28);
+
+  --teal: #3f8a80;
+  --teal-bg: rgba(63, 138, 128, 0.1);
+  --teal-border: rgba(63, 138, 128, 0.28);
+
+  --pink: #b0697f;
+  --pink-bg: rgba(176, 105, 127, 0.1);
+  --pink-border: rgba(176, 105, 127, 0.28);
+
+  /* Rank colors (warm-toned for contests) */
+  --gold: #c1923a;
+  --silver: #9a948a;
+  --bronze: #a8704a;
+
+  --color-success: var(--green);
+  --color-warning: var(--yellow);
+  --color-error: var(--red);
+  --color-info: #5d7e9c;
+  --color-success-bg: var(--green-bg);
+  --color-warning-bg: var(--yellow-bg);
+  --color-error-bg: var(--red-bg);
+  --color-info-bg: rgba(93, 126, 156, 0.1);
+
+  /* === OVERLAYS === */
+  --color-badge-overlay: rgba(42, 38, 32, 0.72);
+
+  /* === INTERACTIVE === */
+  --color-link: #2b6147;
+  --color-link-hover: #1f4a35;
+
+  /* === TYPOGRAPHY === */
+  --font-sans: 'Work Sans', system-ui, -apple-system, sans-serif;
+  --font-mono: 'JetBrains Mono', ui-monospace, monospace;
+  --font-display: 'Fraunces', Georgia, 'Times New Roman', serif;
+  --font-read: 'Newsreader', Georgia, 'Times New Roman', serif;
+
+  --font-heading: var(--font-display);
+  --font-body: var(--font-sans);
+
+  --text-label: 0.6875rem; /* 11px monospace UI labels */
+
+  --leading-tight: 1.16;
+  --leading-snug: 1.36;
+  --leading-normal: 1.62;
+  --leading-relaxed: 1.78;
+
+  --tracking-tight: -0.015em;
+  --tracking-normal: 0;
+  --tracking-wide: 0.04em;
+  --tracking-wider: 0.08em;
+  --tracking-widest: 0.14em;
+
+  /* === SHAPE (soft, rounded — Stoa's signature departure) === */
+  --radius: 12px;
+  --radius-sm: 8px;
+  --radius-md: 14px;
+  --radius-lg: 20px;
+  --radius-xl: 28px;
+  --radius-2xl: 28px;
+
+  /* === SHADOWS (soft blurred lifts, not offset) === */
+  --shadow-sm: 0 1px 2px rgba(38, 32, 24, 0.06), 0 1px 1px rgba(38, 32, 24, 0.04);
+  --shadow-md: 0 2px 6px rgba(38, 32, 24, 0.06), 0 8px 20px rgba(38, 32, 24, 0.06);
+  --shadow-lg: 0 12px 34px rgba(38, 32, 24, 0.11), 0 3px 10px rgba(38, 32, 24, 0.06);
+  --shadow-xl: 0 22px 50px rgba(38, 32, 24, 0.14), 0 6px 16px rgba(38, 32, 24, 0.08);
+  --shadow-accent: 0 6px 18px rgba(60, 130, 98, 0.28);
+
+  /* === TRANSITIONS (gentle, springy) === */
+  --transition-fast: 140ms cubic-bezier(0.22, 1, 0.36, 1);
+  --transition-default: 200ms cubic-bezier(0.22, 1, 0.36, 1);
+  --transition-slow: 320ms cubic-bezier(0.4, 0, 0.2, 1);
+
+  /* === FOCUS (moss glow) === */
+  --focus-ring: 0 0 0 3px rgba(60, 130, 98, 0.22);
+}
+} /* end @layer commonpub — token overrides only */
+
+
+/* ═══════════════════════════════════════════
+   COMPONENT OVERRIDES (outside @layer so they
+   beat Vue scoped styles). Shared by the light
+   AND dark variants — both data-theme values
+   are targeted so stoa-dark inherits them.
+   ═══════════════════════════════════════════ */
+
+/* Display serif for headings */
+[data-theme="stoa"] h1,
+[data-theme="stoa"] h2,
+[data-theme="stoa"] h3,
+[data-theme="stoa-dark"] h1,
+[data-theme="stoa-dark"] h2,
+[data-theme="stoa-dark"] h3,
+[data-theme="stoa"] .cpub-section-title-lg,
+[data-theme="stoa"] .cpub-section-title-sm,
+[data-theme="stoa-dark"] .cpub-section-title-lg,
+[data-theme="stoa-dark"] .cpub-section-title-sm,
+[data-theme="stoa"] .admin-page-title,
+[data-theme="stoa-dark"] .admin-page-title {
+  font-family: var(--font-display);
+}
+
+/* Wordmark + brand use the display serif */
+[data-theme="stoa"] .cpub-logo-name,
+[data-theme="stoa-dark"] .cpub-logo-name,
+[data-theme="stoa"] .admin-brand,
+[data-theme="stoa-dark"] .admin-brand {
+  font-family: var(--font-display);
+  font-weight: 600;
+  letter-spacing: -0.01em;
+}
+
+[data-theme="stoa"] .cpub-logo-bracket,
+[data-theme="stoa-dark"] .cpub-logo-bracket {
+  color: var(--accent);
+}
+
+/* Focus: moss glow instead of a hard outline */
+[data-theme="stoa"] :focus-visible,
+[data-theme="stoa-dark"] :focus-visible {
+  outline: none;
+  box-shadow: var(--focus-ring);
+}
+
+/* Buttons: gentle lift on hover */
+[data-theme="stoa"] .cpub-btn,
+[data-theme="stoa-dark"] .cpub-btn {
+  transition: transform var(--transition-fast), box-shadow var(--transition-fast), background var(--transition-fast);
+}
+
+[data-theme="stoa"] .cpub-btn:hover,
+[data-theme="stoa-dark"] .cpub-btn:hover {
+  transform: translateY(-1px);
+  box-shadow: var(--shadow-sm);
+}
+
+[data-theme="stoa"] .cpub-btn:active,
+[data-theme="stoa-dark"] .cpub-btn:active {
+  transform: translateY(0);
+  box-shadow: none;
+}
+
+[data-theme="stoa"] .cpub-btn-primary,
+[data-theme="stoa-dark"] .cpub-btn-primary {
+  background: var(--accent);
+  border-color: var(--accent);
+  color: var(--color-on-accent);
+}
+
+[data-theme="stoa"] .cpub-btn-primary:hover,
+[data-theme="stoa-dark"] .cpub-btn-primary:hover {
+  background: var(--color-primary-hover);
+  box-shadow: var(--shadow-accent);
+  transform: translateY(-1px);
+}
+
+[data-theme="stoa"] .cpub-btn-ghost,
+[data-theme="stoa-dark"] .cpub-btn-ghost {
+  color: var(--accent);
+  border-color: transparent;
+}
+
+[data-theme="stoa"] .cpub-btn-ghost:hover,
+[data-theme="stoa-dark"] .cpub-btn-ghost:hover {
+  background: var(--accent-bg);
+}
+
+/* Cards: soft lift on hover */
+[data-theme="stoa"] .cpub-content-card,
+[data-theme="stoa-dark"] .cpub-content-card,
+[data-theme="stoa"] .cpub-sb-card,
+[data-theme="stoa-dark"] .cpub-sb-card,
+[data-theme="stoa"] .cpub-stat-card,
+[data-theme="stoa-dark"] .cpub-stat-card {
+  transition: transform var(--transition-fast), box-shadow var(--transition-fast), border-color var(--transition-fast);
+}
+
+[data-theme="stoa"] .cpub-content-card:hover,
+[data-theme="stoa-dark"] .cpub-content-card:hover {
+  transform: translateY(-2px);
+  box-shadow: var(--shadow-md);
+}
+
+/* Card titles use the display serif */
+[data-theme="stoa"] .cpub-content-card h3,
+[data-theme="stoa-dark"] .cpub-content-card h3,
+[data-theme="stoa"] .cpub-card-title,
+[data-theme="stoa-dark"] .cpub-card-title {
+  font-family: var(--font-display);
+  font-weight: 600;
+}
+
+/* Inputs: glow focus */
+[data-theme="stoa"] .cpub-input:focus,
+[data-theme="stoa-dark"] .cpub-input:focus,
+[data-theme="stoa"] .cpub-textarea:focus,
+[data-theme="stoa-dark"] .cpub-textarea:focus,
+[data-theme="stoa"] .cpub-select:focus,
+[data-theme="stoa-dark"] .cpub-select:focus {
+  border-color: var(--accent);
+  box-shadow: var(--focus-ring);
+  outline: none;
+}
+
+/* Links: moss with a soft underline */
+[data-theme="stoa"] a:not(.cpub-btn):not(.cpub-topbar-link):not(.cpub-footer-link):not(.admin-nav-link),
+[data-theme="stoa-dark"] a:not(.cpub-btn):not(.cpub-topbar-link):not(.cpub-footer-link):not(.admin-nav-link) {
+  text-decoration-color: var(--accent-border);
+  text-underline-offset: 2px;
+}
+
+[data-theme="stoa"] .cpub-topbar-link.router-link-active,
+[data-theme="stoa-dark"] .cpub-topbar-link.router-link-active {
+  color: var(--accent);
+}
+
+/* Prose: Newsreader reading serif, moss blockquote */
+[data-theme="stoa"] .cpub-prose,
+[data-theme="stoa-dark"] .cpub-prose {
+  font-family: var(--font-read);
+  font-size: 1.0625rem;
+  line-height: var(--leading-relaxed);
+}
+
+[data-theme="stoa"] .cpub-prose h1,
+[data-theme="stoa"] .cpub-prose h2,
+[data-theme="stoa"] .cpub-prose h3,
+[data-theme="stoa"] .cpub-prose h4,
+[data-theme="stoa-dark"] .cpub-prose h1,
+[data-theme="stoa-dark"] .cpub-prose h2,
+[data-theme="stoa-dark"] .cpub-prose h3,
+[data-theme="stoa-dark"] .cpub-prose h4 {
+  font-family: var(--font-display);
+}
+
+[data-theme="stoa"] .cpub-prose blockquote,
+[data-theme="stoa-dark"] .cpub-prose blockquote {
+  border-left-color: var(--accent);
+  background: var(--accent-bg);
+}
+
+[data-theme="stoa"] .cpub-prose a,
+[data-theme="stoa-dark"] .cpub-prose a {
+  color: var(--accent);
+  text-decoration-color: var(--accent-border);
+}
+
+/* Admin: active nav uses moss */
+[data-theme="stoa"] .admin-nav-link.router-link-exact-active,
+[data-theme="stoa-dark"] .admin-nav-link.router-link-exact-active {
+  color: var(--accent);
+  background: var(--accent-bg);
+}
+
+[data-theme="stoa"] .cpub-footer-col-title,
+[data-theme="stoa-dark"] .cpub-footer-col-title {
+  letter-spacing: var(--tracking-widest);
+}
+
+
+/* ═══════════════════════════════════════════
+   LOGO SWITCH
+   Stoa shares Agora's Town Square mark (hide
+   the Classic logo, show the Agora wordmark +
+   hero aside).
+   ═══════════════════════════════════════════ */
+
+[data-theme="stoa"] .cpub-logo-classic,
+[data-theme="stoa-dark"] .cpub-logo-classic { display: none !important; }
+
+[data-theme="stoa"] .cpub-logo-agora,
+[data-theme="stoa-dark"] .cpub-logo-agora { display: flex !important; }
+
+[data-theme="stoa"] .cpub-hero-logo-aside,
+[data-theme="stoa-dark"] .cpub-hero-logo-aside {
+  display: flex !important;
+  align-items: center;
+  justify-content: center;
+}

package/utils/themeConfig.ts

@@ -17,6 +17,8 @@ export const THEME_TO_FAMILY: Record<string, string> = {
   generics: 'generics',
   agora: 'agora',
   'agora-dark': 'agora',
+  stoa: 'stoa',
+  'stoa-dark': 'stoa',
 };
 
 /** Light/dark variants for each family */
@@ -24,6 +26,7 @@ export const FAMILY_VARIANTS: Record<string, { light: string; dark: string }> =
   classic: { light: 'base', dark: 'dark' },
   agora: { light: 'agora', dark: 'agora-dark' },
   generics: { light: 'generics', dark: 'generics' },
+  stoa: { light: 'stoa', dark: 'stoa-dark' },
 };
 
 /** Whether a theme ID is a dark theme */
@@ -33,6 +36,8 @@ export const IS_DARK: Record<string, boolean> = {
   generics: true,
   agora: false,
   'agora-dark': true,
+  stoa: false,
+  'stoa-dark': true,
 };
 
 /** All valid theme IDs */