@semiont/react-ui 0.5.9 → 0.5.10

package/src/components/modals/__tests__/ConfigureGatherStep.test.tsx

@@ -0,0 +1,82 @@
+/**
+ * GENERATE-FROM-BUTTON P2/P4 — the gather-options form.
+ *
+ * Pure presentational form (no providers): it owns the gather config in local
+ * state and emits a `ResourceGatherConfig` on submit. The `children` slot hosts
+ * the Phase-4 exclusion multi-select.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { ConfigureGatherStep } from '../ConfigureGatherStep';
+
+const t = {
+  intro: 'Choose what to include.',
+  includeContent: 'Include content',
+  includeSummary: 'Include summary',
+  depth: 'Depth',
+  maxResources: 'Max resources',
+  cancel: 'Cancel',
+  gather: 'Gather',
+};
+
+describe('ConfigureGatherStep', () => {
+  it('renders the intro and the default option values', () => {
+    render(<ConfigureGatherStep onGather={vi.fn()} onCancel={vi.fn()} translations={t} />);
+    expect(screen.getByText('Choose what to include.')).toBeInTheDocument();
+    expect(screen.getByLabelText('Include content')).toBeChecked();
+    expect(screen.getByLabelText('Include summary')).toBeChecked();
+    expect(screen.getByLabelText('Depth')).toHaveValue(2);
+    expect(screen.getByLabelText('Max resources')).toHaveValue(10);
+  });
+
+  it('emits the default config on submit', () => {
+    const onGather = vi.fn();
+    render(<ConfigureGatherStep onGather={onGather} onCancel={vi.fn()} translations={t} />);
+    fireEvent.click(screen.getByRole('button', { name: /Gather/ }));
+    expect(onGather).toHaveBeenCalledWith({ includeContent: true, includeSummary: true, depth: 2, maxResources: 10 });
+  });
+
+  it('reflects edits in the emitted config', () => {
+    const onGather = vi.fn();
+    render(<ConfigureGatherStep onGather={onGather} onCancel={vi.fn()} translations={t} />);
+    fireEvent.click(screen.getByLabelText('Include content')); // uncheck
+    fireEvent.click(screen.getByLabelText('Include summary')); // uncheck
+    fireEvent.change(screen.getByLabelText('Depth'), { target: { value: '4' } });
+    fireEvent.change(screen.getByLabelText('Max resources'), { target: { value: '25' } });
+    fireEvent.click(screen.getByRole('button', { name: /Gather/ }));
+    expect(onGather).toHaveBeenCalledWith({ includeContent: false, includeSummary: false, depth: 4, maxResources: 25 });
+  });
+
+  it('honors the defaults prop', () => {
+    const onGather = vi.fn();
+    render(
+      <ConfigureGatherStep
+        defaults={{ includeSummary: false, depth: 1, maxResources: 5 }}
+        onGather={onGather}
+        onCancel={vi.fn()}
+        translations={t}
+      />,
+    );
+    expect(screen.getByLabelText('Include summary')).not.toBeChecked();
+    expect(screen.getByLabelText('Depth')).toHaveValue(1);
+    fireEvent.click(screen.getByRole('button', { name: /Gather/ }));
+    expect(onGather).toHaveBeenCalledWith({ includeContent: true, includeSummary: false, depth: 1, maxResources: 5 });
+  });
+
+  it('calls onCancel from the cancel button', () => {
+    const onCancel = vi.fn();
+    render(<ConfigureGatherStep onGather={vi.fn()} onCancel={onCancel} translations={t} />);
+    fireEvent.click(screen.getByRole('button', { name: /Cancel/ }));
+    expect(onCancel).toHaveBeenCalledTimes(1);
+  });
+
+  it('renders the children slot (exclusion picker)', () => {
+    render(
+      <ConfigureGatherStep onGather={vi.fn()} onCancel={vi.fn()} translations={t}>
+        <div>EXCLUDE-SLOT</div>
+      </ConfigureGatherStep>,
+    );
+    expect(screen.getByText('EXCLUDE-SLOT')).toBeInTheDocument();
+  });
+});

package/src/components/modals/__tests__/GatherContextStep.resource.test.tsx

@@ -0,0 +1,107 @@
+/**
+ * GENERATE-FROM-BUTTON P1 — the GatheredContext display renders a resource focus.
+ *
+ * ContextSummary's graph views are focus-agnostic; GatherContextStep gains a
+ * resource-focus strip and hides the annotation-only controls (hint + the
+ * Bind/Generate/Compose footer) for a resource focus.
+ */
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { render } from '@testing-library/react';
+import type { GatheredContext } from '@semiont/core';
+import { GatherContextStep } from '../GatherContextStep';
+import { ContextSummary } from '../ContextSummary';
+
+const t = {
+  title: 'Gather',
+  loadingContext: 'Loading…',
+  failedContext: 'Failed',
+  search: 'Search',
+  generate: 'Generate',
+  compose: 'Compose',
+  resolutionStrategyLabel: 'Strategy',
+  sourceContextLabel: 'Source',
+  connectionsLabel: 'Connections',
+  citedByLabel: 'Cited by',
+  userHintLabel: 'Hint',
+  userHintPlaceholder: 'hint…',
+};
+
+function resourceContext(): GatheredContext {
+  return {
+    focus: {
+      kind: 'resource',
+      resource: { id: 'res-1', name: 'My Resource' },
+      summary: 'A short summary',
+      suggestedReferences: ['Suggested Topic'],
+      content: { main: 'main content' },
+    },
+    graph: {
+      nodes: [
+        { id: 'res-1', type: 'resource', label: 'My Resource' },
+        { id: 'res-2', type: 'resource', label: 'Related Resource', entityTypes: ['Topic'] },
+      ],
+      edges: [{ source: 'res-1', target: 'res-2', type: 'peer' }],
+    },
+    metadata: { entityTypes: ['Topic'] },
+  } as unknown as GatheredContext;
+}
+
+describe('GatheredContext display — resource focus', () => {
+  beforeEach(() => {
+    // jsdom doesn't implement scrollIntoView — GatherContextStep's annotation
+    // strip calls it on mount. (Same stub the panel tests use.)
+    Element.prototype.scrollIntoView = vi.fn();
+  });
+
+  it('ContextSummary renders graph views (connections) for a resource focus', () => {
+    const { container } = render(<ContextSummary context={resourceContext()} translations={t} />);
+    expect(container.textContent).toContain('Related Resource'); // peer connection from deriveViews
+  });
+
+  it('GatherContextStep shows the resource strip and hides the annotation-only footer', () => {
+    const { container } = render(
+      <GatherContextStep
+        context={resourceContext()}
+        contextLoading={false}
+        contextError={null}
+        translations={t}
+      />,
+    );
+    expect(container.textContent).toContain('My Resource');     // focal resource name
+    expect(container.textContent).toContain('A short summary'); // resource summary
+    expect(container.textContent).toContain('Suggested Topic'); // suggestedReferences chip
+    expect(container.textContent).toContain('Related Resource'); // graph view via ContextSummary
+    // annotation-only controls are gated out for a resource focus
+    expect(container.textContent).not.toContain('Strategy');
+    expect(container.querySelector('.semiont-gather__footer')).toBeNull();
+    expect(container.querySelector('.semiont-gather__hint-textarea')).toBeNull();
+  });
+
+  it('GatherContextStep still shows the footer for an annotation focus', () => {
+    const annotationContext = {
+      focus: {
+        kind: 'annotation',
+        annotation: { id: 'anno-1', motivation: 'linking' },
+        sourceResource: { id: 'res-1', name: 'Host' },
+        selected: { before: 'a ', text: 'term', after: ' b' },
+      },
+      graph: { nodes: [], edges: [] },
+      metadata: {},
+    } as unknown as GatheredContext;
+    const { container } = render(
+      <GatherContextStep
+        context={annotationContext}
+        contextLoading={false}
+        contextError={null}
+        userHint=""
+        onUserHintChange={() => {}}
+        onBind={() => {}}
+        onGenerate={() => {}}
+        onCompose={() => {}}
+        translations={t}
+      />,
+    );
+    expect(container.querySelector('.semiont-gather__footer')).not.toBeNull();
+    expect(container.textContent).toContain('Strategy');
+  });
+});

