@commonpub/layer 0.3.22 → 0.3.24

package/README.md

@@ -0,0 +1,95 @@
+# @commonpub/layer
+
+Shared Nuxt 3 layer that provides the complete CommonPub application — pages, components, composables, server routes, plugins, and theme CSS. This is the primary way to build a CommonPub-powered site.
+
+## Installation
+
+```bash
+npm install @commonpub/layer
+```
+
+In your `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  extends: ['@commonpub/layer'],
+});
+```
+
+## Configuration
+
+Create a `commonpub.config.ts` in your project root:
+
+```ts
+import { defineCommonPubConfig } from '@commonpub/config';
+
+export default defineCommonPubConfig({
+  instance: {
+    name: 'My Community',
+    domain: 'example.com',
+    contentTypes: ['project', 'article', 'blog', 'explainer'],
+  },
+  features: {
+    content: true,
+    social: true,
+    hubs: true,
+    docs: true,
+    learning: true,
+    admin: true,
+  },
+  auth: {
+    methods: ['email'],
+  },
+});
+```
+
+Create `server/utils/config.ts` to load the config on the server side. See `apps/shell/server/utils/config.ts` for a complete example with environment variable overrides.
+
+## What's Included
+
+### Pages (20+ routes)
+
+Content CRUD, hub feeds, learning paths, docs sites, admin panel, federation management, user profiles, messaging, notifications, search, and more.
+
+### Components (30+)
+
+Content editor (`CpubEditor`), content cards, author rows, comment sections, engagement bars, federation UI, notification items, message threads, and more.
+
+### Composables (19)
+
+`useAuth`, `useFeatures`, `useBlockEditor`, `useContentSave`, `useEngagement`, `useFederation`, `useMessages`, `useNotifications`, `useTheme`, and more.
+
+### Server
+
+API routes for all CommonPub features, auth middleware, federation endpoints, and Nitro plugins.
+
+### Theme
+
+CSS custom properties with 4 built-in themes (base, deepwood, hackbuild, deveco). Override with your own `theme.css`.
+
+## Customization
+
+The layer is designed to be extended:
+
+- **Override components**: Place a component with the same name in your app's `components/` directory
+- **Override pages**: Place a page at the same route path in your app's `pages/` directory
+- **Custom theme**: Add CSS custom property overrides in your app's assets
+- **Feature flags**: Enable/disable features via `commonpub.config.ts`
+
+## Dependencies
+
+This layer depends on all `@commonpub/*` packages:
+
+- `@commonpub/schema` — Database tables and validators
+- `@commonpub/config` — Configuration and feature flags
+- `@commonpub/server` — Business logic
+- `@commonpub/auth` — Authentication
+- `@commonpub/protocol` — ActivityPub federation
+- `@commonpub/ui` — Headless UI components
+- `@commonpub/editor` — TipTap block editor
+- `@commonpub/docs` — Documentation module
+- `@commonpub/learning` — Learning path engine
+
+## License
+
+AGPL-3.0-or-later

package/components/CommentSection.vue

