Add public shard read endpoints + live SSE stream (phase 2)

Curated, same-origin, token-free reads so the browser never sees the sidecar
URL or token:

- public/shard.controller.js:
  - GET /public/shard/status — connection state + online count + latest economy
    (from the site's ingested data).
  - GET /public/shard/feed?kind=&limit= — recent notable events from the log.
  - GET /public/shard/economy — gold-supply series (oldest → newest).
  - GET /public/shard/idoc — houses currently at IDOC.
  - GET /public/shard/char/:serial — live sheet round-trip via uoLinkClient,
    briefly cached; 503 (shard restarting) serves a stale cache or a retry
    banner rather than an error.
  - GET /public/shard/stream — public SSE channel (safe kinds only).
- Wired into public.routes.js with express-validator guards and #swagger
  annotations; new "Public · Shard" tag + ShardStatus/ShardEvent/
  ShardEconomyPoint/ShardHouse schemas; swagger-output.json regenerated.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011qPmpmVH1xGCiZoz9m9vW3

server/src/router/v1/public/public.routes.js

@@ -1,7 +1,8 @@
 const express = require('express')
-const { body } = require('express-validator')
+const { body, param, query } = require('express-validator')
 
 const ctrl = require('./public.controller')
+const shard = require('./shard.controller')
 const siteMode = require('../../../middleware/siteMode')
 const validate = require('../../../middleware/validate')
 const { contactLimiter } = require('../../../middleware/rateLimit')
@@ -128,4 +129,66 @@ publicRouter.get(
   ctrl.getPage,
 )
 
+// ── Shard live data (uo-link) ──────────────────────────────────────────────
+// Token-free, same-origin reads. The status/feed/economy/idoc endpoints read
+// the site's own ingested data; /char round-trips the live shard (cached). Not
+// site-mode gated — shard status is useful even during site maintenance.
+publicRouter.get(
+  '/shard/status',
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'Shard connection state, online count and latest economy'
+  /* #swagger.responses[200] = { description: 'Shard status', content: { "application/json": { schema: { $ref: "#/components/schemas/ShardStatus" } } } } */
+  shard.getStatus,
+)
+publicRouter.get(
+  '/shard/feed',
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'Recent notable shard events (from the ingested log)'
+  // #swagger.parameters['kind'] = { in: 'query', required: false, schema: { type: 'string' }, description: 'Filter to a single event kind, e.g. vendor.sale.' }
+  // #swagger.parameters['limit'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Max rows (default 100, max 1000).' }
+  /* #swagger.responses[200] = { description: 'Events, newest first', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardEvent" } } } } } */
+  query('kind').optional({ values: 'falsy' }).isString().isLength({ max: 48 }),
+  query('limit').optional().isInt({ min: 1, max: 1000 }),
+  validate,
+  shard.getFeed,
+)
+publicRouter.get(
+  '/shard/economy',
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'Gold-supply time series (oldest → newest)'
+  // #swagger.parameters['limit'] = { in: 'query', required: false, schema: { type: 'integer' }, description: 'Max samples (default 100, max 1000).' }
+  /* #swagger.responses[200] = { description: 'Economy samples', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardEconomyPoint" } } } } } */
+  query('limit').optional().isInt({ min: 1, max: 1000 }),
+  validate,
+  shard.getEconomy,
+)
+publicRouter.get(
+  '/shard/idoc',
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'Houses currently in danger (IDOC)'
+  /* #swagger.responses[200] = { description: 'IDOC houses', content: { "application/json": { schema: { type: "array", items: { $ref: "#/components/schemas/ShardHouse" } } } } } */
+  shard.getIdoc,
+)
+publicRouter.get(
+  '/shard/char/:serial',
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'Live character sheet by serial (cached; degrades on shard restart)'
+  // #swagger.parameters['serial'] = { in: 'path', required: true, schema: { type: 'string' }, description: 'Mobile serial, e.g. 0x24C.' }
+  /* #swagger.responses[200] = { description: 'Character profile', content: { "application/json": { schema: { type: "object", additionalProperties: true } } } } */
+  /* #swagger.responses[400] = { description: 'Invalid serial', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[404] = { description: 'Character not found', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  /* #swagger.responses[503] = { description: 'Shard restarting — retry', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
+  param('serial').matches(/^0x[0-9a-fA-F]+$/),
+  validate,
+  shard.getChar,
+)
+publicRouter.get(
+  '/shard/stream',
+  // #swagger.tags = ['Public · Shard']
+  // #swagger.summary = 'Live shard event stream (Server-Sent Events, public/safe kinds)'
+  // #swagger.description = 'text/event-stream of curated live events. Sensitive kinds (staff audit, cheat detection, login attempts, IPs) are NOT sent on this channel.'
+  /* #swagger.responses[200] = { description: 'An SSE stream (Content-Type: text/event-stream).' } */
+  shard.stream,
+)
+
 module.exports = publicRouter