package/src/components/modals/__tests__/ResourceGenerateModal.test.tsx

@@ -0,0 +1,197 @@
+/**
+ * GENERATE-FROM-BUTTON P2/P4 — the resource-generate flow modal.
+ *
+ * Drives the step machine: configure-gather → review → configure-generation.
+ * `useResourceGather` is mocked so we control the gathered context and assert
+ * how the step wires `gather()` (incl. the Phase-4 exclusion threading) and
+ * `onGenerateSubmit`. `useSemiont` is mocked to feed the entity-type options.
+ */
+import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { BehaviorSubject, of } from 'rxjs';
+import type { GatheredContext } from '@semiont/core';
+import type { GenerationConfig } from '../ConfigureGenerationStep';
+
+const RESOURCE_CONTEXT = {
+  focus: { kind: 'resource', resource: { id: 'res-1', name: 'My Resource' }, summary: 'A short summary' },
+  graph: { nodes: [{ id: 'res-1', type: 'resource', label: 'My Resource' }], edges: [] },
+  metadata: {},
+} as unknown as GatheredContext;
+
+// Mutable hook state + spies, shared with the hoisted vi.mock factory.
+const h = vi.hoisted(() => ({
+  gather: vi.fn(),
+  reset: vi.fn(),
+  state: { context: null as unknown, loading: false, error: null as Error | null },
+}));
+
+vi.mock('../../../hooks/useResourceGather', () => ({
+  useResourceGather: () => ({
+    context: h.state.context,
+    loading: h.state.loading,
+    error: h.state.error,
+    gather: h.gather,
+    reset: h.reset,
+  }),
+}));
+
+// Stable observable instance — the modal calls `entityTypes()` inline in
+// render, so a fresh observable each call would re-subscribe every render and
+// loop. The real SDK returns a cached observable; mirror that here.
+const entityTypes$ = of<string[]>(['Person', 'Topic']);
+const mockClient = { browse: { entityTypes: () => entityTypes$ } };
+const activeSession$ = new BehaviorSubject<unknown>({ client: mockClient });
+vi.mock('../../../session/SemiontProvider', async () => {
+  const actual = await vi.importActual<typeof import('../../../session/SemiontProvider')>('../../../session/SemiontProvider');
+  return { ...actual, useSemiont: () => ({ activeSession$ }) };
+});
+
+import { ResourceGenerateModal } from '../ResourceGenerateModal';
+
+const T = {
+  gatherTitle: 'Configure Gather',
+  reviewTitle: 'Review Context',
+  configureTitle: 'Configure Generation',
+  next: 'Next',
+  back: 'Back',
+  cancel: 'Cancel',
+  gatherIntro: 'Choose what to include.',
+  includeContent: 'Include content',
+  includeSummary: 'Include summary',
+  gatherDepth: 'Depth',
+  gatherMaxResources: 'Max resources',
+  gatherButton: 'Gather',
+  excludeLabel: 'Exclude from recall',
+  loadingContext: 'Gathering…',
+  failedContext: 'Failed',
+  sourceContextLabel: 'Resource',
+  connectionsLabel: 'Connections',
+  citedByLabel: 'Cited by',
+  resourceTitle: 'New resource title',
+  resourceTitlePlaceholder: 'Title…',
+  additionalInstructions: 'Additional Instructions',
+  additionalInstructionsPlaceholder: 'Optional…',
+  language: 'Language',
+  languageHelp: 'Language help',
+  creativity: 'Creativity',
+  creativityFocused: 'Focused',
+  creativityCreative: 'Creative',
+  maxLength: 'Max Length',
+  maxLengthHelp: 'Max help',
+  generate: 'Generate',
+};
+
+let onClose: Mock<() => void>;
+let onGenerateSubmit: Mock<(resourceId: string, config: GenerationConfig) => void>;
+
+function renderModal(props: Partial<React.ComponentProps<typeof ResourceGenerateModal>> = {}) {
+  return render(
+    <ResourceGenerateModal
+      isOpen
+      onClose={onClose}
+      resourceId="res-1"
+      defaultTitle="Default Title"
+      locale="en"
+      onGenerateSubmit={onGenerateSubmit}
+      translations={T}
+      {...props}
+    />,
+  );
+}
+
+describe('ResourceGenerateModal', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    onClose = vi.fn<() => void>();
+    onGenerateSubmit = vi.fn<(resourceId: string, config: GenerationConfig) => void>();
+    h.state = { context: null, loading: false, error: null };
+    activeSession$.next({ client: mockClient });
+    // jsdom doesn't implement scrollIntoView; GatherContextStep may call it.
+    Element.prototype.scrollIntoView = vi.fn();
+  });
+
+  it('renders nothing when closed', () => {
+    renderModal({ isOpen: false });
+    expect(screen.queryByText('Configure Gather')).not.toBeInTheDocument();
+  });
+
+  it('opens on the configure-gather step with the exclusion options', () => {
+    renderModal();
+    expect(screen.getByText('Configure Gather')).toBeInTheDocument(); // step title
+    expect(screen.getByText('Choose what to include.')).toBeInTheDocument();
+    expect(screen.getByLabelText('Include content')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Person' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Topic' })).toBeInTheDocument();
+  });
+
+  it('submitting the gather step calls gather() and advances to review (exclusion omitted when none picked)', () => {
+    renderModal();
+    fireEvent.click(screen.getByRole('button', { name: /Gather/ }));
+    expect(h.gather).toHaveBeenCalledWith('res-1', { includeContent: true, includeSummary: true, depth: 2, maxResources: 10 });
+    expect(screen.getByText('Review Context')).toBeInTheDocument(); // step title flipped
+    expect(screen.getByRole('button', { name: /Next/ })).toBeDisabled(); // no context yet
+  });
+
+  it('threads picked entity types into the gather call', () => {
+    renderModal();
+    fireEvent.click(screen.getByRole('button', { name: 'Person' })); // select to exclude
+    fireEvent.click(screen.getByRole('button', { name: /Gather/ }));
+    expect(h.gather).toHaveBeenCalledWith('res-1', {
+      includeContent: true,
+      includeSummary: true,
+      depth: 2,
+      maxResources: 10,
+      excludeEntityTypes: ['Person'],
+    });
+  });
+
+  it('walks gather → review → configure-generation → emits onGenerateSubmit then closes', () => {
+    h.state.context = RESOURCE_CONTEXT; // gather already resolved
+    renderModal();
+
+    fireEvent.click(screen.getByRole('button', { name: /Gather/ })); // → review
+    const next = screen.getByRole('button', { name: /Next/ });
+    expect(next).toBeEnabled();
+    fireEvent.click(next); // → configure-generation
+
+    fireEvent.change(screen.getByLabelText('New resource title'), { target: { value: 'Generated Doc' } });
+    fireEvent.change(screen.getByLabelText('Save location'), { target: { value: 'generated/out.md' } });
+    fireEvent.click(screen.getByRole('button', { name: /Generate/ }));
+
+    expect(onGenerateSubmit).toHaveBeenCalledTimes(1);
+    expect(onGenerateSubmit).toHaveBeenCalledWith(
+      'res-1',
+      expect.objectContaining({
+        title: 'Generated Doc',
+        storagePath: 'file://generated/out.md',
+        context: RESOURCE_CONTEXT,
+      }),
+    );
+    expect(onClose).toHaveBeenCalled();
+  });
+
+  it('Back from configure-generation returns to review', () => {
+    h.state.context = RESOURCE_CONTEXT;
+    renderModal();
+    fireEvent.click(screen.getByRole('button', { name: /Gather/ })); // → review
+    fireEvent.click(screen.getByRole('button', { name: /Next/ }));   // → configure-generation
+    expect(screen.getByText('Configure Generation')).toBeInTheDocument();
+    fireEvent.click(screen.getByRole('button', { name: /Back/ }));   // → review
+    expect(screen.getByText('Review Context')).toBeInTheDocument();
+  });
+
+  it('Back from review returns to the configure-gather step', () => {
+    renderModal();
+    fireEvent.click(screen.getByRole('button', { name: /Gather/ })); // → review
+    expect(screen.getByText('Review Context')).toBeInTheDocument();
+    fireEvent.click(screen.getByRole('button', { name: /Back/ })); // → configure-gather
+    expect(screen.getByText('Configure Gather')).toBeInTheDocument();
+  });
+
+  it('the header close button calls onClose', () => {
+    renderModal();
+    fireEvent.click(screen.getByLabelText('Close'));
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+});