@@ -161,7 +161,7 @@ async function deleteComment(id: string): Promise<void> {
               {{ new Date(comment.createdAt).toLocaleDateString('en-US', { month: 'short', day: 'numeric' }) }}
             </time>
           </div>
-          <p class="cpub-comment-text">{{ comment.content }}</p>
+          <p class="cpub-comment-text"><MentionText :text="comment.content" /></p>
           <button
             v-if="user?.id === comment.author?.id"
             class="cpub-comment-delete"

package/components/MessageThread.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-defineProps<{
+const props = defineProps<{
   messages: Array<{
     id: string;
     senderId: string;
@@ -17,6 +17,19 @@ const emit = defineEmits<{
 }>();
 
 const newMessage = ref('');
+const messagesContainer = ref<HTMLElement | null>(null);
+
+function scrollToBottom(): void {
+  nextTick(() => {
+    if (messagesContainer.value) {
+      messagesContainer.value.scrollTop = messagesContainer.value.scrollHeight;
+    }
+  });
+}
+
+// Auto-scroll when messages change (new message arrives or initial load)
+watch(() => props.messages.length, scrollToBottom);
+onMounted(scrollToBottom);
 
 function handleSend(): void {
   if (!newMessage.value.trim()) return;
@@ -27,7 +40,7 @@ function handleSend(): void {
 
 <template>
   <div class="cpub-thread">
-    <div class="cpub-thread-messages">
+    <div ref="messagesContainer" class="cpub-thread-messages">
       <div
         v-for="msg in messages"
         :key="msg.id"

package/composables/useFeatures.ts

@@ -11,6 +11,7 @@ export interface FeatureFlags {
   explainers: boolean;
   federation: boolean;
   admin: boolean;
+  emailNotifications: boolean;
 }
 
 export function useFeatures() {
@@ -29,5 +30,6 @@ export function useFeatures() {
     explainers: computed(() => flags.explainers),
     federation: computed(() => flags.federation),
     admin: computed(() => flags.admin),
+    emailNotifications: computed(() => flags.emailNotifications),
   };
 }

package/nuxt.config.ts

@@ -67,6 +67,7 @@ export default defineNuxtConfig({
         federation: false,
         federateHubs: false,
         admin: false,
+        emailNotifications: false,
       },
       contentTypes: 'project,article,blog,explainer',
       contestCreation: 'admin',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonpub/layer",
-  "version": "0.3.22",
+  "version": "0.3.24",
   "type": "module",
   "main": "./nuxt.config.ts",
   "files": [
@@ -45,14 +45,14 @@
     "vue-router": "^4.3.0",
     "zod": "^4.3.6",
     "@commonpub/auth": "0.5.0",
-    "@commonpub/config": "0.7.0",
     "@commonpub/docs": "0.5.2",
+    "@commonpub/protocol": "0.9.5",
     "@commonpub/editor": "0.5.0",
-    "@commonpub/learning": "0.5.0",
-    "@commonpub/protocol": "0.9.4",
     "@commonpub/schema": "0.8.12",
-    "@commonpub/server": "2.14.0",
-    "@commonpub/ui": "0.7.1"
+    "@commonpub/server": "2.15.0",
+    "@commonpub/config": "0.7.1",
+    "@commonpub/ui": "0.7.1",
+    "@commonpub/learning": "0.5.0"
   },
   "scripts": {}
 }

package/pages/hubs/[slug]/posts/[postId].vue

@@ -235,7 +235,7 @@ useSeoMeta({
           <span class="cpub-post-sep">&middot;</span>
           <time class="cpub-post-time">{{ formatDate(reply.createdAt) }}</time>
         </div>
-        <div class="cpub-reply-content">{{ reply.content }}</div>
+        <div class="cpub-reply-content"><MentionText :text="reply.content" /></div>
         <div class="cpub-reply-actions">
           <button v-if="isAuthenticated && hub?.currentUserRole && !post.isLocked" class="cpub-reply-btn" @click="replyingTo = reply.id; replyContent = `@${reply.author?.username} `">
             <i class="fa-solid fa-reply"></i> Reply
@@ -254,7 +254,7 @@ useSeoMeta({
               <span class="cpub-post-sep">&middot;</span>
               <time class="cpub-post-time">{{ formatDate(child.createdAt) }}</time>
             </div>
-            <div class="cpub-reply-content">{{ child.content }}</div>
+            <div class="cpub-reply-content"><MentionText :text="child.content" /></div>
           </div>
         </div>
       </div>

package/pages/messages/index.vue

@@ -34,6 +34,36 @@ const newRecipients = ref<string[]>([]);
 const newMessage = ref('');
 
 const msgError = ref('');
+const dialogRef = ref<HTMLElement | null>(null);
+const triggerRef = ref<HTMLElement | null>(null);
+
+// WCAG focus trap: trap Tab inside dialog, restore focus on close
+watch(showNewDialog, async (open) => {
+  if (open) {
+    await nextTick();
+    const firstInput = dialogRef.value?.querySelector<HTMLElement>('input, textarea, button:not([disabled])');
+    firstInput?.focus();
+  } else {
+    triggerRef.value?.focus();
+  }
+});
+
+function handleDialogKeydown(e: KeyboardEvent): void {
+  if (e.key !== 'Tab' || !dialogRef.value) return;
+  const focusable = dialogRef.value.querySelectorAll<HTMLElement>(
+    'input:not([disabled]), textarea:not([disabled]), button:not([disabled]), [tabindex]:not([tabindex="-1"])',
+  );
+  if (focusable.length === 0) return;
+  const first = focusable[0]!;
+  const last = focusable[focusable.length - 1]!;
+  if (e.shiftKey && document.activeElement === first) {
+    e.preventDefault();
+    last.focus();
+  } else if (!e.shiftKey && document.activeElement === last) {
+    e.preventDefault();
+    first.focus();
+  }
+}
 
 function addRecipient(): void {
   const val = newRecipientInput.value.trim();
@@ -79,14 +109,14 @@ async function startConversation(): Promise<void> {
   <div class="cpub-messages-page">
     <div class="cpub-messages-header">
       <h1 class="cpub-section-title-lg">Messages</h1>
-      <button class="cpub-btn cpub-btn-sm cpub-btn-primary" @click="showNewDialog = true">
+      <button ref="triggerRef" class="cpub-btn cpub-btn-sm cpub-btn-primary" @click="showNewDialog = true">
         <i class="fa-solid fa-pen"></i> New Message
       </button>
     </div>
 
     <!-- New conversation dialog -->
-    <div v-if="showNewDialog" class="cpub-new-msg-overlay" @click.self="showNewDialog = false" @keydown.escape="showNewDialog = false">
-      <div class="cpub-new-msg-dialog" role="dialog" aria-label="New message">
+    <div v-if="showNewDialog" class="cpub-new-msg-overlay" @click.self="showNewDialog = false" @keydown.escape="showNewDialog = false" @keydown="handleDialogKeydown">
+      <div ref="dialogRef" class="cpub-new-msg-dialog" role="dialog" aria-label="New message" aria-modal="true">
         <div class="cpub-new-msg-header">
           <h2 class="cpub-new-msg-title">New Conversation</h2>
           <button class="cpub-new-msg-close" @click="showNewDialog = false" aria-label="Close">

package/pages/settings/profile.vue

@@ -39,6 +39,22 @@ const socialLinks = ref({
 });
 const experience = ref<Array<{ id: string; title: string; company: string; startDate: string; endDate: string; description: string }>>([]);
 
+const emailNotifications = ref<{
+  digest: 'daily' | 'weekly' | 'none';
+  likes: boolean;
+  comments: boolean;
+  follows: boolean;
+  mentions: boolean;
+}>({
+  digest: 'none',
+  likes: false,
+  comments: false,
+  follows: false,
+  mentions: false,
+});
+
+const { emailNotifications: emailNotificationsEnabled } = useFeatures();
+
 const avatarInput = ref<HTMLInputElement | null>(null);
 const bannerInput = ref<HTMLInputElement | null>(null);
 
@@ -73,12 +89,22 @@ if (profile.value) {
   if (Array.isArray(profileRecord.experience)) {
     experience.value = (profileRecord.experience as Array<Record<string, unknown>>).map((e) => ({ ...e }) as typeof experience.value[number]);
   }
+  if (profileRecord.emailNotifications && typeof profileRecord.emailNotifications === 'object') {
+    const en = profileRecord.emailNotifications as Record<string, unknown>;
+    emailNotifications.value = {
+      digest: (['daily', 'weekly', 'none'].includes(en.digest as string) ? en.digest : 'none') as 'daily' | 'weekly' | 'none',
+      likes: en.likes === true,
+      comments: en.comments === true,
+      follows: en.follows === true,
+      mentions: en.mentions === true,
+    };
+  }
 }
 
 // Watch for form changes AFTER initial data is loaded (nextTick avoids false positive)
 onMounted(() => {
   nextTick(() => {
-    watch([form, skills, socialLinks, experience], () => { isDirty.value = true; }, { deep: true });
+    watch([form, skills, socialLinks, experience, emailNotifications], () => { isDirty.value = true; }, { deep: true });
   });
 });
 
@@ -147,6 +173,7 @@ async function handleSave(): Promise<void> {
         skills: skills.value.filter((s) => s.name.trim()),
         socialLinks: socialLinks.value,
         experience: experience.value.filter((e) => e.title.trim()),
+        ...(emailNotificationsEnabled.value ? { emailNotifications: emailNotifications.value } : {}),
       },
     });
     toast.success('Profile updated');
@@ -490,6 +517,76 @@ async function handleSave(): Promise<void> {
         </button>
       </div>
 
+      <!-- Email Notifications (gated behind feature flag) -->
+      <div v-if="emailNotificationsEnabled" class="cpub-form-section">
+        <span class="cpub-form-section-label">Email Notifications</span>
+
+        <div class="cpub-form-group">
+          <label for="digest-mode" class="cpub-form-label">Digest Mode</label>
+          <select
+            id="digest-mode"
+            v-model="emailNotifications.digest"
+            class="cpub-select"
+          >
+            <option value="none">Off (instant emails only)</option>
+            <option value="daily">Daily digest</option>
+            <option value="weekly">Weekly digest</option>
+          </select>
+          <span class="cpub-form-hint">
+            {{ emailNotifications.digest === 'none'
+              ? 'Instant emails are sent for each enabled type below.'
+              : `A ${emailNotifications.digest} email summarizing your unread notifications.` }}
+          </span>
+        </div>
+
+        <fieldset class="cpub-notification-toggles" :disabled="emailNotifications.digest !== 'none'">
+          <legend class="cpub-form-label cpub-toggle-legend">Instant Email Types</legend>
+          <span v-if="emailNotifications.digest !== 'none'" class="cpub-form-hint cpub-toggle-hint">
+            Individual emails are disabled when digest mode is active.
+          </span>
+
+          <label class="cpub-toggle-row" for="notif-likes">
+            <input
+              id="notif-likes"
+              v-model="emailNotifications.likes"
+              type="checkbox"
+              class="cpub-checkbox"
+            />
+            <span>Likes</span>
+          </label>
+
+          <label class="cpub-toggle-row" for="notif-comments">
+            <input
+              id="notif-comments"
+              v-model="emailNotifications.comments"
+              type="checkbox"
+              class="cpub-checkbox"
+            />
+            <span>Comments</span>
+          </label>
+
+          <label class="cpub-toggle-row" for="notif-follows">
+            <input
+              id="notif-follows"
+              v-model="emailNotifications.follows"
+              type="checkbox"
+              class="cpub-checkbox"
+            />
+            <span>New followers</span>
+          </label>
+
+          <label class="cpub-toggle-row" for="notif-mentions">
+            <input
+              id="notif-mentions"
+              v-model="emailNotifications.mentions"
+              type="checkbox"
+              class="cpub-checkbox"
+            />
+            <span>@mentions</span>
+          </label>
+        </fieldset>
+      </div>
+
       <!-- Actions -->
       <div class="cpub-form-actions">
         <button type="submit" class="cpub-save-btn" :disabled="saving">
@@ -792,6 +889,61 @@ async function handleSave(): Promise<void> {
   gap: var(--space-4);
 }
 
+/* ─── Email notification toggles ─── */
+.cpub-select {
+  display: block;
+  width: 100%;
+  padding: var(--space-2) var(--space-3);
+  background: var(--surface);
+  color: var(--text);
+  border: var(--border-width-default) solid var(--border2);
+  font-size: var(--text-sm);
+  font-family: var(--font-sans);
+  appearance: none;
+}
+
+.cpub-select:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 1px;
+}
+
+.cpub-notification-toggles {
+  border: none;
+  padding: 0;
+  margin: var(--space-3) 0 0;
+}
+
+.cpub-notification-toggles:disabled {
+  opacity: 0.5;
+}
+
+.cpub-toggle-legend {
+  margin-bottom: var(--space-2);
+}
+
+.cpub-toggle-hint {
+  display: block;
+  margin-bottom: var(--space-2);
+}
+
+.cpub-toggle-row {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  padding: var(--space-2) 0;
+  cursor: pointer;
+  font-size: var(--text-sm);
+  color: var(--text);
+}
+
+.cpub-checkbox {
+  width: 16px;
+  height: 16px;
+  accent-color: var(--accent);
+  cursor: pointer;
+  flex-shrink: 0;
+}
+
 /* ─── Form actions ─── */
 .cpub-form-actions {
   display: flex;

package/server/api/files/upload-from-url.post.ts

@@ -10,17 +10,24 @@ export default defineEventHandler(async (event) => {
   const user = requireAuth(event);
   const { url, purpose } = await parseBody(event, schema);
 
-  // SSRF protection — block private IPs
+  // SSRF protection — block private/internal IPs
   const parsed = new URL(url);
-  const hostname = parsed.hostname;
+  const hostname = parsed.hostname.toLowerCase();
+  const h = hostname.replace(/^\[|\]$/g, '');
   if (
-    hostname === 'localhost' ||
-    hostname === '127.0.0.1' ||
-    hostname === '::1' ||
-    hostname.startsWith('10.') ||
-    hostname.startsWith('192.168.') ||
-    hostname.match(/^172\.(1[6-9]|2\d|3[01])\./) ||
-    hostname === '169.254.169.254' // AWS metadata
+    h === 'localhost' ||
+    h === 'localhost.localdomain' ||
+    h === 'metadata.google.internal' ||
+    h.endsWith('.local') ||
+    /^127\./.test(h) ||
+    /^10\./.test(h) ||
+    /^172\.(1[6-9]|2\d|3[01])\./.test(h) ||
+    /^192\.168\./.test(h) ||
+    /^169\.254\./.test(h) ||
+    /^0\./.test(h) ||
+    h === '::1' ||
+    /^f[cd]/i.test(h) ||
+    /^fe80/i.test(h)
   ) {
     throw createError({ statusCode: 400, statusMessage: 'Cannot fetch from private/local addresses' });
   }

package/server/api/image-proxy.get.ts

@@ -29,15 +29,22 @@ export default defineEventHandler(async (event) => {
   }
 
   // Block localhost/private IPs (SSRF prevention)
-  const hostname = parsed.hostname;
+  const hostname = parsed.hostname.toLowerCase();
+  const h = hostname.replace(/^\[|\]$/g, ''); // strip IPv6 brackets
   if (
-    hostname === 'localhost' ||
-    hostname === '127.0.0.1' ||
-    hostname === '::1' ||
-    hostname.startsWith('10.') ||
-    hostname.startsWith('172.') ||
-    hostname.startsWith('192.168.') ||
-    hostname.endsWith('.local')
+    h === 'localhost' ||
+    h === 'localhost.localdomain' ||
+    h === 'metadata.google.internal' ||
+    h.endsWith('.local') ||
+    /^127\./.test(h) ||
+    /^10\./.test(h) ||
+    /^172\.(1[6-9]|2\d|3[01])\./.test(h) ||
+    /^192\.168\./.test(h) ||
+    /^169\.254\./.test(h) ||
+    /^0\./.test(h) ||
+    h === '::1' ||
+    /^f[cd]/i.test(h) ||
+    /^fe80/i.test(h)
   ) {
     throw createError({ statusCode: 403, statusMessage: 'Private addresses not allowed' });
   }

package/server/api/realtime/stream.get.ts

@@ -30,8 +30,12 @@ export default defineEventHandler(async (event) => {
         controller.enqueue(encoder.encode(`data: ${JSON.stringify({ type: 'counts', notifications, messages })}\n\n`));
       }
 
-      // Send initial counts
-      await sendCounts();
+      // Send initial counts — if DB is unavailable, send zeros and let polling retry
+      try {
+        await sendCounts();
+      } catch {
+        controller.enqueue(encoder.encode(`data: ${JSON.stringify({ type: 'counts', notifications: 0, messages: 0 })}\n\n`));
+      }
 
       // Poll every 10 seconds
       const interval = setInterval(async () => {

package/server/middleware/auth.ts

@@ -1,45 +1,10 @@
 // Nitro middleware for authentication using @commonpub/auth
 import { createAuthMiddleware, type AuthLocals } from '@commonpub/auth';
 import { createAuth } from '@commonpub/auth';
-import { ConsoleEmailAdapter, SmtpEmailAdapter, ResendEmailAdapter, emailTemplates } from '@commonpub/server';
-import type { EmailAdapter } from '@commonpub/server';
+import { emailTemplates } from '@commonpub/server';
 
 let authMiddleware: ReturnType<typeof createAuthMiddleware> | null = null;
 
-function createEmailAdapter(): EmailAdapter {
-  const runtimeConfig = useRuntimeConfig();
-  const adapter = (runtimeConfig.emailAdapter as string) || 'console';
-
-  if (adapter === 'smtp') {
-    const host = runtimeConfig.smtpHost as string;
-    const port = parseInt(runtimeConfig.smtpPort as string, 10) || 587;
-    const user = runtimeConfig.smtpUser as string;
-    const pass = runtimeConfig.smtpPass as string;
-    const from = runtimeConfig.smtpFrom as string;
-
-    if (!host || !user || !pass || !from) {
-      console.warn('[email] SMTP configured but missing credentials — falling back to console');
-      return new ConsoleEmailAdapter();
-    }
-
-    return new SmtpEmailAdapter({ host, port, user, pass, from });
-  }
-
-  if (adapter === 'resend') {
-    const apiKey = runtimeConfig.resendApiKey as string;
-    const from = runtimeConfig.resendFrom as string;
-
-    if (!apiKey || !from) {
-      console.warn('[email] Resend configured but missing API key or from address — falling back to console');
-      return new ConsoleEmailAdapter();
-    }
-
-    return new ResendEmailAdapter({ apiKey, from });
-  }
-
-  return new ConsoleEmailAdapter();
-}
-
 function getAuthMiddleware(): ReturnType<typeof createAuthMiddleware> {
   if (authMiddleware) return authMiddleware;
 
@@ -49,7 +14,7 @@ function getAuthMiddleware(): ReturnType<typeof createAuthMiddleware> {
   const siteUrl = (runtimeConfig.public?.siteUrl as string) || `https://${config.instance.domain}`;
   const siteName = config.instance.name || 'CommonPub';
 
-  const emailAdapter = createEmailAdapter();
+  const emailAdapter = useEmailAdapter();
 
   // In dev, trust any localhost origin so port changes don't break auth
   const trustedOrigins = process.env.NODE_ENV !== 'production'

package/server/plugins/federation-hub-sync.ts

@@ -0,0 +1,119 @@
+/**
+ * Federation hub sync worker.
+ * Periodically refreshes metadata and optionally backfills posts for accepted federated hubs.
+ * Gated on features.federateHubs. Configurable via federation.hubSyncIntervalMs.
+ */
+import {
+  refreshFederatedHubMetadata,
+  backfillHubFromOutbox,
+} from '@commonpub/server';
+import { federatedHubs } from '@commonpub/schema';
+import { eq, and, or, lt, isNull } from 'drizzle-orm';
+
+const MAX_HUBS_PER_CYCLE = 5;
+const STAGGER_DELAY_MS = 2_000;
+
+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.federateHubs) {
+        console.log('[hub-sync] Hub federation disabled — sync worker not started');
+        return;
+      }
+
+      const runtimeConfig = useRuntimeConfig();
+      const siteUrl = (runtimeConfig.public?.siteUrl as string) || `https://${config.instance.domain}`;
+      const domain = siteUrl.replace(/^https?:\/\//, '').replace(/[:/].*$/, '');
+
+      const fedConfig = config.federation ?? {};
+      const intervalMs = fedConfig.hubSyncIntervalMs ?? 3_600_000;
+      const backfillOnSync = fedConfig.backfillOnMirrorAccept ?? false;
+
+      console.log(`[hub-sync] Hub sync worker started (domain: ${domain}, interval: ${intervalMs}ms, backfill: ${backfillOnSync})`);
+
+      // Run first sync after a brief delay to avoid startup contention
+      runSync(domain, intervalMs, backfillOnSync);
+
+      interval = setInterval(() => {
+        runSync(domain, intervalMs, backfillOnSync).catch((err) => {
+          console.error('[hub-sync] Sync worker unexpected error:', err instanceof Error ? err.message : err);
+        });
+      }, intervalMs);
+    } catch (err) {
+      console.error('[hub-sync] Failed to start:', err instanceof Error ? err.message : err);
+    }
+  }, 10_000); // 10s startup delay (longer than delivery worker to avoid contention)
+
+  async function runSync(domain: string, intervalMs: number, backfillOnSync: boolean): Promise<void> {
+    try {
+      const db = useDB();
+      const now = new Date();
+      const staleThreshold = new Date(now.getTime() - intervalMs);
+
+      // Find accepted, non-hidden hubs where lastSyncAt is older than the interval or null
+      const staleHubs = await db
+        .select({
+          id: federatedHubs.id,
+          actorUri: federatedHubs.actorUri,
+          name: federatedHubs.name,
+          lastSyncAt: federatedHubs.lastSyncAt,
+        })
+        .from(federatedHubs)
+        .where(and(
+          eq(federatedHubs.status, 'accepted'),
+          eq(federatedHubs.isHidden, false),
+          or(
+            isNull(federatedHubs.lastSyncAt),
+            lt(federatedHubs.lastSyncAt, staleThreshold),
+          ),
+        ))
+        .limit(MAX_HUBS_PER_CYCLE);
+
+      if (staleHubs.length === 0) return;
+
+      console.log(`[hub-sync] Found ${staleHubs.length} stale hub(s) to sync`);
+
+      for (const hub of staleHubs) {
+        try {
+          // Refresh metadata (name, description, icon, member count)
+          await refreshFederatedHubMetadata(db, hub.id, hub.actorUri);
+
+          // Optionally backfill new posts from outbox
+          if (backfillOnSync) {
+            const result = await backfillHubFromOutbox(db, hub.id, domain);
+            if (result.processed > 0 || result.errors > 0) {
+              console.log(`[hub-sync] Backfill ${hub.name}: ${result.processed} processed, ${result.errors} errors`);
+            }
+          }
+
+          // Update lastSyncAt
+          await db.update(federatedHubs).set({
+            lastSyncAt: new Date(),
+          }).where(eq(federatedHubs.id, hub.id));
+        } catch (err) {
+          console.error(`[hub-sync] Failed to sync hub ${hub.name}:`, err instanceof Error ? err.message : err);
+        }
+
+        // Stagger between hubs to avoid hammering remote instances
+        if (staleHubs.indexOf(hub) < staleHubs.length - 1) {
+          await new Promise((r) => setTimeout(r, STAGGER_DELAY_MS));
+        }
+      }
+    } catch (err) {
+      console.error('[hub-sync] Sync worker error:', err instanceof Error ? err.message : err);
+    }
+  }
+
+  nitro.hooks.hook('close', () => {
+    clearTimeout(startupTimer);
+    if (interval) {
+      clearInterval(interval);
+      interval = null;
+    }
+  });
+});

package/server/plugins/notification-email.ts

@@ -0,0 +1,165 @@
+/**
+ * Notification email plugin.
+ * - Registers an instant email sender so createNotification() can fire emails.
+ * - Runs a digest scheduler that batches unread notifications for users who prefer daily/weekly digests.
+ */
+import {
+  setNotificationEmailSender,
+  shouldEmailNotification,
+  getNotificationEmailTarget,
+  emailTemplates,
+  listNotifications,
+} from '@commonpub/server';
+import type { NotificationType } from '@commonpub/server';
+import { users } from '@commonpub/schema';
+import { and, isNotNull, eq } from 'drizzle-orm';
+
+export default defineNitroPlugin((nitro) => {
+  if (process.env.NODE_ENV === 'test') return;
+
+  let digestInterval: ReturnType<typeof setInterval> | null = null;
+
+  const startupTimer = setTimeout(() => {
+    try {
+      const config = useConfig();
+      if (!config.features.emailNotifications) {
+        console.log('[notification-email] Email notifications disabled');
+        return;
+      }
+
+      const runtimeConfig = useRuntimeConfig();
+      const siteUrl = (runtimeConfig.public?.siteUrl as string) || `https://${config.instance.domain}`;
+      const siteName = config.instance.name || 'CommonPub';
+
+      // Register instant email sender.
+      // Uses useDB() instead of the passed db because createNotification() may be
+      // called inside a transaction — the fire-and-forget callback would run after
+      // the transaction commits, making the transaction-scoped db handle stale.
+      setNotificationEmailSender(async (_db, notification) => {
+        const freshDb = useDB();
+        const should = await shouldEmailNotification(
+          freshDb,
+          notification.userId,
+          notification.type as NotificationType,
+        );
+        if (!should) return;
+
+        const target = await getNotificationEmailTarget(freshDb, notification.userId);
+        if (!target) return;
+
+        const emailAdapter = useEmailAdapter();
+        const template = emailTemplates.notificationInstant(
+          siteName,
+          target.username,
+          {
+            title: notification.title,
+            message: notification.message,
+            url: notification.link ? `${siteUrl}${notification.link}` : siteUrl,
+          },
+        );
+        await emailAdapter.send({ ...template, to: target.email });
+      });
+
+      console.log('[notification-email] Instant email sender registered');
+
+      // Digest scheduler — runs every hour, sends digests for users whose digest window has elapsed
+      const DIGEST_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
+      digestInterval = setInterval(() => {
+        runDigest(siteUrl, siteName).catch((err) => {
+          console.error('[notification-email] Digest scheduler unexpected error:', err instanceof Error ? err.message : err);
+        });
+      }, DIGEST_INTERVAL_MS);
+
+      console.log('[notification-email] Digest scheduler started (interval: 1h)');
+    } catch (err) {
+      console.error('[notification-email] Failed to start:', err instanceof Error ? err.message : err);
+    }
+  }, 5_000);
+
+  async function runDigest(siteUrl: string, siteName: string): Promise<void> {
+    try {
+      const db = useDB();
+      const now = new Date();
+      const hour = now.getUTCHours();
+
+      // Daily digests go out at 8am UTC; weekly digests go out Monday at 8am UTC
+      const isDigestHour = hour === 8;
+      const isMonday = now.getUTCDay() === 1;
+
+      if (!isDigestHour) return;
+
+      // Find users with digest preferences
+      const digestUsers = await db
+        .select({
+          id: users.id,
+          email: users.email,
+          username: users.username,
+          emailNotifications: users.emailNotifications,
+          emailVerified: users.emailVerified,
+        })
+        .from(users)
+        .where(and(
+          isNotNull(users.emailNotifications),
+          eq(users.emailVerified, true),
+        ));
+
+      const emailAdapter = useEmailAdapter();
+      let sent = 0;
+
+      for (const user of digestUsers) {
+        const prefs = user.emailNotifications as { digest?: string } | null;
+        if (!prefs?.digest) continue;
+        if (prefs.digest === 'none') continue;
+        if (prefs.digest === 'weekly' && !isMonday) continue;
+
+        // Get unread notifications from the last digest period
+        const since = new Date(now);
+        if (prefs.digest === 'daily') {
+          since.setDate(since.getDate() - 1);
+        } else {
+          since.setDate(since.getDate() - 7);
+        }
+
+        const { items } = await listNotifications(db, {
+          userId: user.id,
+          read: false,
+          limit: 50,
+        });
+
+        // Filter to only notifications within the digest window
+        const recent = items.filter((n) => n.createdAt >= since);
+        if (recent.length === 0) continue;
+
+        const template = emailTemplates.notificationDigest(
+          siteName,
+          user.username,
+          recent.map((n) => ({
+            text: `${n.title}: ${n.message}`,
+            url: n.link ? `${siteUrl}${n.link}` : siteUrl,
+          })),
+        );
+
+        try {
+          await emailAdapter.send({ ...template, to: user.email });
+          sent++;
+        } catch (err) {
+          console.error(`[notification-email] Digest failed for ${user.username}:`, err instanceof Error ? err.message : err);
+        }
+      }
+
+      if (sent > 0) {
+        console.log(`[notification-email] Sent ${sent} digest email(s)`);
+      }
+    } catch (err) {
+      console.error('[notification-email] Digest scheduler error:', err instanceof Error ? err.message : err);
+    }
+  }
+
+  nitro.hooks.hook('close', () => {
+    clearTimeout(startupTimer);
+    if (digestInterval) {
+      clearInterval(digestInterval);
+      digestInterval = null;
+    }
+  });
+});

package/server/utils/email.ts

@@ -0,0 +1,49 @@
+import { ConsoleEmailAdapter, SmtpEmailAdapter, ResendEmailAdapter } from '@commonpub/server';
+import type { EmailAdapter } from '@commonpub/server';
+
+let cachedAdapter: EmailAdapter | null = null;
+
+/**
+ * Create and cache an email adapter based on runtime config.
+ * Reusable by auth middleware, notification plugin, and any server route.
+ */
+export function useEmailAdapter(): EmailAdapter {
+  if (cachedAdapter) return cachedAdapter;
+
+  const runtimeConfig = useRuntimeConfig();
+  const adapter = (runtimeConfig.emailAdapter as string) || 'console';
+
+  if (adapter === 'smtp') {
+    const host = runtimeConfig.smtpHost as string;
+    const port = parseInt(runtimeConfig.smtpPort as string, 10) || 587;
+    const user = runtimeConfig.smtpUser as string;
+    const pass = runtimeConfig.smtpPass as string;
+    const from = runtimeConfig.smtpFrom as string;
+
+    if (!host || !user || !pass || !from) {
+      console.warn('[email] SMTP configured but missing credentials — falling back to console');
+      cachedAdapter = new ConsoleEmailAdapter();
+      return cachedAdapter;
+    }
+
+    cachedAdapter = new SmtpEmailAdapter({ host, port, user, pass, from });
+    return cachedAdapter;
+  }
+
+  if (adapter === 'resend') {
+    const apiKey = runtimeConfig.resendApiKey as string;
+    const from = runtimeConfig.resendFrom as string;
+
+    if (!apiKey || !from) {
+      console.warn('[email] Resend configured but missing API key or from address — falling back to console');
+      cachedAdapter = new ConsoleEmailAdapter();
+      return cachedAdapter;
+    }
+
+    cachedAdapter = new ResendEmailAdapter({ apiKey, from });
+    return cachedAdapter;
+  }
+
+  cachedAdapter = new ConsoleEmailAdapter();
+  return cachedAdapter;
+}

package/server/api/messages/stream.get.ts

@@ -1,57 +0,0 @@
-import { getUnreadMessageCount } from '@commonpub/server';
-
-/** @deprecated Use /api/realtime/stream instead */
-export default defineEventHandler(async (event) => {
-  console.warn('[deprecated] /api/messages/stream — use /api/realtime/stream instead');
-  const user = requireAuth(event);
-  const userId = user.id;
-  const db = useDB();
-
-  setResponseHeader(event, 'Content-Type', 'text/event-stream');
-  setResponseHeader(event, 'Cache-Control', 'no-cache');
-  setResponseHeader(event, 'Connection', 'keep-alive');
-
-  const encoder = new TextEncoder();
-  const stream = new ReadableStream({
-    async start(controller) {
-      let closed = false;
-      function cleanup(): void {
-        if (closed) return;
-        closed = true;
-        clearInterval(interval);
-        clearInterval(keepalive);
-        try { controller.close(); } catch { /* already closed */ }
-      }
-
-      const count = await getUnreadMessageCount(db, userId);
-      controller.enqueue(encoder.encode(`data: ${JSON.stringify({ type: 'count', count })}\n\n`));
-
-      const interval = setInterval(async () => {
-        try {
-          const currentCount = await getUnreadMessageCount(db, userId);
-          controller.enqueue(encoder.encode(`data: ${JSON.stringify({ type: 'count', count: currentCount })}\n\n`));
-        } catch {
-          cleanup();
-        }
-      }, 10000);
-
-      const keepalive = setInterval(() => {
-        try {
-          controller.enqueue(encoder.encode(': keepalive\n\n'));
-        } catch {
-          cleanup();
-        }
-      }, 30000);
-
-      event.node.req.on('close', cleanup);
-    },
-  });
-
-  return new Response(stream, {
-    headers: {
-      'Content-Type': 'text/event-stream',
-      'Cache-Control': 'no-cache',
-      'Connection': 'keep-alive',
-    },
-  });
-});

package/server/api/notifications/stream.get.ts

@@ -1,61 +0,0 @@
-import { getUnreadCount } from '@commonpub/server';
-
-/** @deprecated Use /api/realtime/stream instead */
-export default defineEventHandler(async (event) => {
-  console.warn('[deprecated] /api/notifications/stream — use /api/realtime/stream instead');
-  const user = requireAuth(event);
-  const userId = user.id;
-  const db = useDB();
-
-  setResponseHeader(event, 'Content-Type', 'text/event-stream');
-  setResponseHeader(event, 'Cache-Control', 'no-cache');
-  setResponseHeader(event, 'Connection', 'keep-alive');
-
-  const encoder = new TextEncoder();
-  const stream = new ReadableStream({
-    async start(controller) {
-      let closed = false;
-      function cleanup(): void {
-        if (closed) return;
-        closed = true;
-        clearInterval(interval);
-        clearInterval(keepalive);
-        try { controller.close(); } catch { /* already closed */ }
-      }
-
-      // Send initial count
-      const count = await getUnreadCount(db, userId);
-      controller.enqueue(encoder.encode(`data: ${JSON.stringify({ type: 'count', count })}\n\n`));
-
-      // Poll every 10 seconds for new notifications
-      const interval = setInterval(async () => {
-        try {
-          const currentCount = await getUnreadCount(db, userId);
-          controller.enqueue(encoder.encode(`data: ${JSON.stringify({ type: 'count', count: currentCount })}\n\n`));
-        } catch {
-          cleanup();
-        }
-      }, 10000);
-
-      // Send keepalive every 30 seconds
-      const keepalive = setInterval(() => {
-        try {
-          controller.enqueue(encoder.encode(': keepalive\n\n'));
-        } catch {
-          cleanup();
-        }
-      }, 30000);
-
-      // Clean up on close
-      event.node.req.on('close', cleanup);
-    },
-  });
-
-  return new Response(stream, {
-    headers: {
-      'Content-Type': 'text/event-stream',
-      'Cache-Control': 'no-cache',
-      'Connection': 'keep-alive',
-    },
-  });
-});