@startsimpli/ui 0.4.111 → 0.4.112

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.111",
+  "version": "0.4.112",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -47,9 +47,9 @@
     "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/api": "^0.5.58",
     "@startsimpli/auth": "^0.4.35",
-    "@startsimpli/i18n": "^0.1.3"
+    "@startsimpli/i18n": "^0.1.3",
+    "@startsimpli/api": "^0.5.58"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {
@@ -123,8 +123,8 @@
     "tailwindcss": "^3.4.19",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "@startsimpli/realtime": "0.0.2",
-    "@startsimpli/i18n": "0.1.3"
+    "@startsimpli/i18n": "0.1.3",
+    "@startsimpli/realtime": "0.0.2"
   },
   "keywords": [
     "ui",

package/src/components/collection/DraftReviewWorkspace.tsx

@@ -18,6 +18,7 @@ import { notify } from '../toast/use-notify';
 import { MarkdownRenderer } from '../blog/MarkdownRenderer';
 import type { CollectionClient, EntityRecord } from './types';
 import { readData, toCamelKey } from './data';
+import { scopeKey } from './scoped-client';
 import {
   groupDrafts,
   parseSources,
@@ -58,10 +59,14 @@ export interface DraftReviewWorkspaceProps {
 
 export function DraftReviewWorkspace({ client }: DraftReviewWorkspaceProps) {
   const qc = useQueryClient();
+  // The injected client's bound, in the cache key — see the same note on
+  // TopicReviewWorkspace: a scope change that does not change the key serves the
+  // previous client's drafts under the new client's name.
+  const scope = scopeKey(client);
   const typesQ = useQuery({ queryKey: ['schema-types'], queryFn: () => client.listTypes() });
   const draftType = typesQ.data?.results.find((t) => t.key === 'draft');
   const recordsQ = useQuery({
-    queryKey: ['entities', 'draft', 'all'],
+    queryKey: ['entities', 'draft', 'all', scope],
     queryFn: () => client.listAllEntities('draft'),
     enabled: !!draftType,
   });
@@ -70,8 +75,12 @@ export function DraftReviewWorkspace({ client }: DraftReviewWorkspaceProps) {
   // A story whose topic was rejected shouldn't keep cluttering the review — its
   // drafts collapse into the "Rejected" section, mirroring the topic list
   // (startsim-ay9l follow-up). draft.topic_ref is the topic's entity id.
+  // SCOPED, unlike the source registry below: a topic is a client's own work,
+  // not shared corpus, and this read decides which of THIS board's drafts are
+  // collapsed as rejected. Reading it unscoped would let another client's topic
+  // ids reach the decision.
   const topicsQ = useQuery({
-    queryKey: ['entities', 'topic', 'all'],
+    queryKey: ['entities', 'topic', 'all', scope],
     queryFn: () => client.listAllEntities('topic'),
     enabled: !!draftType,
   });
@@ -83,9 +92,11 @@ export function DraftReviewWorkspace({ client }: DraftReviewWorkspaceProps) {
     return s;
   }, [topicsQ.data]);
 
+  // UNSCOPED — the source registry is shared across scopes (epic
+  // startsim-ux39t) and this is a domain→tier lookup, not the client's work.
   const sourcesQ = useQuery({
     queryKey: ['entities', 'source', 'all'],
-    queryFn: () => client.listAllEntities('source'),
+    queryFn: () => client.listAllEntities('source', { scoped: false }),
     enabled: !!draftType,
   });
   const tierByDomain = useMemo(() => {
@@ -112,6 +123,9 @@ export function DraftReviewWorkspace({ client }: DraftReviewWorkspaceProps) {
   const [showRejected, setShowRejected] = useState(false);
 
   async function writeEntity(record: EntityRecord, changes: Record<string, unknown>) {
+    // The FULL blob, spread from the record: PATCH REPLACES `data`, so an
+    // attribute this board never touches — the scope path included — has to be
+    // sent back to survive. A write is never a move between scopes.
     const data: Record<string, unknown> = { ...record.data };
     for (const [k, v] of Object.entries(changes)) data[toCamelKey(k)] = v;
     return client.updateEntity(record.id, { data });
@@ -153,6 +167,18 @@ export function DraftReviewWorkspace({ client }: DraftReviewWorkspaceProps) {
   if (!draftType) {
     return <p className="text-sm text-gray-500">No “draft” type is defined for this app.</p>;
   }
+  // See TopicReviewWorkspace: a scoped list can be refused (a type with no
+  // declared scope path is a 400), and an unreported refusal renders as an empty
+  // board rather than as a problem.
+  if (recordsQ.isError) {
+    return (
+      <p className="rounded-lg border border-rose-200 bg-rose-50 p-4 text-sm text-rose-700">
+        Could not load drafts
+        {scope === 'all' ? '' : ` for ${scope}`}:{' '}
+        {recordsQ.error instanceof Error ? recordsQ.error.message : 'the request was refused.'}
+      </p>
+    );
+  }
 
   const pickedCount = activeGroups.filter((g) => g.chosen).length;
   const readyCount = activeGroups.filter((g) => g.ready).length;

package/src/components/collection/TopicReviewWorkspace.tsx

@@ -18,6 +18,7 @@ import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '.
 import { notify } from '../toast/use-notify';
 import type { CollectionClient, EntityRecord, EntityTypeDef } from './types';
 import { readData, toCamelKey } from './data';
+import { scopeKey } from './scoped-client';
 
 const STATUSES = ['suggested', 'ready', 'rejected', 'written'] as const;
 const VERDICTS = [
@@ -52,18 +53,26 @@ export interface TopicReviewWorkspaceProps {
 
 export function TopicReviewWorkspace({ client, markets = [], renderDetail }: TopicReviewWorkspaceProps) {
   const qc = useQueryClient();
+  // The bound the injected client is carrying. IT IS PART OF THE CACHE KEY, and
+  // that is not bookkeeping: without it a scope change reuses the previous
+  // scope's rows — the request would carry the new scope and the board would
+  // still show the old client's topics, which is worse than not scoping at all.
+  const scope = scopeKey(client);
   const typesQ = useQuery({ queryKey: ['schema-types'], queryFn: () => client.listTypes() });
   const topicType = typesQ.data?.results.find((t) => t.key === 'topic');
   const recordsQ = useQuery({
-    queryKey: ['entities', 'topic', 'all'],
+    queryKey: ['entities', 'topic', 'all', scope],
     queryFn: () => client.listAllEntities('topic'),
     enabled: !!topicType,
   });
   const records = recordsQ.data ?? [];
 
+  // The source registry is SHARED across scopes (epic startsim-ux39t) and this
+  // is a tier lookup, not a list of the client's work — so it is read unscoped
+  // and keyed without the scope, one fetch for every bound rather than one each.
   const sourcesQ = useQuery({
     queryKey: ['entities', 'source', 'all'],
-    queryFn: () => client.listAllEntities('source'),
+    queryFn: () => client.listAllEntities('source', { scoped: false }),
     enabled: !!topicType,
   });
   const tierByDomain = useMemo(() => {
@@ -98,6 +107,9 @@ export function TopicReviewWorkspace({ client, markets = [], renderDetail }: Top
     const data: Record<string, unknown> = { ...record.data };
     for (const [k, v] of Object.entries(changes)) data[toCamelKey(k)] = v;
     try {
+      // The FULL blob, spread from the record — so an attribute this workspace
+      // never touches (the scope path among them) survives a PATCH that
+      // REPLACES the blob rather than merging it. A write is never a move.
       await client.updateEntity(record.id, { data });
       await qc.invalidateQueries({ queryKey: ['entities', 'topic'] });
     } catch (err) {
@@ -111,6 +123,20 @@ export function TopicReviewWorkspace({ client, markets = [], renderDetail }: Top
   if (!topicType) {
     return <p className="text-sm text-gray-500">No “topic” type is defined for this app.</p>;
   }
+  // A SCOPED LIST CAN NOW FAIL, so it has to be able to say so. `?scope=` on a
+  // type that declares no scope path is a 400 (bd startsim-mj609) — and an
+  // unreported error renders as an empty board, which reads as "this client has
+  // no topics". Silently empty under an active bound is the same class of lie
+  // as silently widening.
+  if (recordsQ.isError) {
+    return (
+      <p className="rounded-lg border border-rose-200 bg-rose-50 p-4 text-sm text-rose-700">
+        Could not load topics
+        {scope === 'all' ? '' : ` for ${scope}`}:{' '}
+        {recordsQ.error instanceof Error ? recordsQ.error.message : 'the request was refused.'}
+      </p>
+    );
+  }
 
   return (
     <div className="space-y-6">

package/src/components/collection/__tests__/scoped-client.test.ts

@@ -0,0 +1,243 @@
+/**
+ * `withScope` — the one seam (bd startsim-nq39j, epic startsim-ux39t).
+ *
+ * These pin the four things the bead asked to be TESTED rather than inspected:
+ * a list read carries the active scope, a blank one never reaches the wire, a
+ * request with no type never carries a scope at all, and a write cannot move a
+ * row between scopes.
+ *
+ * WHY THE ASSERTIONS LOOK AT THE ABSENCE OF A KEY. `?scope=` (blank) and
+ * `?scope=all` are both 400s server-side, and the blank one is the dangerous
+ * one — `normalize_container("")` returns `/`, so an implementation that sends
+ * an empty parameter is asking for EVERY scoped row while believing it asked
+ * for none (bd startsim-mj609). `toHaveProperty` is therefore the right
+ * assertion and `toBe('')` is not.
+ */
+import { resolveScope, scopeFilters, scopeKey, withScope, SCOPE_FILTER } from '../scoped-client';
+import type { CollectionClient, EntityRecord, EntityTypeDef, ListEntitiesOptions, Paginated } from '../types';
+
+function page<T>(results: T[]): Paginated<T> {
+  return { count: results.length, next: null, previous: null, results };
+}
+
+function record(over: Partial<EntityRecord> = {}): EntityRecord {
+  return {
+    id: 1,
+    entityType: 'topic',
+    externalId: null,
+    name: 'A topic',
+    data: {},
+    createdAt: '2026-08-27T00:00:00Z',
+    ...over,
+  };
+}
+
+function stub() {
+  const listTypes = jest.fn(async () => page<EntityTypeDef>([]));
+  const listAllEntities = jest.fn(async (_type: string, _options?: ListEntitiesOptions) => [record()]);
+  const updateEntity = jest.fn(async () => record());
+  const client: CollectionClient = { listTypes, listAllEntities, updateEntity };
+  return { client, listTypes, listAllEntities, updateEntity };
+}
+
+/** The filters bag as it was actually handed down, whatever the call shape. */
+function filtersOf(mock: jest.Mock, call = 0): Record<string, string> {
+  const options = mock.mock.calls[call]?.[1] as ListEntitiesOptions | undefined;
+  return options?.filters ?? {};
+}
+
+// --------------------------------------------------------------------------
+// resolveScope / scopeFilters — the wire spelling of "everything"
+// --------------------------------------------------------------------------
+
+describe('resolveScope — every spelling of "no bound" is one value', () => {
+  it.each([
+    ['null', null],
+    ['undefined', undefined],
+    ['empty', ''],
+    ['whitespace', '   '],
+    // The BROWSER URL's reserved word. A caller can reach the raw parameter
+    // without going through useScopeParam — a server component reading
+    // searchParams, a test, an app keeping the scope elsewhere — so `all` has to
+    // mean the same thing here as it does there.
+    ['the reserved word "all"', 'all'],
+  ])('resolves %s to null', (_label, input) => {
+    expect(resolveScope(input as string | null | undefined)).toBeNull();
+  });
+
+  it('keeps a real path, trimmed, verbatim', () => {
+    expect(resolveScope('  /clients/acme  ')).toBe('/clients/acme');
+  });
+
+  it('passes a malformed path THROUGH rather than dropping it', () => {
+    // The server refuses a value with no leading separator, and that refusal is
+    // the right answer: dropping it would silently widen to the whole corpus
+    // under a filter the reader believes is active.
+    expect(resolveScope('clients/acme')).toBe('clients/acme');
+  });
+});
+
+describe('scopeFilters — a blank scope is never on the wire', () => {
+  it.each([[null], [undefined], [''], ['   '], ['all']])(
+    'emits NO scope key at all for %p',
+    (input) => {
+      const filters = scopeFilters(input as string | null | undefined);
+      expect(filters).not.toHaveProperty(SCOPE_FILTER);
+      expect(Object.keys(filters)).toHaveLength(0);
+    },
+  );
+
+  it('emits the path when there is one', () => {
+    expect(scopeFilters('/clients/acme')).toEqual({ scope: '/clients/acme' });
+  });
+});
+
+// --------------------------------------------------------------------------
+// list reads
+// --------------------------------------------------------------------------
+
+describe('withScope — with a scope active, every list request carries it', () => {
+  it('puts the scope in the FILTERS bag, which the app puts in the URL string', async () => {
+    const { client, listAllEntities } = stub();
+    await withScope(client, '/clients/acme').listAllEntities('topic');
+    expect(filtersOf(listAllEntities)).toEqual({ scope: '/clients/acme' });
+  });
+
+  it('carries it on every type a workspace reads, not just the first', async () => {
+    const { client, listAllEntities } = stub();
+    const scoped = withScope(client, '/clients/acme');
+    await scoped.listAllEntities('topic');
+    await scoped.listAllEntities('draft');
+    expect(filtersOf(listAllEntities, 0)).toEqual({ scope: '/clients/acme' });
+    expect(filtersOf(listAllEntities, 1)).toEqual({ scope: '/clients/acme' });
+  });
+
+  it('keeps the caller’s own filters alongside it', async () => {
+    const { client, listAllEntities } = stub();
+    await withScope(client, '/clients/acme').listAllEntities('draft', {
+      filters: { 'attr.published_at__gte': '2026-08-10' },
+    });
+    expect(filtersOf(listAllEntities)).toEqual({
+      scope: '/clients/acme',
+      'attr.published_at__gte': '2026-08-10',
+    });
+  });
+
+  it('does not overrule a caller that sent its own scope', async () => {
+    const { client, listAllEntities } = stub();
+    await withScope(client, '/clients/acme').listAllEntities('draft', {
+      filters: { scope: '/clients/globex' },
+    });
+    expect(filtersOf(listAllEntities).scope).toBe('/clients/globex');
+  });
+
+  it('sends no scope key when nothing is in scope', async () => {
+    const { client, listAllEntities } = stub();
+    await withScope(client, null).listAllEntities('topic', { filters: { page_size: '200' } });
+    expect(filtersOf(listAllEntities)).not.toHaveProperty('scope');
+    expect(filtersOf(listAllEntities)).toEqual({ page_size: '200' });
+  });
+
+  it('calls an unscoped read exactly the way an unwrapped client is called', async () => {
+    // A client that only ever took `(type)` must see what it always saw, so
+    // wrapping an existing app in `withScope` is not a behaviour change.
+    const { client, listAllEntities } = stub();
+    await withScope(client, null).listAllEntities('topic');
+    expect(listAllEntities).toHaveBeenCalledWith('topic');
+    expect(listAllEntities.mock.calls[0]).toHaveLength(1);
+  });
+});
+
+describe('withScope — a request with no type never carries a scope', () => {
+  it('hands listTypes on with NO arguments', async () => {
+    // `?scope=` REQUIRES `?type=` — a 400 without it (bd startsim-mj609),
+    // because the parameter resolves through ONE type's declaration and the
+    // schema read spans every type.
+    const { client, listTypes } = stub();
+    await withScope(client, '/clients/acme').listTypes();
+    expect(listTypes).toHaveBeenCalledWith();
+    expect(listTypes.mock.calls[0]).toHaveLength(0);
+  });
+
+  it.each([[''], ['   ']])('adds no scope to a list read whose type is %p', async (type) => {
+    const { client, listAllEntities } = stub();
+    await withScope(client, '/clients/acme').listAllEntities(type);
+    expect(filtersOf(listAllEntities)).not.toHaveProperty('scope');
+  });
+});
+
+describe('withScope — the shared corpus opts out', () => {
+  it('leaves a `scoped: false` read unbounded', async () => {
+    // One source registry, one news_item corpus (epic startsim-ux39t decision
+    // 2). Narrowing a lookup of a shared type either 400s or silently loses
+    // every row outside the bound.
+    const { client, listAllEntities } = stub();
+    await withScope(client, '/clients/acme').listAllEntities('source', { scoped: false });
+    expect(filtersOf(listAllEntities)).not.toHaveProperty('scope');
+  });
+
+  it('scopes by DEFAULT, so forgetting narrows rather than widens', async () => {
+    const { client, listAllEntities } = stub();
+    await withScope(client, '/clients/acme').listAllEntities('source', {});
+    expect(filtersOf(listAllEntities)).toEqual({ scope: '/clients/acme' });
+  });
+});
+
+// --------------------------------------------------------------------------
+// writes
+// --------------------------------------------------------------------------
+
+describe('withScope — a write cannot cross scopes', () => {
+  it('hands the payload on BYTE-FOR-BYTE', async () => {
+    const { client, updateEntity } = stub();
+    const input = { data: { status: 'ready', path: '/clients/globex' } };
+    await withScope(client, '/clients/acme').updateEntity(7, input);
+    expect(updateEntity).toHaveBeenCalledWith(7, input);
+  });
+
+  it('never rewrites a row’s own scope to the active one', async () => {
+    // Patching a row while /clients/acme is selected must NOT move it out of
+    // /clients/globex. Changing a row's scope is an explicit act.
+    const { client, updateEntity } = stub();
+    await withScope(client, '/clients/acme').updateEntity(7, {
+      data: { path: '/clients/globex' },
+    });
+    const [, input] = updateEntity.mock.calls[0] as [unknown, { data: Record<string, unknown> }];
+    expect(input.data.path).toBe('/clients/globex');
+  });
+
+  it('never STAMPS a scope onto a write that carried none', async () => {
+    // The bead's "writes stamp it" belongs to CREATE, on the upsert path. There
+    // is no create on this interface, and stamping an UPDATE is exactly the
+    // cross-scope move the same bead forbids.
+    const { client, updateEntity } = stub();
+    await withScope(client, '/clients/acme').updateEntity(7, { data: { status: 'ready' } });
+    const [, input] = updateEntity.mock.calls[0] as [unknown, { data: Record<string, unknown> }];
+    expect(input.data).toEqual({ status: 'ready' });
+    expect(input).not.toHaveProperty('scope');
+  });
+});
+
+// --------------------------------------------------------------------------
+// the cache key
+// --------------------------------------------------------------------------
+
+describe('scopeKey — a cached read is only valid for its own scope', () => {
+  it('is the path for a bound client', () => {
+    expect(scopeKey(withScope(stub().client, '/clients/acme'))).toBe('/clients/acme');
+  });
+
+  it('is "all" for an unbounded one', () => {
+    expect(scopeKey(withScope(stub().client, null))).toBe('all');
+  });
+
+  it('is "all" for a plain, never-wrapped client, so an existing cache does not split', () => {
+    expect(scopeKey(stub().client)).toBe('all');
+    expect(scopeKey(undefined)).toBe('all');
+  });
+
+  it('differs between two scopes — the whole point of putting it in a key', () => {
+    const { client } = stub();
+    expect(scopeKey(withScope(client, '/a'))).not.toBe(scopeKey(withScope(client, '/b')));
+  });
+});

package/src/components/collection/__tests__/scoped-workspace.test.tsx

@@ -0,0 +1,179 @@
+/**
+ * The seam AS THE REVIEW SURFACE SEES IT (bd startsim-nq39j).
+ *
+ * `scoped-client.test.ts` pins the decorator in isolation. This pins the thing
+ * the decorator exists for: a workspace handed a scoped client asks the server
+ * for that scope, SHOWS that scope, and stops showing it the moment the scope
+ * changes.
+ *
+ * THE SECOND TEST HERE IS THE ONE THAT MATTERS, and it is a defect this bead
+ * introduced and had to fix. react-query keys the two list reads
+ * `['entities','topic','all']` — a key with no scope in it. Wrap the client and
+ * the REQUEST carries the new scope while the CACHE serves the old scope's rows:
+ * the "every list request carries it" acceptance criterion goes green while the
+ * board shows another client's work. A scope in the key is the fix and this is
+ * what stops it being tidied away.
+ */
+import * as React from 'react';
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+import { TopicReviewWorkspace } from '../TopicReviewWorkspace';
+import { withScope } from '../scoped-client';
+import type {
+  CollectionClient,
+  EntityRecord,
+  EntityTypeDef,
+  ListEntitiesOptions,
+  Paginated,
+} from '../types';
+
+const TOPIC_TYPE: EntityTypeDef = { id: 1, key: 'topic', label: 'Topic', attributes: [] };
+
+function page<T>(results: T[]): Paginated<T> {
+  return { count: results.length, next: null, previous: null, results };
+}
+
+function topic(id: number, title: string, path: string): EntityRecord {
+  return {
+    id,
+    entityType: 'topic',
+    externalId: null,
+    name: title,
+    data: { title, status: 'suggested', path },
+    createdAt: '2026-08-27T00:00:00Z',
+  };
+}
+
+/** Rows per scope, so "which scope did the board actually render" is answerable. */
+const BY_SCOPE: Record<string, EntityRecord[]> = {
+  '/clients/acme': [topic(1, 'Acme desalination', '/clients/acme')],
+  '/clients/globex': [topic(2, 'Globex logistics', '/clients/globex')],
+};
+
+function stub(overrides: Partial<CollectionClient> = {}) {
+  const listTypes = jest.fn(async () => page([TOPIC_TYPE]));
+  const listAllEntities = jest.fn(async (type: string, options?: ListEntitiesOptions) => {
+    if (type !== 'topic') return [];
+    const scope = options?.filters?.scope;
+    return scope ? (BY_SCOPE[scope] ?? []) : Object.values(BY_SCOPE).flat();
+  });
+  const updateEntity = jest.fn(async () => topic(1, 'Acme desalination', '/clients/acme'));
+  const client: CollectionClient = { listTypes, listAllEntities, updateEntity, ...overrides };
+  return { client, listTypes, listAllEntities, updateEntity };
+}
+
+function Harness({ client }: { client: CollectionClient }) {
+  // ONE QueryClient across re-renders — otherwise a fresh cache per render would
+  // hide exactly the staleness the scope-change test is looking for.
+  const [qc] = React.useState(
+    () => new QueryClient({ defaultOptions: { queries: { retry: false } } }),
+  );
+  return (
+    <QueryClientProvider client={qc}>
+      <TopicReviewWorkspace client={client} />
+    </QueryClientProvider>
+  );
+}
+
+/** Every `topic` list read the client saw, as its scope filter (or `none`). */
+function topicScopes(mock: jest.Mock): string[] {
+  return mock.mock.calls
+    .filter((call) => call[0] === 'topic')
+    .map((call) => (call[1] as ListEntitiesOptions | undefined)?.filters?.scope ?? 'none');
+}
+
+describe('a scoped client scopes the whole review surface', () => {
+  it('asks the server for the active scope, and renders what came back', async () => {
+    const { client, listAllEntities } = stub();
+    render(<Harness client={withScope(client, '/clients/acme')} />);
+
+    expect(await screen.findByText('Acme desalination')).toBeTruthy();
+    expect(topicScopes(listAllEntities)).toEqual(['/clients/acme']);
+    // NO CLIENT-SIDE FILTERING: the board shows exactly the rows the request
+    // returned, so the other scope's row was never fetched to be hidden.
+    expect(screen.queryByText('Globex logistics')).toBeNull();
+  });
+
+  it('REFETCHES when the scope changes, instead of serving the previous scope’s rows', async () => {
+    const { client, listAllEntities } = stub();
+    const { rerender } = render(<Harness client={withScope(client, '/clients/acme')} />);
+    expect(await screen.findByText('Acme desalination')).toBeTruthy();
+
+    rerender(<Harness client={withScope(client, '/clients/globex')} />);
+
+    expect(await screen.findByText('Globex logistics')).toBeTruthy();
+    await waitFor(() => expect(screen.queryByText('Acme desalination')).toBeNull());
+    expect(topicScopes(listAllEntities)).toEqual(['/clients/acme', '/clients/globex']);
+  });
+
+  it('reads the SHARED source registry unscoped, and reads it once for both scopes', async () => {
+    // One source registry across scopes (epic startsim-ux39t decision 2). It is
+    // also keyed without the scope, so switching client does not refetch it.
+    const { client, listAllEntities } = stub();
+    const { rerender } = render(<Harness client={withScope(client, '/clients/acme')} />);
+    expect(await screen.findByText('Acme desalination')).toBeTruthy();
+    rerender(<Harness client={withScope(client, '/clients/globex')} />);
+    expect(await screen.findByText('Globex logistics')).toBeTruthy();
+
+    const sourceCalls = listAllEntities.mock.calls.filter((call) => call[0] === 'source');
+    expect(sourceCalls).toHaveLength(1);
+    expect((sourceCalls[0][1] as ListEntitiesOptions).filters).not.toHaveProperty('scope');
+  });
+
+  it('never puts a scope on the schema read', async () => {
+    const { client, listTypes } = stub();
+    render(<Harness client={withScope(client, '/clients/acme')} />);
+    expect(await screen.findByText('Acme desalination')).toBeTruthy();
+    // `?scope=` without `?type=` is a 400 (bd startsim-mj609).
+    expect(listTypes).toHaveBeenCalledWith();
+  });
+});
+
+describe('an update preserves the row’s scope', () => {
+  it('PATCHes the row’s own path back, not the active one', async () => {
+    // The row lives in /clients/globex; the board is bounded to /clients/acme
+    // (a staff view that reached it, a stale cache, a hand-edited URL). Rating
+    // it must not MOVE it. PATCH replaces the whole blob, so the path has to be
+    // in the payload — with the row's value, never the client's.
+    const { client, updateEntity } = stub();
+    const scoped = withScope(client, '/clients/acme');
+    const stray = topic(9, 'Stray topic', '/clients/globex');
+    jest
+      .spyOn(client, 'listAllEntities')
+      .mockImplementation(async (type: string) => (type === 'topic' ? [stray] : []));
+
+    render(<Harness client={scoped} />);
+    expect(await screen.findByText('Stray topic')).toBeTruthy();
+
+    await userEvent.click(screen.getByRole('button', { name: /Good/ }));
+
+    await waitFor(() => expect(updateEntity).toHaveBeenCalled());
+    const [id, input] = updateEntity.mock.calls[0] as [
+      number,
+      { data: Record<string, unknown> },
+    ];
+    expect(id).toBe(9);
+    expect(input.data.path).toBe('/clients/globex');
+    expect(input.data.teamVerdict).toBe('good');
+  });
+});
+
+describe('a refused scope is reported, not rendered as an empty board', () => {
+  it('shows the server’s refusal instead of “Nothing to review right now.”', async () => {
+    // `?scope=` on a type declaring no scope path is a 400 (bd startsim-mj609).
+    // Swallowed, it renders as "this client has no topics" — a confident wrong
+    // answer of the same family as silently widening.
+    const { client } = stub();
+    jest.spyOn(client, 'listAllEntities').mockImplementation(async (type: string) => {
+      if (type === 'topic') throw new Error("type 'topic' declares no scope path");
+      return [];
+    });
+
+    render(<Harness client={withScope(client, '/clients/acme')} />);
+
+    expect(await screen.findByText(/declares no scope path/)).toBeTruthy();
+    expect(screen.queryByText('Nothing to review right now.')).toBeNull();
+  });
+});

package/src/components/collection/index.ts

@@ -28,7 +28,28 @@ export {
   type VerdictOption,
   type VerdictTone,
 } from './review';
-export type { CollectionClient, EntityRecord, EntityTypeDef, AttributeDef, Paginated, DataType } from './types';
+export type {
+  CollectionClient,
+  EntityRecord,
+  EntityTypeDef,
+  AttributeDef,
+  Paginated,
+  DataType,
+  EntityFilters,
+  ListEntitiesOptions,
+} from './types';
+// The scope seam (bd startsim-nq39j): wrap the injected client once and every
+// review surface in this package is scoped, because every one of them is
+// client-injected. `useScopedCollectionClient` in '@startsimpli/ui/scope' binds
+// it to the URL for a Next host.
+export {
+  withScope,
+  scopeFilters,
+  resolveScope,
+  scopeKey,
+  SCOPE_FILTER,
+  type ScopedCollectionClient,
+} from './scoped-client';
 export { readData, toCamelKey } from './data';
 export {
   parseSources,

package/src/components/collection/scoped-client.ts

@@ -0,0 +1,155 @@
+/**
+ * THE ONE SEAM (bd startsim-nq39j, epic startsim-ux39t).
+ *
+ * `withScope(client, scope)` returns a `CollectionClient` whose LIST reads carry
+ * the active scope and whose WRITES cannot cross one. Because every review
+ * surface in this package is client-injected — the app wrapper is ~10 LOC and
+ * hands in its authed tenant API — wrapping that one object scopes the whole
+ * surface at once. Nothing else in `collection/` knows what a scope is, and
+ * nothing else should learn: a second place that narrows is a second place that
+ * can forget to.
+ *
+ * THE WIRE SPELLING OF "EVERYTHING" IS SILENCE, and this is the decision the
+ * bead asked to be taken deliberately. The BROWSER URL spells it `?scope=all`
+ * (`SCOPE_ALL`), because there a missing parameter has to stay distinguishable
+ * from an asserted one — see `../scope/useScopeParam`. The WIRE cannot borrow
+ * that spelling and must not borrow the empty one either:
+ *
+ *   • `?scope=all` is a 400 — every stored path begins with the separator, so a
+ *     value that does not is refused as a value that could only match nothing.
+ *   • `?scope=` (blank) is ALSO a 400, and it is the dangerous one:
+ *     `normalize_container("")` returns `/`, so the obvious implementation reads
+ *     an empty parameter as EVERY scoped row (bd startsim-mj609).
+ *
+ * So "no scope" OMITS THE KEY. That is not merely the safe encoding, it is the
+ * only correct one: an omitted parameter returns unscoped rows too, which today
+ * is every row, while `?scope=/` would return only rows that carry a path.
+ *
+ * A PATH IS PASSED THROUGH VERBATIM, INCLUDING A BAD ONE. A value that is not
+ * `all` and not blank goes on the wire as the caller wrote it, even without a
+ * leading separator, because the server refuses that and a refusal is a better
+ * answer than a client that quietly drops a narrowing it did not understand.
+ *
+ * REFERENTIALLY STABLE OR NOT AT ALL. The returned client is the query key's
+ * input and react-query's identity for the injected API; building a new one on
+ * every render is the same mistake as building a new `ScopeClient` on every
+ * render (see `../scope/types.ts`). Memoize it on the scope, or use
+ * `useScopedCollectionClient` from `@startsimpli/ui/scope`, which does.
+ */
+import type { CollectionClient, EntityFilters, ListEntitiesOptions } from './types';
+
+/**
+ * The query parameter the tenant recognises. It is a plain lowercase word, so
+ * unlike `attr.x__gte` it survives a camel/snake rewrite unharmed — but it still
+ * travels the {@link EntityFilters} path, because one narrowing mechanism is the
+ * whole point of `EntityFilters` existing.
+ */
+export const SCOPE_FILTER = 'scope';
+
+/**
+ * The URL's reserved word for "no bound at all". Recognised here as well as in
+ * `useScopeParam` because a caller can reach a raw `?scope=` value without going
+ * through the hook — a server component reading `searchParams`, a test, an app
+ * that keeps the scope somewhere else — and `all` must mean the same thing to
+ * every one of them.
+ */
+const SCOPE_ALL_VALUE = 'all';
+
+/**
+ * A `CollectionClient` that knows what it is bounded to.
+ *
+ * `scope` is exposed for ONE reason and it is not decoration: a cached read is
+ * only valid for the scope it was made under, so a consumer's react-query key
+ * has to name it. {@link scopeKey} is that read.
+ */
+export interface ScopedCollectionClient extends CollectionClient {
+  /** The active path, or `null` for no bound. */
+  readonly scope: string | null;
+}
+
+/**
+ * Resolve any spelling of a scope to the one the wire uses: a path, or `null`.
+ *
+ * `null`, `undefined`, empty, whitespace and the reserved `all` all resolve to
+ * `null` — "no bound" — and `null` is spelled on the wire by sending nothing.
+ */
+export function resolveScope(scope: string | null | undefined): string | null {
+  if (typeof scope !== 'string') return null;
+  const trimmed = scope.trim();
+  if (!trimmed || trimmed === SCOPE_ALL_VALUE) return null;
+  return trimmed;
+}
+
+/**
+ * The filters a scope contributes to a list read — `{}` when there is no bound.
+ *
+ * IT RETURNS AN ABSENT KEY, NOT AN EMPTY ONE. `{ scope: '' }` is a 400 that
+ * would be read as "the root" by an unlucky implementation; the only encoding of
+ * "everything" this package will ever put on the wire is no key at all.
+ */
+export function scopeFilters(scope: string | null | undefined): EntityFilters {
+  const resolved = resolveScope(scope);
+  return resolved === null ? {} : { [SCOPE_FILTER]: resolved };
+}
+
+/**
+ * The cache-key fragment for a client's bound. `'all'` for no bound, so an
+ * UNWRAPPED client (a plain `CollectionClient`, which has no `scope` at all)
+ * keys identically to an explicitly unbounded one and an existing consumer's
+ * cache does not split in two for no reason.
+ */
+export function scopeKey(client: Pick<ScopedCollectionClient, 'scope'> | CollectionClient | null | undefined): string {
+  const scope = (client as ScopedCollectionClient | null | undefined)?.scope;
+  return resolveScope(scope) ?? SCOPE_ALL_VALUE;
+}
+
+/**
+ * Bind a `CollectionClient` to a scope.
+ *
+ * LIST reads gain `?scope=<path>`; WRITES are handed on BYTE-FOR-BYTE. A write
+ * that carried the active scope would be able to MOVE a row: patch a row while
+ * `/clients/acme` is selected and it would silently leave `/clients/globex`.
+ * Changing a row's scope is an explicit act with its own affordance, never a
+ * side effect of editing it somewhere. (The bead's phrase "writes stamp it"
+ * belongs to CREATE, on the scope-aware upsert path — there is no create on this
+ * interface, so there is nothing here to stamp.)
+ */
+export function withScope(
+  client: CollectionClient,
+  scope: string | null | undefined,
+): ScopedCollectionClient {
+  const resolved = resolveScope(scope);
+
+  return {
+    scope: resolved,
+
+    // Passed on with NO arguments at all. The schema read carries no `?type=`,
+    // and `?scope=` without `?type=` is a 400 (bd startsim-mj609) — so this is
+    // not an omission to tidy up later, it is the refusal being respected.
+    listTypes: () => client.listTypes(),
+
+    listAllEntities: (type: string, options?: ListEntitiesOptions) => {
+      // A type-less list read cannot carry a scope for the same reason
+      // `listTypes` cannot: the parameter resolves through ONE type's
+      // declaration. A blank type is already a bad request; adding a scope to it
+      // would turn a legible 400 into a confusing one.
+      const scopable = typeof type === 'string' && type.trim() !== '';
+      const applies = scopable && options?.scoped !== false;
+      const extra = applies ? scopeFilters(resolved) : {};
+      // Merged UNDER the caller's own filters, not over them: a consumer that
+      // deliberately sent its own `scope` (a fixture, a one-off drill-down)
+      // means it, and the decorator does not overrule it.
+      const filters: EntityFilters = { ...extra, ...(options?.filters ?? {}) };
+      const next: ListEntitiesOptions = { ...options, filters };
+      // No filters and no options in means no options through — an
+      // implementation that only ever took `(type)` sees exactly what it did
+      // before, so wrapping an old client is not a behaviour change.
+      if (Object.keys(filters).length === 0 && options === undefined) {
+        return client.listAllEntities(type);
+      }
+      return client.listAllEntities(type, next);
+    },
+
+    updateEntity: (id, input) => client.updateEntity(id, input),
+  };
+}

package/src/components/collection/types.ts

@@ -42,13 +42,64 @@ export interface Paginated<T> {
   results: T[];
 }
 
+/**
+ * Server-side narrowing, spelled EXACTLY as the wire spells it — `type`,
+ * `scope`, `attr.published_at__gte`, `attr.topic_ref__in`. The value is a string
+ * because it is a query-string value and nothing else.
+ *
+ * THE KEY GOES IN THE URL, NEVER THROUGH A CLIENT'S `params` BAG. The shared
+ * `@startsimpli/api` client rewrites request keys between camelCase and
+ * snake_case, and `attr.published_at__gte` is neither — it comes out mangled,
+ * the server does not recognise it, and (on an image with
+ * TENANT_ALLOW_UNKNOWN_FILTERS on) reads as "no filter" rather than as an
+ * error. That is a widening, and a widening under an active filter chip is the
+ * failure that cost nine production tandem rows on 2026-08-27. The fork's
+ * `listEntities` already builds the query string itself for this reason and is
+ * guarded by its own `src/lib/__tests__/entity-filters.test.ts`; this type is
+ * the same contract, named, so a `CollectionClient` implementation inherits the
+ * requirement instead of rediscovering it.
+ */
+export type EntityFilters = Record<string, string>;
+
+/**
+ * How a list read is narrowed. Deliberately the SAME SHAPE the fork's
+ * `listAllEntities(type, { filters })` already accepts (bd startsim-nq39j), so
+ * the existing, tested filter path is extended rather than joined by a second
+ * one — an app that already implements it satisfies this interface unchanged.
+ */
+export interface ListEntitiesOptions {
+  /** Server-side narrowing — see {@link EntityFilters}. */
+  filters?: EntityFilters;
+  /**
+   * Opt this read OUT of the active scope. Default: scoped.
+   *
+   * THE SHARED CORPUS IS WHY THIS EXISTS (epic startsim-ux39t, decision 2: "one
+   * news_item corpus, one source registry"). A source registry or an article
+   * corpus is subscribed to by several scopes rather than ingested per scope, so
+   * narrowing a LOOKUP read of one to the active scope answers the wrong
+   * question: either the type declares no scope path and the server 400s
+   * (`?scope=` on an unscoped type is a refusal, bd startsim-mj609), or it does
+   * and the lookup silently loses every row outside the bound. Deliverable reads
+   * — the topics and drafts a client is owed — stay scoped.
+   *
+   * The polarity is deliberate: forgetting this flag NARROWS loudly, it never
+   * widens silently. Do not delete it as dead config.
+   */
+  scoped?: boolean;
+}
+
 /**
  * The tenant-API surface a review workspace needs. The app implements this over
  * its authed same-origin client (keys are camel/snake-normalized by that client;
  * PATCH replaces the whole data blob, so callers send the full merged data).
+ *
+ * `listTypes` TAKES NO NARROWING AND MUST NOT. It is a schema read with no
+ * `?type=`, and `?scope=` REQUIRES `?type=` server-side — a 400, by design,
+ * because the parameter resolves through one type's declaration and an
+ * unfiltered list spans many (bd startsim-mj609).
  */
 export interface CollectionClient {
   listTypes(): Promise<Paginated<EntityTypeDef>>;
-  listAllEntities(type: string): Promise<EntityRecord[]>;
+  listAllEntities(type: string, options?: ListEntitiesOptions): Promise<EntityRecord[]>;
   updateEntity(id: number | string, input: { name?: string; data?: Record<string, unknown> }): Promise<EntityRecord>;
 }

package/src/components/index.ts

@@ -199,6 +199,7 @@ export {
   ScopeSwitcher,
   ScopeSwitcherControlled,
   useScopeParam,
+  useScopedCollectionClient,
   createScopeClient,
   SCOPE_PARAM,
   SCOPE_ALL,

package/src/components/scope/__tests__/use-scoped-client.test.tsx

@@ -0,0 +1,80 @@
+/**
+ * `useScopedCollectionClient` (bd startsim-nq39j) — the URL's scope bound onto
+ * the app's injected tenant client, which is the whole of a fork's adoption.
+ *
+ * Two properties, and the second is the one that would otherwise be discovered
+ * in production: the hook reads the SAME `?scope=` the switcher writes (so a
+ * shared link scopes the data, not just the picker's label), and the client it
+ * returns is REFERENTIALLY STABLE — it is a react-query input, and a fresh
+ * object per render refetches every list on every keystroke elsewhere on the
+ * page.
+ */
+import * as React from 'react'
+import { render, screen } from '@testing-library/react'
+import { useSearchParams } from 'next/navigation'
+
+import { useScopedCollectionClient } from '../useScopedClient'
+import type { CollectionClient, EntityRecord, EntityTypeDef, Paginated } from '../../collection/types'
+
+const mockedSearchParams = useSearchParams as unknown as jest.Mock
+
+function page<T>(results: T[]): Paginated<T> {
+  return { count: results.length, next: null, previous: null, results }
+}
+
+const client: CollectionClient = {
+  listTypes: async () => page<EntityTypeDef>([]),
+  listAllEntities: async () => [] as EntityRecord[],
+  updateEntity: async () => ({}) as EntityRecord,
+}
+
+/** Renders the bound scope and hands every client instance it saw to the test. */
+function Probe({ seen }: { seen: unknown[] }) {
+  const scoped = useScopedCollectionClient(client, { remember: false })
+  seen.push(scoped)
+  return <span data-testid="scope">{String(scoped.scope)}</span>
+}
+
+beforeEach(() => {
+  mockedSearchParams.mockReturnValue(new URLSearchParams(''))
+})
+
+describe('useScopedCollectionClient', () => {
+  it('binds the client to the scope the URL is asserting', () => {
+    mockedSearchParams.mockReturnValue(new URLSearchParams('scope=/clients/acme'))
+    render(<Probe seen={[]} />)
+    expect(screen.getByTestId('scope').textContent).toBe('/clients/acme')
+  })
+
+  it('reads the URL’s reserved "all" as no bound', () => {
+    // `?scope=all` is the browser spelling of "everything"; on the wire that is
+    // the ABSENCE of the parameter, which is what `scope: null` produces.
+    mockedSearchParams.mockReturnValue(new URLSearchParams('scope=all'))
+    render(<Probe seen={[]} />)
+    expect(screen.getByTestId('scope').textContent).toBe('null')
+  })
+
+  it('is unbounded on a bare URL', () => {
+    render(<Probe seen={[]} />)
+    expect(screen.getByTestId('scope').textContent).toBe('null')
+  })
+
+  it('returns the SAME client across re-renders, so react-query does not thrash', () => {
+    mockedSearchParams.mockReturnValue(new URLSearchParams('scope=/clients/acme'))
+    const seen: unknown[] = []
+    const { rerender } = render(<Probe seen={seen} />)
+    rerender(<Probe seen={seen} />)
+    expect(seen.length).toBeGreaterThan(1)
+    expect(new Set(seen).size).toBe(1)
+  })
+
+  it('returns a NEW client when the scope changes, so the cache key moves with it', () => {
+    mockedSearchParams.mockReturnValue(new URLSearchParams('scope=/clients/acme'))
+    const seen: unknown[] = []
+    const { rerender } = render(<Probe seen={seen} />)
+    mockedSearchParams.mockReturnValue(new URLSearchParams('scope=/clients/globex'))
+    rerender(<Probe seen={seen} />)
+    expect(screen.getByTestId('scope').textContent).toBe('/clients/globex')
+    expect(new Set(seen).size).toBe(2)
+  })
+})

package/src/components/scope/index.ts

@@ -26,6 +26,12 @@ export {
   type ScopeHttp,
   type CreateScopeClientOptions,
 } from './client'
+/**
+ * The URL's scope bound onto the app's `CollectionClient` (bd startsim-nq39j) —
+ * the whole of a fork's adoption, because every review surface in
+ * '@startsimpli/ui/collection' is client-injected.
+ */
+export { useScopedCollectionClient } from './useScopedClient'
 export type {
   ScopeClient,
   ScopeNode,

package/src/components/scope/useScopedClient.ts

@@ -0,0 +1,44 @@
+'use client'
+
+/**
+ * The URL's scope, bound onto the app's injected tenant client — the two halves
+ * of bd startsim-nq39j joined in the one place an app has to touch.
+ *
+ * A fork wrapper is then the whole adoption:
+ *
+ *   const client = useScopedCollectionClient(collectionClient)
+ *   return <TopicReviewWorkspace client={client} />
+ *
+ * WHY THIS AND NOT `withScope(collectionClient, useScopeParam().scope)` INLINE.
+ * The returned client is a react-query input: it is the query function's closure
+ * and, through `scopeKey`, part of the query key. Built fresh on every render it
+ * is a new object every render, which is the same defect `ScopeClient` documents
+ * for the switcher's own reset key. The memo here is the point of the hook.
+ *
+ * THE HOOK LIVES IN `scope/`, NOT IN `collection/`, ON PURPOSE. Reading the URL
+ * means `next/navigation`; keeping that import out of `collection/` leaves the
+ * review workspaces and `withScope` framework-agnostic, so a host that keeps its
+ * scope somewhere else (a native shell, a test, a server component passing a
+ * value down) calls `withScope` directly and loses nothing.
+ */
+import * as React from 'react'
+
+import { withScope, type ScopedCollectionClient } from '../collection/scoped-client'
+import type { CollectionClient } from '../collection/types'
+import { useScopeParam, type UseScopeParamOptions } from './useScopeParam'
+
+/**
+ * Bind the URL's active scope onto a `CollectionClient`.
+ *
+ * The result is stable while the scope and the underlying client are — so pass a
+ * module-level or memoized `client`, exactly as an unwrapped one would need to
+ * be. Options are forwarded to {@link useScopeParam} verbatim.
+ */
+export function useScopedCollectionClient(
+  client: CollectionClient,
+  options: UseScopeParamOptions = {},
+): ScopedCollectionClient {
+  const { param, remember, rememberKey, history } = options
+  const { scope } = useScopeParam({ param, remember, rememberKey, history })
+  return React.useMemo(() => withScope(client, scope), [client, scope])
+}