package/src/components/resource/panels/ReferencesPanel.tsx

@@ -455,6 +455,16 @@ export function ReferencesPanel({
             <AnnotateReferencesProgressWidget
               progress={progress}
               annotationType="reference"
+              cancelJobType="annotation"
+              translations={{
+                title: t('annotationProgressTitle'),
+                cancel: t('cancelAnnotation'),
+                inProgress: t('annotating'),
+                complete: t('complete'),
+                failed: t('failed'),
+                found: (count) => t('found', { count }),
+                current: (entityType) => t('current', { entityType }),
+              }}
             />
           )}
               </>

package/src/components/resource/panels/ResourceInfoPanel.tsx

@@ -23,6 +23,12 @@ interface Props {
   wasAttributedTo?: Agent | Agent[] | undefined;
   wasDerivedFrom?: string | string[] | undefined;
   generator?: Agent | Agent[] | undefined;
+  /**
+   * Open the resource-generate flow. UI-only — the SDK isn't involved in
+   * *opening* the display (if collaborative gather ever lands, this graduates
+   * to a verb). Omit to hide the Generate action.
+   */
+  onGenerate?: () => void;
 }
 
 /**
@@ -45,6 +51,7 @@ export function ResourceInfoPanel({
   wasAttributedTo,
   wasDerivedFrom,
   generator,
+  onGenerate,
 }: Props) {
   const t = useTranslations('ResourceInfoPanel');
   const session = useObservable(useSemiont().activeSession$);
@@ -177,6 +184,21 @@ export function ResourceInfoPanel({
         </div>
       )}
 
+      {/* Generate Action — opens the resource-generate flow (UI-only) */}
+      {onGenerate && (
+        <div className="semiont-resource-info-panel__action-section">
+          <button
+            onClick={onGenerate}
+            className="semiont-resource-button semiont-resource-button--secondary"
+          >
+            ✨ {t('generate')}
+          </button>
+          <p className="semiont-resource-info-panel__description">
+            {t('generateDescription')}
+          </p>
+        </div>
+      )}
+
       {/* Clone Action */}
       <div className="semiont-resource-info-panel__action-section">
         <button

