refactor(teams)!: Teams is a contract, not a surface — invert the slots

Org lead's correction, and it changes what this phase ships.

TEAMS.md §3.1 and §3.5 put four public pages and three nav rows in core. They
should never have been core's. **Teams is the platform primitive that the API
contract exposes; the module builds the pages on top of it.** module-uo builds
guilds; the Rust module that comes next builds clans. Core does not own the word
for a Team, so a core page under a noun core invented would have sat beside
module-uo's existing /uo/guilds saying the same thing in the wrong vocabulary.

Removed: /teams, /teams/:slug, /teams/:slug/roster, /player/teams, the public
and portal nav rows, the `teams` feature flag and the core feature provider that
answered it. /admin/teams stays — an operator inspecting the primitive is
looking at the primitive.

Kept, and unchanged: the tables, the reconciler, the access resolver, the
activity feed, the retention prune, the whole public/player/admin API,
optionalAuth and the roster projection. That is the contract, and it is what
this phase was actually for.

**So the extension slots invert, which is a new direction in MODULE_API §3.7.**
`team.overview` and `team.member.row` assumed core rendered the page. In their
place `registry.declareModuleSlot(id, name)` lets a MODULE declare a place on
its own page and core fill it. Core fills `uo.guild.detail` with the Team
activity feed — the one part of that page core cannot hand over, because only
core can resolve whether the viewer is inside the Team and the public/members
split is a security boundary.

Three things about the inverted direction are load-bearing:

  - the name is namespaced under the declaring module and that is enforced, not
    conventional: it is the only thing keeping two modules off one name;
  - core's fills are applied at MOUNT rather than eagerly. Core's bundle
    evaluates before every module chunk, so when core registers a fill the slot
    does not exist yet — filling eagerly would silently do nothing;
  - a fill for a slot nobody declared is a no-op, never an error. The declaring
    module is simply not installed, which is the ordinary case. That is the
    opposite of §3.7, where an unknown slot throws, and the asymmetry is real:
    there, core declares first, so an unknown name is always a typo.

`Slot` becomes the eighth member of the shared UI kit, so a module renders the
place with core's own error boundary. It matters more here than anywhere else in
the kit: the thing being contained is core's content failing inside the module's
page.

`GET /public/teams/by-external/:moduleId/:externalId` is added because a module
names a Team in its own vocabulary and core keys the feed by slug. The module id
is matched rather than trusted — an external id is unique only within a module.

Co-Authored-By: Claude <noreply@anthropic.com>

client/src/modules/TeamActivityFeed.jsx

@@ -0,0 +1,96 @@
+import { useEffect, useState } from 'react'
+import { api } from '../api/client.js'
+import { useAuth } from '../contexts/AuthContext.jsx'
+import { activityScopeNote, freshnessNote, groupByDay } from '../lib/teamActivity.js'
+
+// Core's Team activity feed, rendered into a slot a MODULE declares
+// (TEAMS.md Part 4, §3.4 as amended).
+//
+// **This is the inverted slot direction, and this component is why it exists.**
+// The feed is core's: core owns `team_activity`, writes the membership and rename
+// items into it, enforces the public/members split, and is the only thing that
+// can resolve whether this viewer is inside the Team. None of that is a module's
+// to reimplement. But the PAGE is the module's, because Teams is a contract
+// primitive and core does not own the word for one — a UO shard says guild, the
+// next game will say something else. So the module declares the place and core
+// puts the feed in it.
+//
+// The module passes the Team in ITS OWN vocabulary — `externalId` plus its module
+// id — and core resolves the slug. A module never learns core's Team id and never
+// needs to: it names the thing the way it already names it.
+//
+// Everything here degrades to rendering nothing. A slot that throws is contained
+// by core's own boundary (Slot.jsx), but a slot that renders an error box would
+// still be core putting a defect on a page it does not own — so a failed fetch is
+// silence, not a message.
+
+export default function TeamActivityFeed({ externalId, moduleId, limit = 25 }) {
+  const { user } = useAuth()
+  const [state, setState] = useState({ loading: true, feed: null, team: null })
+
+  useEffect(() => {
+    let active = true
+    if (!externalId || !moduleId) {
+      setState({ loading: false, feed: null, team: null })
+      return undefined
+    }
+    // Two calls because the module names the Team its way and the feed is keyed
+    // by core's slug. The lookup is core's job precisely so the module does not
+    // have to hold core's identifiers.
+    api.teamByExternalId(moduleId, externalId)
+      .then(async (team) => {
+        const feed = await api.teamActivity(team.slug, { limit })
+        if (active) setState({ loading: false, feed, team })
+      })
+      .catch(() => { if (active) setState({ loading: false, feed: null, team: null }) })
+    return () => { active = false }
+  }, [externalId, moduleId, limit])
+
+  const { loading, feed, team } = state
+  if (loading || !feed) return null
+
+  const days = groupByDay(feed.items || [])
+  const note = team ? freshnessNote(team) : null
+  const scopeNote = activityScopeNote(feed, Boolean(user))
+
+  // Nothing has happened and nothing to explain: render nothing rather than an
+  // empty heading on someone else's page.
+  if (days.length === 0 && !scopeNote) return null
+
+  return (
+    <section style={{ marginTop: 26 }}>
+      <h2 className="display" style={{ fontSize: '1.15rem', color: 'var(--head)', marginBottom: 4 }}>
+        Recent activity
+      </h2>
+      {note && (
+        <p className="sans dim" style={{ fontSize: '0.8rem', margin: '0 0 12px' }}>{note.text}</p>
+      )}
+
+      {days.length === 0 && (
+        <p className="sans dim" style={{ fontSize: '0.9rem' }}>Nothing has happened here yet.</p>
+      )}
+
+      {days.map((day) => (
+        <div key={day.key} style={{ marginBottom: 16 }}>
+          <h3
+            className="sans dim"
+            style={{ fontSize: '0.74rem', textTransform: 'uppercase', letterSpacing: '0.06em', marginBottom: 6 }}
+          >
+            {day.label}
+          </h3>
+          <ul style={{ listStyle: 'none', padding: 0, margin: 0, display: 'grid', gap: 6 }}>
+            {day.items.map((item) => (
+              <li key={item.id} className="sans" style={{ fontSize: '0.92rem', color: 'var(--ink)' }}>
+                {item.summary}
+              </li>
+            ))}
+          </ul>
+        </div>
+      ))}
+
+      {scopeNote && (
+        <p className="sans dim" style={{ fontSize: '0.82rem', marginTop: 10 }}>{scopeNote}</p>
+      )}
+    </section>
+  )
+}

