@startsimpli/ui 0.4.85 → 0.4.87

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.85",
+  "version": "0.4.87",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -43,8 +43,8 @@
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@startsimpli/auth": "^0.4.31",
-    "@startsimpli/api": "^0.5.51"
+    "@startsimpli/api": "^0.5.53",
+    "@startsimpli/auth": "^0.4.32"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {

package/src/components/navigation/__tests__/entity-switcher.test.tsx

@@ -43,6 +43,20 @@ describe('EntitySwitcher — trigger', () => {
     expect(trigger).toHaveAttribute('aria-controls', listbox.id)
   })
 
+  it('takes an explicit accessible name for the trigger', () => {
+    // `combobox` is not a name-from-content role, so the trigger's visible
+    // "Acme Robotics" does NOT name it — without this prop it has no accessible
+    // name at all. startsim-768w.21.4 needs one (OrgSwitcher's caption is
+    // aria-hidden), and it has to carry the label AND the current entity.
+    setup()
+    expect(screen.getByRole('combobox')).not.toHaveAttribute('aria-label')
+
+    setup({ triggerAriaLabel: 'Organization: Acme Robotics' })
+    expect(
+      screen.getAllByRole('combobox', { name: 'Organization: Acme Robotics' })
+    ).toHaveLength(1)
+  })
+
   it('takes a triggerClassName override so it can sit on a dark rail', () => {
     setup({ triggerClassName: 'my-dark-trigger' })
     expect(screen.getByRole('combobox')).toHaveClass('my-dark-trigger')

package/src/components/navigation/__tests__/navigation.test.tsx

@@ -1,6 +1,9 @@
-import { render, screen, fireEvent } from '@testing-library/react'
+import { render, screen, fireEvent, within } from '@testing-library/react'
+import { usePathname } from 'next/navigation'
 import { Sidebar, SidebarLayout } from '../sidebar'
 
+const mockPathname = usePathname as unknown as jest.Mock
+
 // next/link and next/navigation are mocked via jest.config.js moduleNameMapper
 
 const sections = [
@@ -161,6 +164,105 @@ describe('Sidebar', () => {
   })
 })
 
+// ---------------------------------------------------------------------------
+// The rail as PRIMARY nav (startsim-768w.21.3)
+// ---------------------------------------------------------------------------
+
+/**
+ * A control plane puts its whole section list in the rail — a foundry
+ * contributes nine scoped links under a titled group. That promotes the rail
+ * from "app shortcuts" to the thing you navigate with, and a tab strip used to
+ * provide two things for free that the rail owes back:
+ *
+ *  • the current item ANNOUNCED, not just tinted. Colour is not an accessible
+ *    name; `aria-current="page"` is the standard for "you are here".
+ *  • "current" decided by path SEGMENT, not by string prefix.
+ *    '/foundry/x/builds'.startsWith('/foundry/x/build') is true, so a prefix
+ *    test lights up two peer surfaces at once — and the nine foundry sections
+ *    include exactly that pair.
+ *
+ * Plus a section addressable by its title, so a consumer can assert "these
+ * links, under this group" without walking up from a heading — and a pathname
+ * that may legitimately be null (the hook returns null outside an app-router
+ * provider) instead of throwing.
+ */
+describe('Sidebar — which link is current (768w.21.3)', () => {
+  const railLinks = [
+    { href: '/', label: 'Foundries' },
+    { href: '/foundry/mcr/build', label: 'Build with AI' },
+    { href: '/foundry/mcr/builds', label: 'Builds' },
+    { href: '/foundry/mcr/members', label: 'Members' },
+  ]
+
+  const renderAt = (pathname: string | null) => {
+    mockPathname.mockReturnValue(pathname)
+    return render(<Sidebar appName="Foundry" sections={[{ links: railLinks }]} />)
+  }
+
+  const current = () =>
+    screen
+      .getAllByRole('link')
+      .filter((a) => a.getAttribute('aria-current') === 'page')
+      .map((a) => a.getAttribute('href'))
+
+  afterEach(() => {
+    mockPathname.mockReturnValue('/test-path')
+  })
+
+  it('announces the current link with aria-current="page"', () => {
+    renderAt('/foundry/mcr/members')
+    expect(current()).toEqual(['/foundry/mcr/members'])
+  })
+
+  it('does not let a prefix sibling light up too', () => {
+    renderAt('/foundry/mcr/builds')
+    expect(current()).toEqual(['/foundry/mcr/builds'])
+  })
+
+  it('keeps a link current on a deeper URL under it', () => {
+    renderAt('/foundry/mcr/members/u-42')
+    expect(current()).toEqual(['/foundry/mcr/members'])
+  })
+
+  it('marks the root link current only at the root', () => {
+    renderAt('/')
+    expect(current()).toEqual(['/'])
+  })
+
+  it('renders with no current link rather than throwing on a null pathname', () => {
+    // usePathname() is null outside an app-router provider — shared chrome gets
+    // rendered in harnesses and tests that have no router.
+    expect(() => renderAt(null)).not.toThrow()
+    expect(current()).toEqual([])
+  })
+
+  it('still tints the current link, so the marker and the pill agree', () => {
+    renderAt('/foundry/mcr/builds')
+    expect(screen.getByText('Builds').closest('a')).toHaveClass('bg-primary')
+    expect(screen.getByText('Build with AI').closest('a')).not.toHaveClass('bg-primary')
+  })
+})
+
+describe('Sidebar — titled groups (768w.21.3)', () => {
+  const sectionsWithTitle = [
+    { links: [{ href: '/', label: 'Foundries' }] },
+    { title: 'My Copyright', links: [{ href: '/foundry/mcr/members', label: 'Members' }] },
+  ]
+
+  it('exposes a titled section as a group carrying that name', () => {
+    render(<Sidebar appName="Foundry" sections={sectionsWithTitle} />)
+    const group = screen.getByRole('group', { name: 'My Copyright' })
+    expect(within(group).getByRole('link', { name: 'Members' })).toBeInTheDocument()
+    expect(within(group).queryByRole('link', { name: 'Foundries' })).toBeNull()
+  })
+
+  it('keeps the group name while collapsed, when the heading is hidden', () => {
+    render(<Sidebar appName="Foundry" sections={sectionsWithTitle} defaultCollapsed />)
+    expect(screen.queryByText('My Copyright')).toBeNull()
+    expect(screen.getByRole('group', { name: 'My Copyright' })).toBeInTheDocument()
+  })
+})
+
 // ---------------------------------------------------------------------------
 // SidebarLayout
 // ---------------------------------------------------------------------------

package/src/components/navigation/entity-switcher.tsx

@@ -58,6 +58,14 @@ export interface EntitySwitcherProps {
   triggerPlaceholder?: string
   /** Set false to drop the filter input (short lists). */
   searchable?: boolean
+  /**
+   * Accessible name for the trigger. Left unset, the trigger is named by its
+   * own content — the current item's label — which reads correctly when the
+   * surrounding chrome already says WHAT is being switched (the sidebar rail).
+   * Set it when the control has to name itself, e.g. a switcher dropped into a
+   * settings page whose visible caption is `aria-hidden` (see OrgSwitcher).
+   */
+  triggerAriaLabel?: string
   /** Override the trigger chrome — e.g. to sit on a light surface. */
   triggerClassName?: string
   /** Override the popover panel chrome (width, padding, colours). */
@@ -79,6 +87,7 @@ export function EntitySwitcher({
   emptyLabel = 'No matches',
   triggerPlaceholder = 'Select…',
   searchable = true,
+  triggerAriaLabel,
   triggerClassName,
   contentClassName,
   disabled,
@@ -179,6 +188,7 @@ export function EntitySwitcher({
           aria-expanded={open}
           aria-controls={listboxId}
           aria-haspopup="listbox"
+          aria-label={triggerAriaLabel}
           disabled={disabled}
           className={cn(
             'flex w-full items-center justify-between gap-2 rounded-md border border-white/15 bg-white/5 px-3 py-2',

package/src/components/navigation/sidebar.tsx

@@ -71,7 +71,10 @@ export function Sidebar({
   collapsed: controlledCollapsed,
   onCollapsedChange,
 }: SidebarProps) {
-  const pathname = usePathname();
+  // usePathname() is null outside an app-router provider (harnesses, tests,
+  // a pages-router host). Shared chrome renders there too, so treat it as
+  // "no current page" rather than throwing on `null.startsWith`.
+  const pathname = usePathname() ?? '';
   const [internalCollapsed, setInternalCollapsed] = useState(defaultCollapsed);
   const collapsed = controlledCollapsed ?? internalCollapsed;
   const setCollapsed = (next: boolean) => {
@@ -79,12 +82,19 @@ export function Sidebar({
     onCollapsedChange?.(next);
   };
 
-  const isActivePath = (href: string) => {
-    if (href === '/') {
-      return pathname === '/';
-    }
-    return pathname.startsWith(href);
-  };
+  /**
+   * "You are here", by path SEGMENT rather than by string prefix.
+   *
+   * A prefix test lights up peers that merely share a stem —
+   * `/foundry/x/builds`.startsWith(`/foundry/x/build`) — and once a control
+   * plane puts its whole section list in the rail (startsim-768w.21.3) that
+   * pair is real: Build with AI and Builds sat next to each other, both lit.
+   * Requiring the next character to be a boundary keeps parent links current on
+   * their own sub-pages (`/leads` on `/leads/42`) without the collision. `/` is
+   * exact by the same rule, since nothing else starts with `//`.
+   */
+  const isActivePath = (href: string) =>
+    pathname === href || pathname.startsWith(`${href}/`);
 
   return (
     <div
@@ -115,9 +125,18 @@ export function Sidebar({
       {/* Navigation */}
       <nav className="flex-1 overflow-y-auto p-4 space-y-6">
         {sections.map((section, idx) => (
-          <div key={idx}>
+          // A named group, not an anonymous div: a titled section is a distinct
+          // scope ("the sections of THIS foundry"), and the name has to survive
+          // the collapsed rail hiding the heading — hence aria-label rather than
+          // aria-labelledby (startsim-768w.21.3).
+          <div key={idx} role="group" aria-label={section.title}>
             {section.title && !collapsed && (
-              <h3 className="text-xs font-semibold text-gray-400 uppercase tracking-wider mb-2 px-3">
+              // A group title can be a user-supplied record name (a foundry's
+              // branding), so it truncates instead of wrapping the rail open.
+              <h3
+                className="text-xs font-semibold text-gray-400 uppercase tracking-wider mb-2 px-3 truncate"
+                title={section.title}
+              >
                 {section.title}
               </h3>
             )}
@@ -128,6 +147,9 @@ export function Sidebar({
                   <Link
                     key={link.href}
                     href={link.href}
+                    // Colour is not an accessible name — say "you are here".
+                    aria-current={isActive ? 'page' : undefined}
+                    title={collapsed ? link.label : undefined}
                     className={cn(
                       'flex items-center gap-3 px-3 py-2 rounded-md text-sm font-medium transition-colors',
                       isActive
@@ -141,7 +163,7 @@ export function Sidebar({
                         {link.icon}
                       </span>
                     ) : null}
-                    {!collapsed && <span>{link.label}</span>}
+                    {!collapsed && <span className="min-w-0 truncate">{link.label}</span>}
                   </Link>
                 );
               })}

package/src/components/team/MembersSection.tsx

@@ -18,7 +18,7 @@
 import * as React from 'react'
 import { MembersTable } from './MembersTable'
 import { InviteMemberDialog } from './InviteMemberDialog'
-import type { InvitationLite, MemberRow, TeamRole } from './types'
+import type { InvitationLite, MemberRow, MemberSource, TeamRole } from './types'
 import {
   MEMBERS_SECTION_DEFAULTS,
   type MembersSectionClassNames,
@@ -62,9 +62,43 @@ export interface MembersSectionProps {
   inviteSuccessMessage?: (email: string) => string
   emptyState?: React.ReactNode
   helpText?: React.ReactNode
+  /**
+   * Narrow the list to ONE population (startsim-768w.20.4): the people who were
+   * invited, the people who signed themselves up, or the rows the platform
+   * seeded.
+   *
+   * A CONTROLLED prop, not internal state, and the composer never filters
+   * `members` itself. That is deliberate: the list is paginated server-side
+   * (repo rule 8), so a browser dropping rows from the page it happens to hold
+   * would shrink pages and lose people off the end. The host answers the change
+   * by re-querying.
+   */
+  sourceFilter?: MemberSourceFilter
   classNames?: MembersSectionClassNames
 }
 
+/** `all` is the absence of a filter, not a fourth population. */
+export type MemberSourceFilterValue = MemberSource | 'all'
+
+export interface MemberSourceFilter {
+  value: MemberSourceFilterValue
+  onChange: (value: MemberSourceFilterValue) => void
+  /** Override the offered options (default: everyone + the three origins). */
+  options?: MemberSourceFilterValue[]
+  label?: string
+}
+
+const SOURCE_FILTER_OPTIONS: MemberSourceFilterValue[] = [
+  'all', 'invited', 'self_signup', 'seed',
+]
+
+const SOURCE_FILTER_LABEL: Record<MemberSourceFilterValue, string> = {
+  all: 'Everyone',
+  invited: 'Invited',
+  self_signup: 'Signed up',
+  seed: 'Provisioned',
+}
+
 const defaultDescription = (count: number) =>
   `${count} ${count === 1 ? 'person has' : 'people have'} access.`
 
@@ -94,9 +128,11 @@ export function MembersSection({
   inviteSuccessMessage = (email) => `Invite sent to ${email} — they'll set a password and join`,
   emptyState,
   helpText,
+  sourceFilter,
   classNames,
 }: MembersSectionProps) {
   const cls = { ...MEMBERS_SECTION_DEFAULTS, ...(classNames ?? {}) }
+  const sourceOptions = sourceFilter?.options ?? SOURCE_FILTER_OPTIONS
 
   return (
     <div className={cls.root}>
@@ -125,6 +161,25 @@ export function MembersSection({
         </div>
       )}
       <div className={cls.body}>
+        {sourceFilter && (
+          <div className={cls.filterBar}>
+            <label htmlFor="members-source-filter" className={cls.filterLabel}>
+              {sourceFilter.label ?? 'How they joined'}
+            </label>
+            <select
+              id="members-source-filter"
+              className={cls.filterSelect}
+              value={sourceFilter.value}
+              onChange={(e) =>
+                sourceFilter.onChange(e.target.value as MemberSourceFilterValue)
+              }
+            >
+              {sourceOptions.map((o) => (
+                <option key={o} value={o}>{SOURCE_FILTER_LABEL[o]}</option>
+              ))}
+            </select>
+          </div>
+        )}
         <MembersTable
           members={members}
           canManage={canManage}

package/src/components/team/MembersTable.tsx

@@ -25,6 +25,7 @@ import {
   userDisplayName,
   userInitials,
   type MemberRow,
+  type MemberSource,
   type TeamRole,
 } from './types'
 import {
@@ -68,6 +69,12 @@ export interface MembersTableProps {
    */
   showStatus?: boolean
   showLastActive?: boolean
+  /**
+   * Force the "how they joined" column on/off (startsim-768w.20.4). Default:
+   * shown when any row carries `source`, so a backend that doesn't record
+   * provenance renders exactly as before.
+   */
+  showSource?: boolean
   classNames?: MembersTableClassNames
   /** Restrict role-selector options (e.g. hide 'owner' when caller isn't owner). */
   availableRoles?: TeamRole[]
@@ -102,6 +109,22 @@ function rowStatus(m: MemberRow): RowStatus | null {
   return m.inviteStatus ?? null
 }
 
+/**
+ * How they got here, in words a person reads (startsim-768w.20.4). "self_signup"
+ * is a wire value; "Signed up" is what the column says.
+ */
+const SOURCE_LABEL: Record<MemberSource, string> = {
+  invited: 'Invited',
+  self_signup: 'Signed up',
+  seed: 'Provisioned',
+}
+
+const SOURCE_TITLE: Record<MemberSource, string> = {
+  invited: 'Someone on this team added them by email',
+  self_signup: 'They created their own account through the app',
+  seed: 'Created by the platform when this workspace was set up',
+}
+
 /** Short absolute date. Absolute, not "3 days ago": an owner deciding whether to
  *  resend an invite wants the actual day. */
 function formatDate(iso: string): string {
@@ -132,6 +155,7 @@ export function MembersTable({
   emptyState,
   showStatus,
   showLastActive,
+  showSource,
   classNames,
   availableRoles,
   currentUserId,
@@ -139,13 +163,21 @@ export function MembersTable({
   const cls = { ...MEMBERS_TABLE_DEFAULTS, ...(classNames ?? {}) }
   const withStatus = showStatus ?? members.some((m) => rowStatus(m) !== null)
   const withLastActive = showLastActive ?? members.some((m) => m.lastLoginAt !== undefined)
+  const withSource = showSource ?? members.some((m) => m.source !== undefined)
   const statusClass: Record<RowStatus, string> = {
     active: cls.statusActive,
     pending: cls.statusPending,
     expired: cls.statusExpired,
     deactivated: cls.statusDeactivated,
   }
-  const columnCount = 2 + (withStatus ? 1 : 0) + (withLastActive ? 1 : 0) + (canManage ? 1 : 0)
+  const sourceClass: Record<MemberSource, string> = {
+    invited: cls.sourceInvited,
+    self_signup: cls.sourceSelfSignup,
+    seed: cls.sourceSeed,
+  }
+  const columnCount =
+    2 + (withStatus ? 1 : 0) + (withLastActive ? 1 : 0) + (withSource ? 1 : 0)
+    + (canManage ? 1 : 0)
   // Role + actions hug their content so the Member column takes the slack —
   // one shared cell class used to split the table down the middle and leave
   // the controls floating in a gap.
@@ -160,6 +192,9 @@ export function MembersTable({
             {withStatus && (
               <th className={tight(cls.th, cls.tightColumn)} scope="col">Status</th>
             )}
+            {withSource && (
+              <th className={tight(cls.th, cls.tightColumn)} scope="col">How they joined</th>
+            )}
             {withLastActive && (
               <th className={tight(cls.th, cls.tightColumn)} scope="col">Last active</th>
             )}
@@ -246,6 +281,19 @@ export function MembersTable({
                   )}
                 </td>
               )}
+              {withSource && (
+                <td className={tight(cls.cell, cls.tightColumn)}>
+                  {m.source && (
+                    <span
+                      className={tight(cls.sourceBadge, sourceClass[m.source])}
+                      data-member-source={m.source}
+                      title={SOURCE_TITLE[m.source]}
+                    >
+                      {SOURCE_LABEL[m.source]}
+                    </span>
+                  )}
+                </td>
+              )}
               {withLastActive && (
                 <td className={tight(cls.cell, cls.tightColumn)}>
                   {m.lastLoginAt ? (

package/src/components/team/OrgSwitcher.tsx

@@ -4,12 +4,20 @@
  * OrgSwitcher — pick between Companies the current user belongs to. Useful
  * for accounts that ended up multi-company via cross-domain invitations.
  *
- * Native <select> for now. The classNames-slot API stays the same when we
- * upgrade to a dropdown menu. startsim-o7s.
+ * A thin adapter over the shared <EntitySwitcher> (startsim-768w.21.4): it maps
+ * `CompanyLite` -> `EntitySwitcherItem` and hands the chosen id back. The
+ * native <select> this used to render (startsim-o7s, "for now") is gone, so
+ * packages/ui ships ONE switcher implementation rather than two.
+ *
+ * The public props and `classNames` slots are unchanged — `select` now styles
+ * the combobox trigger that replaced the <select>, and its defaults are
+ * semantic tokens tuned for the LIGHT surfaces this renders on, where
+ * EntitySwitcher's own translucent-over-dark rail defaults would wash out.
  */
 
 import * as React from 'react'
 import type { CompanyLite } from './types'
+import { EntitySwitcher, type EntitySwitcherItem } from '../navigation/entity-switcher'
 import {
   ORG_SWITCHER_DEFAULTS,
   type OrgSwitcherClassNames,
@@ -34,9 +42,20 @@ export function OrgSwitcher({
   classNames,
 }: OrgSwitcherProps) {
   const cls = { ...ORG_SWITCHER_DEFAULTS, ...(classNames ?? {}) }
-  // If the caller hasn't pinned currentCompanyId, fall back to the first
-  // entry so the <select>'s value matches an option (otherwise React warns).
-  const value = currentCompanyId ?? companies[0]?.id ?? ''
+
+  const items = React.useMemo<EntitySwitcherItem[]>(
+    // The slug rides along as the sublabel so it is searchable too — two
+    // companies can share a display name, their slugs cannot.
+    () => companies.map((c) => ({ id: c.id, label: c.name, sublabel: c.slug || undefined })),
+    [companies]
+  )
+
+  // If the caller hasn't pinned currentCompanyId, fall back to the first entry
+  // so the control always names a real company — as the <select> did, where a
+  // value matching no option made React warn — rather than falling through to
+  // a "Select…" placeholder for a list it is already scoped to.
+  const currentId = currentCompanyId ?? companies[0]?.id ?? null
+  const currentName = companies.find((c) => c.id === currentId)?.name
 
   if (companies.length === 0) return null
 
@@ -47,22 +66,22 @@ export function OrgSwitcher({
           {label}
         </span>
       )}
-      <label className="sr-only" htmlFor="org-switcher-select">
-        {label}
-      </label>
-      <select
-        id="org-switcher-select"
-        value={value}
-        onChange={(e) => onSwitch(e.target.value)}
-        className={cls.select}
-        aria-label={label}
-      >
-        {companies.map((c) => (
-          <option key={c.id} value={c.id}>
-            {c.name}
-          </option>
-        ))}
-      </select>
+      <EntitySwitcher
+        items={items}
+        currentId={currentId}
+        // onSwitch may be async; the <select>'s onChange ignored the promise too.
+        onSelect={(id) => {
+          void onSwitch(id)
+        }}
+        // Stands in for the sr-only <label htmlFor> + aria-label the <select>
+        // carried. The trigger is a button, so a bare `aria-label={label}`
+        // would suppress the company name it renders — the accessible name
+        // has to carry both parts.
+        triggerAriaLabel={currentName ? `${label}: ${currentName}` : label}
+        triggerPlaceholder={`Select ${label.toLowerCase()}…`}
+        triggerClassName={cls.select}
+        contentClassName={cls.content}
+      />
     </span>
   )
 }

package/src/components/team/__tests__/member-provenance.test.tsx

@@ -0,0 +1,132 @@
+/**
+ * RED (startsim-768w.20.4.1): the members list cannot show two populations.
+ *
+ * Every row renders identically today, so an OPEN foundry's roster puts the
+ * three people who RUN the app and the two hundred who merely USE it in one
+ * undifferentiated table under the heading "N people can access and manage this
+ * foundry". Role does not separate them either — an invited viewer and a
+ * self-joined viewer are the same word.
+ *
+ * The provenance is DATA the backend records (768w.20.4.2). These tests fail
+ * until the shared list renders it and offers a way to ask for one population,
+ * because per rule 9 "how did this person get here" is a members-list concern,
+ * not a foundry-app one — /settings/team has the same two populations the
+ * moment any app opens its own door.
+ */
+
+import { render, screen, fireEvent } from '@testing-library/react'
+import { MembersTable, MembersSection } from '../index'
+import type { MemberRow } from '../types'
+
+const rows: MemberRow[] = [
+  {
+    id: 'm1',
+    userId: 'u1',
+    teamId: 'qafoundry',
+    role: 'owner',
+    joinedAt: '2026-01-01T00:00:00Z',
+    inviteStatus: 'active',
+    source: 'seed',
+    user: { id: 'u1', email: 'owner@ogmc.ai' },
+  },
+  {
+    id: 'm2',
+    userId: 'u2',
+    teamId: 'qafoundry',
+    role: 'admin',
+    joinedAt: '2026-02-01T00:00:00Z',
+    inviteStatus: 'active',
+    source: 'invited',
+    invitedByEmail: 'owner@ogmc.ai',
+    user: { id: 'u2', email: 'nordby@ogmc.ai' },
+  },
+  {
+    id: 'm3',
+    userId: 'u3',
+    teamId: 'qafoundry',
+    role: 'viewer',
+    joinedAt: '2026-07-01T00:00:00Z',
+    inviteStatus: 'active',
+    source: 'self_signup',
+    user: { id: 'u3', email: 'fan@example.com' },
+  },
+]
+
+describe('MembersTable shows how each person got here (768w.20.4.1)', () => {
+  it('renders a joined-how column when the rows carry provenance', () => {
+    render(<MembersTable members={rows} />)
+    expect(screen.getByRole('columnheader', { name: /how they joined/i })).toBeInTheDocument()
+  })
+
+  it('separates an operator from an end user at a glance', () => {
+    const { container } = render(<MembersTable members={rows} />)
+    const badges = Array.from(container.querySelectorAll('[data-member-source]'))
+    expect(badges.map((b) => b.getAttribute('data-member-source'))).toEqual([
+      'seed',
+      'invited',
+      'self_signup',
+    ])
+    // Product language, not the wire value — "self_signup" is not a thing a
+    // person reads.
+    expect(screen.getByText(/signed up/i)).toBeInTheDocument()
+    expect(screen.getByText(/invited/i)).toBeInTheDocument()
+  })
+
+  it('drops the column entirely for a backend that does not report it', () => {
+    const legacy = rows.map(({ source: _source, ...rest }) => rest)
+    render(<MembersTable members={legacy} />)
+    expect(screen.queryByRole('columnheader', { name: /how they joined/i })).toBeNull()
+  })
+})
+
+describe('MembersSection asks the SERVER for one population (768w.20.4.1)', () => {
+  it('offers a filter and reports the choice back to the host', () => {
+    const onSourceChange = jest.fn()
+    render(
+      <MembersSection
+        members={rows}
+        teamId="qafoundry"
+        sourceFilter={{ value: 'all', onChange: onSourceChange }}
+      />,
+    )
+    const select = screen.getByLabelText(/how they joined/i) as HTMLSelectElement
+    fireEvent.change(select, { target: { value: 'self_signup' } })
+    expect(onSourceChange).toHaveBeenCalledWith('self_signup')
+  })
+
+  it('offers exactly the three populations plus "everyone"', () => {
+    render(
+      <MembersSection
+        members={rows}
+        teamId="qafoundry"
+        sourceFilter={{ value: 'all', onChange: jest.fn() }}
+      />,
+    )
+    const select = screen.getByLabelText(/how they joined/i) as HTMLSelectElement
+    expect(Array.from(select.options).map((o) => o.value)).toEqual([
+      'all',
+      'invited',
+      'self_signup',
+      'seed',
+    ])
+  })
+
+  it('does not filter the rows itself — the list is paginated', () => {
+    // A browser-side filter over one PAGE shrinks pages and loses people off the
+    // end (repo rule 8). The composer renders exactly what it was handed.
+    render(
+      <MembersSection
+        members={rows}
+        teamId="qafoundry"
+        sourceFilter={{ value: 'self_signup', onChange: jest.fn() }}
+      />,
+    )
+    expect(screen.getByText('owner@ogmc.ai')).toBeInTheDocument()
+    expect(screen.getByText('fan@example.com')).toBeInTheDocument()
+  })
+
+  it('renders no filter at all when the host does not offer one', () => {
+    render(<MembersSection members={rows} teamId="qafoundry" />)
+    expect(screen.queryByLabelText(/how they joined/i)).toBeNull()
+  })
+})

package/src/components/team/__tests__/team-components.test.tsx

@@ -1,4 +1,5 @@
-import { render, screen, fireEvent, act } from '@testing-library/react'
+import { render, screen, fireEvent, act, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
 import {
   MembersTable,
   RoleSelector,
@@ -370,20 +371,41 @@ describe('LeaveTeamDialog', () => {
 
 // ---------- OrgSwitcher ----------------------------------------------------
 
+/**
+ * Since startsim-768w.21.4 OrgSwitcher is a thin adapter over the shared
+ * <EntitySwitcher>: the control is a combobox trigger + popover listbox, not a
+ * native <select>, so the assertions read the current company off the trigger
+ * and pick from role=option instead of setting `select.value`. The public props
+ * and classNames slots are unchanged, and every behaviour the <select> version
+ * had is still pinned below.
+ */
 describe('OrgSwitcher', () => {
   const companies: CompanyLite[] = [
     { id: 'c1', slug: 'acme', name: 'Acme' },
     { id: 'c2', slug: 'beta', name: 'Beta' },
   ]
 
-  it('renders an option per company + fires onSwitch on change', () => {
+  it('renders an option per company + fires onSwitch on pick', async () => {
+    const user = userEvent.setup()
     const onSwitch = jest.fn()
-    render(
+    const { container } = render(
       <OrgSwitcher companies={companies} currentCompanyId="c1" onSwitch={onSwitch} />
     )
-    const select = screen.getByRole('combobox') as HTMLSelectElement
-    expect(select.value).toBe('c1')
-    fireEvent.change(select, { target: { value: 'c2' } })
+
+    // One switcher in packages/ui, not two: no native <select> is left.
+    expect(container.querySelector('select')).toBeNull()
+
+    const trigger = screen.getByRole('combobox')
+    expect(trigger).toHaveTextContent('Acme')
+
+    await user.click(trigger)
+    expect(await screen.findAllByRole('option')).toHaveLength(2)
+    expect(screen.getByRole('option', { name: /Acme/ })).toHaveAttribute(
+      'aria-selected',
+      'true'
+    )
+
+    await user.click(screen.getByRole('option', { name: /Beta/ }))
     expect(onSwitch).toHaveBeenCalledWith('c2')
   })
 
@@ -393,4 +415,100 @@ describe('OrgSwitcher', () => {
     )
     expect(container.firstChild).toBeNull()
   })
+
+  it('falls back to the first company when currentCompanyId is not pinned', () => {
+    render(<OrgSwitcher companies={companies} onSwitch={() => {}} />)
+    // Never a bare "Select organization…" placeholder for a list it is already
+    // scoped to — the <select> pinned its value the same way.
+    expect(screen.getByRole('combobox')).toHaveTextContent('Acme')
+  })
+
+  it('names the trigger with the label AND the current company', () => {
+    render(
+      <OrgSwitcher companies={companies} currentCompanyId="c2" onSwitch={() => {}} />
+    )
+    // Replaces the sr-only <label> + aria-label the <select> had. A button
+    // named only "Organization" would hide which org is in scope.
+    expect(screen.getByRole('combobox')).toHaveAttribute(
+      'aria-label',
+      'Organization: Beta'
+    )
+    expect(
+      screen.getByRole('combobox', { name: /organization: beta/i })
+    ).toBeInTheDocument()
+  })
+
+  it('hides the visible caption with hideLabel but keeps the accessible name', () => {
+    const { rerender } = render(
+      <OrgSwitcher companies={companies} currentCompanyId="c1" onSwitch={() => {}} />
+    )
+    expect(screen.getByText('Organization')).toBeInTheDocument()
+
+    rerender(
+      <OrgSwitcher
+        companies={companies}
+        currentCompanyId="c1"
+        onSwitch={() => {}}
+        hideLabel
+      />
+    )
+    expect(screen.queryByText('Organization')).not.toBeInTheDocument()
+    expect(screen.getByRole('combobox')).toHaveAttribute(
+      'aria-label',
+      'Organization: Acme'
+    )
+  })
+
+  it('honours a custom label everywhere it surfaces', () => {
+    render(
+      <OrgSwitcher
+        companies={companies}
+        currentCompanyId="c1"
+        onSwitch={() => {}}
+        label="Workspace"
+      />
+    )
+    expect(screen.getByText('Workspace')).toBeInTheDocument()
+    expect(screen.getByRole('combobox')).toHaveAttribute(
+      'aria-label',
+      'Workspace: Acme'
+    )
+  })
+
+  it('routes the classNames slots at the label and the trigger', () => {
+    render(
+      <OrgSwitcher
+        companies={companies}
+        currentCompanyId="c1"
+        onSwitch={() => {}}
+        classNames={{ label: 'my-label', select: 'my-trigger' }}
+      />
+    )
+    expect(screen.getByText('Organization')).toHaveClass('my-label')
+    expect(screen.getByRole('combobox')).toHaveClass('my-trigger')
+  })
+
+  it('filters companies by name or slug — the upgrade the <select> could not do', async () => {
+    const user = userEvent.setup()
+    render(
+      <OrgSwitcher companies={companies} currentCompanyId="c1" onSwitch={() => {}} />
+    )
+    await user.click(screen.getByRole('combobox'))
+    // "beta" is Beta's slug as well as its name; either way it is the only hit.
+    await user.type(await screen.findByRole('textbox'), 'BET')
+
+    await waitFor(() => expect(screen.getAllByRole('option')).toHaveLength(1))
+    expect(screen.getByRole('option')).toHaveTextContent('Beta')
+  })
+
+  it('tolerates an async onSwitch', async () => {
+    const user = userEvent.setup()
+    const onSwitch = jest.fn().mockResolvedValue(undefined)
+    render(
+      <OrgSwitcher companies={companies} currentCompanyId="c1" onSwitch={onSwitch} />
+    )
+    await user.click(screen.getByRole('combobox'))
+    await user.click(await screen.findByRole('option', { name: /Beta/ }))
+    expect(onSwitch).toHaveBeenCalledWith('c2')
+  })
 })

package/src/components/team/index.ts

@@ -13,7 +13,9 @@ export type { MembersTableClassNames } from './members-table-default-class-names
 export { MEMBERS_TABLE_DEFAULTS } from './members-table-default-class-names'
 
 export { MembersSection } from './MembersSection'
-export type { MembersSectionProps } from './MembersSection'
+export type {
+  MembersSectionProps, MemberSourceFilter, MemberSourceFilterValue,
+} from './MembersSection'
 export type { MembersSectionClassNames } from './members-section-default-class-names'
 export { MEMBERS_SECTION_DEFAULTS } from './members-section-default-class-names'
 
@@ -57,6 +59,7 @@ export {
   type MemberUserLite,
   type MemberRow,
   type InviteStatus,
+  type MemberSource,
   type InvitationLite,
   type DomainVerificationMethod,
   type DomainClaimLite,

package/src/components/team/members-section-default-class-names.ts

@@ -12,6 +12,10 @@ export interface MembersSectionClassNames {
   body?: string
   errorText?: string
   helpText?: string
+  /** Row holding the list's narrowing controls (startsim-768w.20.4). */
+  filterBar?: string
+  filterLabel?: string
+  filterSelect?: string
   /** Forwarded to the nested primitives so an app still overrides one map. */
   table?: MembersTableClassNames
   inviteDialog?: InviteMemberDialogClassNames
@@ -28,4 +32,8 @@ export const MEMBERS_SECTION_DEFAULTS: Required<
   body: 'space-y-3',
   errorText: 'text-sm text-destructive',
   helpText: 'text-xs text-muted-foreground',
+  filterBar: 'flex flex-wrap items-center gap-2',
+  filterLabel: 'text-xs font-medium text-muted-foreground',
+  filterSelect:
+    'rounded-md border border-border bg-background px-2 py-1 text-xs text-foreground',
 }

package/src/components/team/members-table-default-class-names.ts

@@ -34,6 +34,13 @@ export interface MembersTableClassNames {
   lastActiveEmpty?: string
   /** "Invited by …" line under a member who hasn't activated yet. */
   invitedBy?: string
+  /** Shared shape of the "how they joined" pill (startsim-768w.20.4). */
+  sourceBadge?: string
+  /** Per-origin colour. The point of the column is that an operator and an
+   *  end user do not look the same, so these must not collapse to one class. */
+  sourceInvited?: string
+  sourceSelfSignup?: string
+  sourceSeed?: string
   /** Resend-invite action on a pending/expired row. */
   resendButton?: string
   /** Deactivate / Restore action — the soft exit next to the hard Remove. */
@@ -73,6 +80,12 @@ export const MEMBERS_TABLE_DEFAULTS: Required<MembersTableClassNames> = {
   lastActive: 'text-muted-foreground',
   lastActiveEmpty: 'text-muted-foreground/70',
   invitedBy: 'text-xs text-muted-foreground/80',
+  sourceBadge:
+    'inline-flex items-center rounded-full border px-2 py-0.5 text-xs font-medium',
+  sourceInvited: 'border-border bg-muted text-muted-foreground',
+  // The population an operator most needs to pick out of a long list.
+  sourceSelfSignup: 'border-primary/30 bg-primary/10 text-primary',
+  sourceSeed: 'border-border bg-muted/60 text-muted-foreground',
   resendButton:
     'rounded-md border border-border px-2 py-1 text-xs text-muted-foreground transition-colors hover:border-primary/40 hover:bg-primary/10 hover:text-primary disabled:opacity-50',
   deactivateButton:

package/src/components/team/org-switcher-default-class-names.ts

@@ -3,12 +3,30 @@
 export interface OrgSwitcherClassNames {
   root?: string
   label?: string
+  /**
+   * The switcher control itself. Named `select` since startsim-o7s, when it
+   * WAS a native `<select>`; startsim-768w.21.4 swapped the implementation for
+   * the shared `<EntitySwitcher>` and this slot now styles its combobox
+   * trigger. The name is kept so existing overrides keep landing on the same
+   * visual element.
+   */
   select?: string
+  /**
+   * The popover panel that replaced the browser's native dropdown
+   * (startsim-768w.21.4) — width/padding/colour of the list surface.
+   */
+  content?: string
 }
 
 export const ORG_SWITCHER_DEFAULTS: Required<OrgSwitcherClassNames> = {
   root: 'inline-flex items-center gap-2',
   label: 'text-xs font-medium uppercase tracking-wide text-muted-foreground',
+  // EntitySwitcher's own trigger defaults are translucent-over-dark, tuned for
+  // the `bg-gray-900` sidebar rail. OrgSwitcher renders on LIGHT surfaces
+  // (settings pages, headers), so each of those has to be overridden with a
+  // semantic token — including the `hover:` / `focus-visible:` variants, which
+  // tailwind-merge cannot fold into an unprefixed override.
   select:
-    'rounded-md border border-input bg-background px-3 py-1.5 text-sm font-medium text-foreground outline-none transition-colors focus:border-ring focus:ring-1 focus:ring-ring',
+    'w-auto min-w-44 rounded-md border border-input bg-background px-3 py-1.5 text-sm font-medium text-foreground transition-colors hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring',
+  content: 'w-64',
 }

package/src/components/team/types.ts

@@ -44,6 +44,16 @@ export interface MemberUserLite {
  */
 export type InviteStatus = 'active' | 'pending' | 'expired'
 
+/**
+ * HOW someone came to be on this list (startsim-768w.20.4).
+ *
+ * The distinction `role` cannot make. Once a workspace can be joined without an
+ * invite, its member list carries two populations — the handful of people who
+ * RUN it and everyone who merely USES it — and an invited viewer reads exactly
+ * like a self-joined viewer.
+ */
+export type MemberSource = 'invited' | 'self_signup' | 'seed'
+
 export interface MemberRow {
   id: string
   userId: string
@@ -54,6 +64,9 @@ export interface MemberRow {
   user?: MemberUserLite
   /** Lifecycle state. Absent for backends that don't report it (older list APIs). */
   inviteStatus?: InviteStatus
+  /** How they got here. Absent for backends that don't record it — the table
+   *  then drops the column rather than rendering an empty one. */
+  source?: MemberSource
   /** Last sign-in, or null for someone who has never signed in. */
   lastLoginAt?: string | null
   /** When the outstanding invite link dies. Null once there is no live invite. */