TownSquare：一个被低估的"网站在场层"，正在悄悄重塑我们对实时 web 的认知

// TownSquare 的核心 API 设计体现了极致的克制
import { TownSquare } from '@townsquare/client';

const presence = new TownSquare({
  room: 'blog-post-hello-world',
  server: 'wss://presence.example.com',
  
  // 自动处理的匿名身份
  identity: 'anonymous',
  
  // 可自定义的在场展现
  render: (users) => {
    // 返回 DOM 节点或 React 组件
    return renderAvatars(users);
  }
});

// 监听特定事件
presence.on('user:joined', (user) => {
  console.log(`${user.id.slice(0,8)} 正在浏览此页`);
});

// Cloudflare Worker 中的 TownSquare 服务端简化实现
export class PresenceRoom implements DurableObject {
  private users: Map<string, UserState> = new Map();
  private subscriptions: Set<WebSocket> = new Set();

  async fetch(request: Request) {
    const upgradeHeader = request.headers.get('Upgrade');
    if (upgradeHeader !== 'websocket') {
      return new Response('Expected websocket', { status: 400 });
    }
    
    const [client, server] = Object.values(new WebSocketPair());
    
    // 关键：DO 的单线程保证消除了并发状态管理的复杂性
    this.handleConnection(server);
    
    return new Response(null, { status: 101, webSocket: client });
  }

  private handleConnection(ws: WebSocket) {
    ws.addEventListener('message', (msg) => {
      const event = JSON.parse(msg.data as string);
      
      switch (event.type) {
        case 'heartbeat':
          // 刷新用户 TTL，DO 内存中的 Map 操作是线性的
          this.users.get(event.userId)?.refresh();
          break;
        case 'cursor:move':
          // 广播给同房间其他用户，不包含自己
          this.broadcast(event, { exclude: event.userId });
          break;
      }
    });
  }

  private broadcast(event: any, options: { exclude?: string }) {
    for (const [userId, state] of this.users) {
      if (userId === options.exclude) continue;
      state.socket.send(JSON.stringify(event));
    }
  }
}

// 用户 ID 是加密学安全的随机生成，无关联追踪
const userId = crypto.randomUUID(); // 每次会话重新生成

// 可选：通过 URL hash 或 localStorage 实现弱持久化
// 但核心设计鼓励"遗忘"——关闭页面即消失

// 一个让我印象深刻的用例：博客评论区的"在场"
const commentPresence = new TownSquare({
  room: `comments:${articleId}`,
  
  // 只显示"附近"的用户——基于滚动位置
  filter: (self, other) => {
    return Math.abs(self.scrollY - other.scrollY) < 800;
  },
  
  // 极简的视觉呈现：仅一个光点
  render: (users) => users.map(u => 
    `<div class="cursor" style="top:${u.scrollY}px; left:${u.x}px" 
          title="读者 ${u.id.slice(0,4)}"/>`
  ).join('')
});

// 未来可能的 API 演进
const hybridPresence = new TownSquare({
  room: 'doc-123',
  
  // AI 参与者在场，但视觉标识不同
  agents: [{
    id: 'ai-editor',
    display: { type: 'sparkle', label: 'AI 助手' },
    // 由服务端 LLM 驱动行为
    behavior: 'collaborative-writing'
  }]
});