client/src/modules/coreFeatures.js

@@ -1,56 +0,0 @@
-import { useEffect, useState } from 'react'
-
-// Core's own feature provider (TEAMS.md §3.5, MODULE_API.md §3.3).
-//
-// Core registered one here until the module cutover, under owner id `core` and
-// namespace `uo`, and it left with the shard rows. This brings the seam back with
-// content that is genuinely core's: `teams` gates the Teams nav rows, and Teams
-// are a core platform entity that a module merely populates.
-//
-// **What the flag actually answers is "does this deployment have Teams at all".**
-// Not "may this viewer see them" — Team pages are public (§0.7) and the server
-// gates them. On bare core, with no module supplying a Team provider and no rows
-// left behind by one, `/teams` is a permanently empty page and a link to it is
-// worse than no link. That is the whole job.
-//
-// It fails OPEN, like every other answer in this seam: while the request is in
-// flight, and on any error, the hook returns `null`, which `buildFeatureGate`
-// reads as "we do not know yet" and SHOWS the row. The page itself is the gate.
-// The one thing a UI mistake must never do here is hide a surface from someone
-// entitled to it — and a Teams link that leads somewhere empty is a far cheaper
-// mistake than a Team page nobody can find.
-
-// `limit=1` because only `enabled` is wanted. The endpoint answers it whatever
-// the page size, and asking for the default fifty would pull a roster's worth of
-// counts into a nav decision.
-const TEAMS_URL = '/api/v1/public/teams?limit=1'
-
-/**
- * The hook core registers. Returns a Set-like of visible flags, or `null` while
- * the answer is unknown.
- *
- * Fetched once per mount rather than subscribed: whether a deployment has Teams
- * changes when a module is installed, which is a restart, not a session event.
- */
-export function useCoreFlags() {
-  const [flags, setFlags] = useState(null)
-
-  useEffect(() => {
-    let active = true
-    fetch(TEAMS_URL, { credentials: 'same-origin' })
-      .then((res) => (res.ok ? res.json() : null))
-      .then((body) => {
-        if (!active) return
-        // A body that does not carry `enabled` is an older server or a shape
-        // change, and both are "unknown" rather than "no".
-        if (!body || typeof body.enabled !== 'boolean') return
-        setFlags(new Set(body.enabled ? ['teams'] : []))
-      })
-      .catch(() => {}) // stays null: unknown shows the row
-    return () => { active = false }
-  }, [])
-
-  return flags
-}
-
-export default useCoreFlags

client/src/modules/registry.js

@@ -135,6 +135,69 @@ export function declareSlot(name) {
   slots.set(name, { Component: null, filledBy: null })
 }
 