package/src/components/resource/panels/__tests__/ResourceInfoPanel.test.tsx

@@ -20,6 +20,8 @@ vi.mock('../../../../contexts/TranslationContext', () => ({
       storageUri: 'Storage',
       clone: 'Clone',
       cloneDescription: 'Generate a shareable clone link for this resource',
+      generate: 'Generate',
+      generateDescription: "Generate a new resource from this one's context",
       archive: 'Archive',
       archiveDescription: 'Move this resource to archived status',
       unarchive: 'Unarchive',
@@ -269,6 +271,30 @@ describe('ResourceInfoPanel Component', () => {
     });
   });
 
+  describe('Generate Action', () => {
+    it('renders the Generate button when onGenerate is provided', () => {
+      renderWithEventBus(
+        <ResourceInfoPanel {...defaultProps} onGenerate={() => {}} />
+      );
+      expect(screen.getByRole('button', { name: /Generate/i })).toBeInTheDocument();
+      expect(screen.getByText("Generate a new resource from this one's context")).toBeInTheDocument();
+    });
+
+    it('hides the Generate button when onGenerate is omitted', () => {
+      renderWithEventBus(<ResourceInfoPanel {...defaultProps} />);
+      expect(screen.queryByRole('button', { name: /Generate/i })).not.toBeInTheDocument();
+    });
+
+    it('calls onGenerate when clicked', () => {
+      const onGenerate = vi.fn();
+      renderWithEventBus(
+        <ResourceInfoPanel {...defaultProps} onGenerate={onGenerate} />
+      );
+      fireEvent.click(screen.getByRole('button', { name: /Generate/i }));
+      expect(onGenerate).toHaveBeenCalledTimes(1);
+    });
+  });
+
   describe('Provenance Section', () => {
     it('should not render provenance section when no provenance data', () => {
       renderWithEventBus(<ResourceInfoPanel {...defaultProps} />);

package/src/features/admin-exchange/state/__tests__/exchange-state-unit.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, vi } from 'vitest';
 import { firstValueFrom, of, throwError } from 'rxjs';
 import type { ShellStateUnit } from '../../../../state/shell-state-unit';
 import { createExchangeStateUnit } from '../exchange-state-unit';
+import { assertStateUnitAxioms, disposeProbe } from '@semiont/core/testing';
 
 function mockBrowse(): ShellStateUnit {
   return { dispose: vi.fn() } as unknown as ShellStateUnit;
@@ -169,3 +170,16 @@ describe('createExchangeStateUnit', () => {
     stateUnit.dispose();
   });
 });
+
+describe('ExchangeStateUnit — StateUnit axioms', () => {
+  it('satisfies the StateUnit axioms (incl. A7-passed: never disposes the injected browse)', () => {
+    assertStateUnitAxioms({
+      setup: () => {
+        const browse = disposeProbe();
+        return { unit: createExchangeStateUnit(browse as unknown as ShellStateUnit, vi.fn(), vi.fn()), passedIn: [browse] };
+      },
+      surfaces: (u) => [u.selectedFile$, u.preview$, u.importPhase$, u.importMessage$, u.importResult$, u.isExporting$, u.isImporting$],
+      invocations: (u) => [() => u.cancelImport(), () => u.doImport()],
+    });
+  });
+});

package/src/features/admin-exchange/state/exchange-state-unit.ts

@@ -1,7 +1,7 @@
 import { BehaviorSubject, lastValueFrom, type Observable } from 'rxjs';
 import { tap } from 'rxjs/operators';
 import { createDisposer } from '@semiont/sdk';
-import type { StateUnit } from '@semiont/sdk';
+import type { StateUnit } from '@semiont/core';
 import type { ShellStateUnit } from '../../../state/shell-state-unit';
 import type { BackendDownload, ProgressEvent } from '@semiont/core';
 
@@ -33,7 +33,9 @@ export function createExchangeStateUnit(
   importFn: (file: File) => Observable<ProgressEvent>,
 ): ExchangeStateUnit {
   const disposer = createDisposer();
-  disposer.add(browse);
+  // `browse` (ShellStateUnit) is a *passed-in* dependency owned by the caller
+  // (`useShellStateUnit`), not this unit — do NOT add it to the disposer (it's the
+  // shared, app-scoped shell). See packages/sdk/docs/STATE-UNITS.md (composition rule).
 
   const selectedFile$ = new BehaviorSubject<File | null>(null);
   const preview$ = new BehaviorSubject<ImportPreview | null>(null);

package/src/features/admin-security/state/__tests__/admin-security-state-unit.test.ts

@@ -4,6 +4,7 @@ import { filter } from 'rxjs/operators';
 import type { SemiontClient } from '@semiont/sdk';
 import type { ShellStateUnit } from '../../../../state/shell-state-unit';
 import { createAdminSecurityStateUnit } from '../admin-security-state-unit';
+import { assertStateUnitAxioms, disposeProbe } from '@semiont/core/testing';
 
 function mockBrowse(): ShellStateUnit {
   return { dispose: vi.fn() } as unknown as ShellStateUnit;
@@ -66,3 +67,16 @@ describe('createAdminSecurityStateUnit', () => {
     stateUnit.dispose();
   });
 });
+
+describe('AdminSecurityStateUnit — StateUnit axioms', () => {
+  it('satisfies the StateUnit axioms (incl. A7-passed: never disposes the injected browse)', () => {
+    assertStateUnitAxioms({
+      setup: () => {
+        const browse = disposeProbe();
+        const client = mockClient(vi.fn().mockResolvedValue({ providers: [], allowedDomains: [] }));
+        return { unit: createAdminSecurityStateUnit(client, browse as unknown as ShellStateUnit), passedIn: [browse] };
+      },
+      surfaces: (u) => [u.providers$, u.allowedDomains$, u.isLoading$],
+    });
+  });
+});

package/src/features/admin-security/state/admin-security-state-unit.ts

@@ -1,6 +1,6 @@
 import { BehaviorSubject, type Observable } from 'rxjs';
 import { createDisposer } from '@semiont/sdk';
-import type { StateUnit } from '@semiont/sdk';
+import type { StateUnit } from '@semiont/core';
 import type { ShellStateUnit } from '../../../state/shell-state-unit';
 import type { SemiontClient } from '@semiont/sdk';
 
@@ -16,7 +16,9 @@ export function createAdminSecurityStateUnit(
   browse: ShellStateUnit,
 ): AdminSecurityStateUnit {
   const disposer = createDisposer();
-  disposer.add(browse);
+  // `browse` (ShellStateUnit) is a *passed-in* dependency owned by the caller
+  // (`useShellStateUnit`), not this unit — do NOT add it to the disposer (it's the
+  // shared, app-scoped shell). See packages/sdk/docs/STATE-UNITS.md (composition rule).
 
   const providers$ = new BehaviorSubject<unknown[]>([]);
   const allowedDomains$ = new BehaviorSubject<string[]>([]);

package/src/features/admin-users/state/__tests__/admin-users-state-unit.test.ts

@@ -4,6 +4,7 @@ import { filter } from 'rxjs/operators';
 import type { SemiontClient } from '@semiont/sdk';
 import type { ShellStateUnit } from '../../../../state/shell-state-unit';
 import { createAdminUsersStateUnit } from '../admin-users-state-unit';
+import { assertStateUnitAxioms, disposeProbe } from '@semiont/core/testing';
 
 function mockBrowse(): ShellStateUnit {
   return { dispose: vi.fn() } as unknown as ShellStateUnit;
@@ -77,10 +78,16 @@ describe('createAdminUsersStateUnit', () => {
     stateUnit.dispose();
   });
 
-  it('disposes browse on dispose', () => {
-    const browse = mockBrowse();
-    const stateUnit = createAdminUsersStateUnit(mockClient(), browse);
-    stateUnit.dispose();
-    expect(browse.dispose).toHaveBeenCalled();
+});
+
+describe('AdminUsersStateUnit — StateUnit axioms', () => {
+  it('satisfies the StateUnit axioms (incl. A7-passed: never disposes the injected browse)', () => {
+    assertStateUnitAxioms({
+      setup: () => {
+        const browse = disposeProbe();
+        return { unit: createAdminUsersStateUnit(mockClient(), browse as unknown as ShellStateUnit), passedIn: [browse] };
+      },
+      surfaces: (u) => [u.users$, u.stats$, u.usersLoading$, u.statsLoading$],
+    });
   });
 });

package/src/features/admin-users/state/admin-users-state-unit.ts

@@ -1,7 +1,7 @@
 import { BehaviorSubject, type Observable } from 'rxjs';
 import { userDID } from '@semiont/core';
 import { createDisposer } from '@semiont/sdk';
-import type { StateUnit } from '@semiont/sdk';
+import type { StateUnit } from '@semiont/core';
 import type { ShellStateUnit } from '../../../state/shell-state-unit';
 import type { SemiontClient } from '@semiont/sdk';
 
@@ -19,7 +19,9 @@ export function createAdminUsersStateUnit(
   browse: ShellStateUnit,
 ): AdminUsersStateUnit {
   const disposer = createDisposer();
-  disposer.add(browse);
+  // `browse` (ShellStateUnit) is a *passed-in* dependency owned by the caller
+  // (`useShellStateUnit`), not this unit — do NOT add it to the disposer (it's the
+  // shared, app-scoped shell). See packages/sdk/docs/STATE-UNITS.md (composition rule).
 
   const users$ = new BehaviorSubject<unknown[]>([]);
   const stats$ = new BehaviorSubject<unknown | null>(null);

package/src/features/auth-welcome/state/__tests__/welcome-state-unit.test.ts

@@ -3,6 +3,7 @@ import { firstValueFrom } from 'rxjs';
 import { filter } from 'rxjs/operators';
 import type { SemiontClient } from '@semiont/sdk';
 import { createWelcomeStateUnit } from '../welcome-state-unit';
+import { assertStateUnitAxioms } from '@semiont/core/testing';
 
 function mockClient(overrides: {
   getMe?: ReturnType<typeof vi.fn>;
@@ -84,3 +85,13 @@ describe('createWelcomeStateUnit', () => {
     stateUnit.dispose();
   });
 });
+
+describe('WelcomeStateUnit — StateUnit axioms', () => {
+  it('satisfies the StateUnit axioms', () => {
+    assertStateUnitAxioms({
+      setup: () => createWelcomeStateUnit(mockClient()),
+      surfaces: (u) => [u.userData$, u.isProcessing$],
+      invocations: (u) => [() => u.acceptTerms()],
+    });
+  });
+});

package/src/features/auth-welcome/state/welcome-state-unit.ts

@@ -1,6 +1,6 @@
 import { BehaviorSubject, type Observable } from 'rxjs';
 import { createDisposer } from '@semiont/sdk';
-import type { StateUnit } from '@semiont/sdk';
+import type { StateUnit } from '@semiont/core';
 import type { SemiontClient } from '@semiont/sdk';
 
 export interface WelcomeStateUnit extends StateUnit {