@startsimpli/ui 0.4.110 → 0.4.112

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.110",
+  "version": "0.4.112",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -21,6 +21,8 @@
     "./blog/resolve": "./src/components/blog/resolveArticle.ts",
     "./activity": "./src/components/activity/index.ts",
     "./collection": "./src/components/collection/index.ts",
+    "./scope": "./src/components/scope/index.ts",
+    "./facet-tree": "./src/components/facet-tree/index.ts",
     "./document-editor": "./src/components/document-editor/index.ts",
     "./email-editor": "./src/components/email-editor/index.ts",
     "./workflows": "./src/components/workflows/index.ts",

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,