+/**
+ * The INVERTED direction: a MODULE declares a slot and CORE fills it.
+ *
+ * Added for Teams (TEAMS.md Part 3). The original direction assumes core owns
+ * the page and a module contributes to it, which is right for the footer and the
+ * admin user detail. Teams is the other shape: **Teams is a contract primitive,
+ * not a surface.** Core owns the tables, the sync, the access rules and the
+ * activity feed; it does not own the vocabulary — a UO shard calls them guilds
+ * and the next game will call them something else — so the PAGE is the module's
+ * and the content core contributes to it is core's.
+ *
+ * Without this, core would have to publish a `/teams` page under a word it
+ * invented, next to the module's own Guilds page saying the same thing twice.
+ *
+ * A module namespaces its slot under its own id (`uo.guild.detail`), which is
+ * what stops two modules colliding and what makes the owner readable at the fill
+ * site. The namespace is enforced rather than conventional.
+ *
+ * **Ordering is why this is a separate call and not just `declareSlot` exposed
+ * to modules.** Core's bundle evaluates BEFORE any module chunk (module scripts
+ * are deferred and injected after core's), so at the moment core would like to
+ * fill one of these, it does not exist yet. Core therefore registers its fills
+ * through `fillModuleSlot` below, which is applied after every module chunk has
+ * evaluated — see main.jsx.
+ */
+export function declareModuleSlot(id, name) {
+  if (!name.startsWith(`${id}.`)) {
+    throw new Error(`declareModuleSlot: "${name}" must be namespaced "${id}."`)
+  }
+  if (slots.has(name)) throw new Error(`extension slot "${name}" already declared`)
+  slots.set(name, { Component: null, filledBy: null, declaredBy: id })
+}
+
+// Core's pending fills for module-declared slots, applied once every module
+// chunk has evaluated. Kept as a list rather than applied eagerly because the
+// slot does not exist when core asks — see the ordering note above.
+const coreFills = []
+
+/**
+ * Core: "fill this module-declared slot when it turns up."
+ *
+ * Deliberately not an error when the slot never appears. A module that is not
+ * installed declares nothing, and core offering content for a page that does not
+ * exist is the ordinary case on any deployment — not a misconfiguration. That is
+ * the mirror of an unfilled slot rendering nothing.
+ */
+export function fillModuleSlot(name, Component) {
+  if (typeof Component !== 'function') throw new Error(`fillModuleSlot: ${name} is not a component`)
+  coreFills.push([name, Component])
+}
+
+/** Apply core's fills. Called once from main.jsx, after module chunks have run. */
+export function applyCoreFills() {
+  for (const [name, Component] of coreFills) {
+    const entry = slots.get(name)
+    if (!entry) continue // the declaring module is not installed
+    if (entry.filledBy) continue // a module already claimed it; first fill wins
+    entry.Component = Component
+    entry.filledBy = 'core'
+  }
+  coreFills.length = 0
+}
+
 /**
  * Fill a declared slot with a component.
  *
@@ -207,6 +270,7 @@ export function _reset() {
     nav[area].length = 0
   }
   providers.clear()
+  coreFills.length = 0
   // Declarations go too, unlike the server's, where a slot is declared once at
   // require time by the router that owns it. Core declares its slots in
   // main.jsx — the one file no test loads — so on this side there is nothing
@@ -224,6 +288,8 @@ export const registry = {
   registerNav,
   registerFeatureProvider,
   registerExtension,
+  // The inverted direction (TEAMS.md Part 3): the module declares, core fills.
+  declareModuleSlot,
   routesFor,
   navFor,
   featureProviderFor,

client/src/modules/shared.js

@@ -34,6 +34,7 @@ import { MODULE_API_VERSION } from './version.js'
 import PublicLayout from '../components/PublicLayout.jsx'
 import PageHeader from '../components/PageHeader.jsx'
 import { Loading, ErrorState, EmptyState } from '../components/PageState.jsx'
+import Slot from './Slot.jsx'
 import { useAsync } from '../lib/useAsync.js'
 import { useAuth } from '../contexts/AuthContext.jsx'
 import { useSite } from '../contexts/SiteContext.jsx'
@@ -66,6 +67,13 @@ const ui = {
   useAsync,
   useAuth,
   useSite,
+  // The eighth member, for the INVERTED slot direction (TEAMS.md Part 3). A
+  // module that declares a slot on its own page needs the same component core
+  // renders its own with — the error boundary in particular, since the thing
+  // being contained here is CORE's content failing inside the MODULE's page.
+  // Shared rather than reimplemented for the reason the whole kit exists: two
+  // boundaries with different behaviour would be two bugs.
+  Slot,
 }
 
 // The request PRIMITIVE, not the `api` object (§3.5): a module builds its own