sos-portal-components-react 0.3.0 → 0.3.2

package/README.md

@@ -1,217 +1,229 @@
-# SOS Portal Components React
-
-## Numbered engineering guides
-
-1. [00 — Documentation index](docs/00-INDEX.md)
-2. [01 — Portal modes, authentication and authority](docs/01-PORTAL_MODES_AND_AUTH.md)
-3. [02 — Cross-portal Tuskr cases](docs/02-CROSS_PORTAL_TUSKR_CASES.md)
-
-Read these with the owning CH application's README for runnable commands and
-flavour configuration. The cases below retain their stable IDs; the numbered
-guides supply cross-portal steps, expected results and negative checks.
-
-Start dependencies by use case: local Demo UI/BFF uses the memory vault and
-no GW; clinical coding/cache cases add Terminology through its SDK, and call
-cases add LiveKit independently. Network cases progress from GW memory/test
-to local Fabric, then the chosen online `dev:staging` Test Network flavours.
-Demo stays BFF-only throughout. See the
-[dependency table](docs/01-PORTAL_MODES_AND_AUTH.md#11-start-dependencies-for-the-case-being-tested).
-Rerun the smallest failed/affected gate while retaining valid green evidence;
-release closure still requires every affected boundary.
-
-## Runtime parity
-
-Components share use-case state between Demo and Test Network. Native support
-is export-specific: conversation uses the React Native/Web adapter; the device
-preferences renderer currently uses web DOM. A native preferences renderer
-remains future work. Components never select storage. Applications inject memory for
-all-local, Expo SQLite for native, or an explicit durable adapter. Firestore
-must not create a Demo-only component or data model.
-
-CH all-local portal execution does not start or require Chat, the telephone
-assistant or the optional web assistant. Realtime audio/video is a dedicated
-RTC boundary supplied by the host BFF. Invitations, terminal states and an
-optional unanswered audio attachment are rendered from Communications.
-
-Shared portal UI for base components. It provides the portal UI core for
-personal and professional applications across human
-health, animal care, public safety, emergency response and other configured
-sectors. The package exists to prevent each sector flavour from reimplementing
-the same shell, access journey, card navigation and governed subject workflows.
-
-Public Demo authenticates a real email account and uses BFF-validated synthetic
-profiles. Fixed Firebase test-phone codes belong only to tests in ignored
-configuration, never public Demo access. Demo business state stays behind the
-BFF Confidential Storage boundary; Test Network separately proves the complete
-organization/employee/subject lifecycle through its real authority and GW.
-
-The first implementation of a workflow may be proven in the animal-care
-portals. That does not make every future human-health consumer depend
-permanently on an animal-care component. Promotion into this package happens
-only after the shared contract is understood. Research, genomics and other
-specialist areas remain in their current package until their long-term
-boundary is deliberately chosen.
-
-## Ownership boundaries
-
-- This package owns reusable portal presentation and controlled user intents.
-- Applications own branding, routes, environment selection, BFF calls and
-  server-resolved sector/role policy.
-- `antifraud-hosting-components-react` owns neutral host- and
-  tenant-controller administration. SOS may compose it but does not fork it.
-- `antifraud-portal-components-react` owns neutral evidence and conversation
-  primitives used beyond health.
-- `terminology-components-react` owns terminology controls; the terminology
-  service and SDK own canonical systems, releases and searches.
-- FHIR/SOS/Vet data utilities and SDKs own data contracts, validation,
-  transport, signatures and persistence. React never derives authority.
-- Sector packages own their human-health, animal-care and other
-  domain-specific extensions.
-
-Browser state, a visible tab or a selected role never grants authority. Every
-protected action is enabled from trusted host capabilities and remains
-revalidated by the BFF/Gateway.
-
-## Implemented exports
-
-This is the current runtime inventory, not completion of the whole catalogue:
-
-| Export | Owner / responsibility |
-| --- | --- |
-| `SubjectConversationChat` | SOS projection of authorized subject Communications into the neutral Antifraud conversation renderer. |
-| `createLiveKitRealtimeCallClient` | Host-configured RTC client adapter; the BFF retains authorization, credentials and Communication persistence. |
-| `DeviceAssistancePreferences` | Reexport of Antifraud's controlled web preferences renderer. |
-
-The complete base-UI extraction is still pending. `PortalHeader`,
-`PortalSettingsPanel`, profile protection, subject/card navigation and several
-contact, permission and clinical controls remain in
-`uhc-portal-components-react`; application composition also remains in the
-owning portals. Research stays there pending its future owner. The catalogue
-below is acceptance scope and must not be read as an implemented export list.
-Controller administration is owned separately by
-`antifraud-hosting-components-react`.
-
-- `sos-portal-components-react/device-assistance-preferences` reexports the
-  controlled `DeviceAssistancePreferences` owned by the neutral Antifraud
-  package. Import `antifraud-portal-components-react/device-assistance-preferences.css`
-  once in the application shell. It separates consent, runtime availability
-  and explicit preparation; hosts supply localized labels, storage and runtime
-  adapters. Rendering/toggling does not prepare a model or grant subject access.
-  Use this independent entry on account pages to avoid loading conversation
-  and RTC modules. Do not fork another device preferences panel per flavour.
-
-- `sos-portal-components-react/subject-conversation-chat` provides the
-  canonical React Native/Web adapter for an already-authorized subject
-  conversation. It projects the stable SOS entry model into the neutral
-  Antifraud conversation surface backed by
-  `@kesha-antonov/react-native-chat`. Hosts retain BFF delivery, attachment
-  opening, FHIR rendering, WebRTC signaling and authorization.
-
-The compatibility export currently present in the human-health component
-package is deprecated and will delegate to this package while consumers move
-to the SOS-owned path.
-
-## Tuskr use-case catalogue
-
-The stable IDs below are intended to become Tuskr cases. Each case must be
-executed for every applicable flavour, actor, viewport and environment. Demo
-uses synthetic state and must say so; Test Network and Production must use
-their real authorized BFF path.
-
-Use [02 — Cross-portal Tuskr cases](docs/02-CROSS_PORTAL_TUSKR_CASES.md)
-for Personal ↔ Professional prerequisites, numbered actions, both-side
-readback, rejected access, reset/revocation and execution evidence. A documented
-case is an acceptance target, not an end-to-end pass claim.
-
-| ID | Area | Governed journey and acceptance target |
-|---|---|---|
-| SOS-PORTAL-001 | Shell | Render the shared top bar, brand slot, account/profile menu, current subject and responsive navigation without flavour-specific forks. |
-| SOS-PORTAL-002 | Entry | Choose an enabled Demo, Test Network or Production entry supplied by trusted host configuration; a browser choice never selects network infrastructure. |
-| SOS-PORTAL-003 | Sign-in | Sign in through the host adapter, restore the exact protected profile and reject a profile belonging to another access path. |
-| SOS-PORTAL-004 | Biometrics | Unlock a protected profile with platform biometrics/passkey when available and use the governed PIN/password recovery fallback without exposing keys to React. |
-| SOS-PORTAL-005 | Registration | Register or accept an invitation for the applicable person, professional or animal-responsible profile; registration alone grants no subject access. |
-| SOS-PORTAL-006 | Cards | List only server-authorized individual or animal cards, select one card and preserve its stable identifier across navigation/reload. |
-| SOS-PORTAL-007 | Card sections | Resolve card sections from subject kind, sector, role and backend capabilities; hidden or read-only sections cannot be enabled by URL or browser state. |
-| SOS-PORTAL-008 | Identity | View and edit the permitted identity fields, provenance and attestations for a selected card while preserving immutable identifiers. |
-| SOS-PORTAL-009 | Related entities | Add, view, update or remove authorized related people, animals and organizations with explicit relationship type and provenance. |
-| SOS-PORTAL-010 | Contacts | Manage ordinary and emergency contacts independently, including priority, relationship, availability and emergency-only disclosure. |
-| SOS-PORTAL-011 | Encounters | List, open and author permitted encounters; bind contributions to the acting professional, organization, subject and server-confirmed scope. |
-| SOS-PORTAL-012 | Communications | Render one canonical conversation of DIDComm/FHIR Communications with text and governed attachments such as Bundles, documents, ICS, images and audio in both Personal and an authorized Professional card channel. |
-| SOS-PORTAL-013 | Calls | Initiate and display authorized audio/video calls and outgoing, incoming, completed, rejected, cancelled or missed call events without treating call signaling as clinical authority. |
-| SOS-PORTAL-014 | Appointments | Search availability and create, update or cancel appointments for applicable services, including blood-donation centres and other scheduled providers. |
-| SOS-PORTAL-015 | Clinical viewer | View authorized clinical documents, IPS summaries, sections, timelines and source/provenance details for human or animal cards. |
-| SOS-PORTAL-016 | Clinical authoring | Create and edit clinical documents through the canonical section-based editor, including encounters, observations, immunizations and host-enabled sections. |
-| SOS-PORTAL-017 | Credentials | Create, display, scan and verify supported health/data-card credentials and QR transports while keeping signing and verification outside React. |
-| SOS-PORTAL-018 | Permissions | View and change only permitted Consent/access relationships, group memberships and card grants; notifications never substitute for authorization. |
-| SOS-PORTAL-019 | Employee lifecycle | Compose the canonical Antifraud Hosting workforce screen for invitations, licences, employees and devices; SOS supplies sector labels and adapters, not a duplicate implementation. |
-| SOS-PORTAL-020 | Individual members | Manage an individual's authorized members/delegates separately from organization employees, with explicit lifecycle and revocation. |
-| SOS-PORTAL-021 | Emergency access | Show protected emergency data and request governed exceptional/break-glass access with reason, expiry, audit and clear post-access state. |
-| SOS-PORTAL-022 | Subject index | Display real index-update Communications from authorized providers and open linked records without manufacturing parallel chat events. |
-| SOS-PORTAL-023 | Provider directory | Select authorized card/index, clinical, appointment or emergency providers from host-supplied directories without hard-coded flavour endpoints. |
-| SOS-PORTAL-024 | Accessibility | Complete every shared journey by keyboard and screen reader with visible focus, labelled controls, status announcements and responsive layouts. |
-| SOS-PORTAL-025 | Expo reuse | Render platform-neutral contracts in Expo Android/iOS adapters and web adapters while retaining one message/card/action model and host-owned native capabilities. |
-| SOS-PORTAL-026 | Preferences | Reuse one device/account Preferences surface across modes: appearance, text size, locale, accessibility and actual speech/language-model enablement/availability/preparation, with explicit disabled states and no implied subject authorization. |
-| SOS-PORTAL-027 | Failure safety | Fail closed on missing capabilities, expired sessions, invalid attachments, unavailable providers or rejected persistence and preserve an actionable, non-sensitive error. |
-| SOS-PORTAL-028 | Controller embedding | In CH Management, embed the published Antifraud controller components for groups, departments, workforce and memberships until controller access is removed from branded professional portals. |
-| SOS-PORTAL-029 | Conversation threads | Open the individual card's root channel and authorized child threads for members, related entities or emergency contacts; each thread keeps stable subject/relationship/participant identifiers, and contact status alone grants no message access. |
-
-### Communications execution matrix
-
-Tuskr must exercise `SOS-PORTAL-012`, `SOS-PORTAL-013` and
-`SOS-PORTAL-029` together:
-
-| Actor/surface | Root card channel | Authorized child thread | Required call events |
-|---|---|---|---|
-| Personal portal | View/send according to the individual's capability | Open a member, related-entity or emergency-contact thread only after the BFF confirms participation | outgoing, incoming, completed, rejected/cancelled and missed audio/video calls |
-| Professional portal | View/send in the selected individual's card channel only with professional subject scope | Open only child threads included in the professional's server-resolved scope | the same persisted call-event projection; no browser-manufactured duplicate |
-| Reload/cross-surface | Preserve stable channel, thread and message identifiers | Preserve the exact relationship reference and participant set | Personal and Professional render the same authorized event status and attachment metadata |
-
-Acceptance requires real persisted Communications (or the explicit synthetic
-Demo adapter), chronological projection without a parallel chat record, and
-negative tests proving that a contact listed for emergencies cannot enumerate
-or open a thread without separate authorization.
-
-## Tracked specialist integration cases
-
-These cases must remain visible in Tuskr and in CH while they are migrated,
-but they are not owned by the initial SOS core package.
-
-| ID | Current owner | Planned direction | Acceptance target |
-|---|---|---|---|
-| HEALTH-RESEARCH-001 | Human-health components / host adapter | Candidate for animal-care components | Create, update, activate and revoke a research study with server-confirmed controller or delegated authority. |
-| HEALTH-RESEARCH-002 | Human-health components / host adapter | Candidate for animal-care components | Search and add authorized research subjects without turning discovery into access. |
-| HEALTH-RESEARCH-003 | Human-health components / host adapter | Candidate for animal-care components | Import research data, map source fields, track jobs and review/reclassify/discard staged records. |
-| HEALTH-RESEARCH-004 | Human-health components / host adapter | Candidate for animal-care components | Manage research contracts, study invitations, subscriptions and governed data access separately from ordinary card permissions. |
-| HEALTH-RESEARCH-005 | Human-health components / host adapter | Undecided specialist package | Use transcription/edge models and future genomic workflows only through explicit capability, provenance and privacy policy. |
-
-The current source inventory still contains host-local research panels.
-Migration is complete only when consuming portals import their published
-human-health implementation and the local alternatives are deprecated.
-Group-management source already lives in
-the Antifraud Controller application; its controlled UI must be exported by
-the Antifraud Hosting component package before CH can remove its final local
-group adapter.
-
-## Explicitly outside the initial core
-
-- host registry, tenant admission and organization lifecycle policy (Antifraud
-  Controller/Hosting);
-- research-study administration, research-subject import and genomic workflows
-  (tracked above through their human-health to animal-care/specialist migration);
-- terminology databases and searches;
-- FHIR validation/conversion, DIDComm transport, wallets, signatures, QR
-  cryptography, WebRTC signaling and persistence;
-- application-specific routes, branding and deployment configuration.
-
-## Delivery order
-
-1. Inventory the current verified components in deprecated sector portals,
-   human-health components and consuming portal flavours.
-2. Add a contract test for one canonical component per use case.
-3. Move the current implementation without changing its data/authority
-   boundary, then switch all CH flavours to the published package.
-4. Mark old exports deprecated and keep their legacy tests separately runnable.
-5. Add web plus Expo adapters only where the same controlled contract is
-   genuinely reusable.
-6. Remove compatibility implementations only in a later breaking release.
-
+# SOS Portal Components React
+
+## Numbered engineering guides
+
+1. [00 — Documentation index](docs/00-INDEX.md)
+2. [01 — Portal modes, authentication and authority](docs/01-PORTAL_MODES_AND_AUTH.md)
+3. [02 — Cross-portal Tuskr cases](docs/02-CROSS_PORTAL_TUSKR_CASES.md)
+
+Read these with the owning CH application's README for runnable commands and
+flavour configuration. The cases below retain their stable IDs; the numbered
+guides supply cross-portal steps, expected results and negative checks.
+
+Start dependencies by use case: local Demo UI/BFF uses the memory vault and
+no GW; clinical coding/cache cases add Terminology through its SDK, and call
+cases add LiveKit independently. Network cases progress from GW memory/test
+to local Fabric, then the chosen online `dev:staging` Test Network flavours.
+Demo stays BFF-only throughout. See the
+[dependency table](docs/01-PORTAL_MODES_AND_AUTH.md#11-start-dependencies-for-the-case-being-tested).
+Rerun the smallest failed/affected gate while retaining valid green evidence;
+release closure still requires every affected boundary.
+
+## Runtime parity
+
+`SubjectCardLocatorFields` is a controlled web input, exported separately at
+`sos-portal-components-react/subject-card-locator-fields`. It distinguishes
+card number from DID/QR entry. For numbers, the user chooses person or animal;
+animals also choose a supplied species or enter another NCBI taxonomy ID.
+The host verifies those hints against the registered card. DID/QR lookup uses
+the registered identity without asking the user to reinterpret its species.
+The same renderer works in Demo and Network; it provides no authorization or
+persistence and requires a native renderer before use in Expo.
+
+Components share use-case state between Demo and Test Network. Native support
+is export-specific: conversation uses the React Native/Web adapter; the device
+preferences renderer currently uses web DOM. A native preferences renderer
+remains future work. Components never select storage. Applications inject memory for
+all-local, Expo SQLite for native, or an explicit durable adapter. Firestore
+must not create a Demo-only component or data model.
+
+CH all-local portal execution does not start or require Chat, the telephone
+assistant or the optional web assistant. Realtime audio/video is a dedicated
+RTC boundary supplied by the host BFF. Invitations, terminal states and an
+optional unanswered audio attachment are rendered from Communications.
+
+Shared portal UI for base components. It provides the portal UI core for
+personal and professional applications across human
+health, animal care, public safety, emergency response and other configured
+sectors. The package exists to prevent each sector flavour from reimplementing
+the same shell, access journey, card navigation and governed subject workflows.
+
+Public Demo authenticates a real email account and uses BFF-validated synthetic
+profiles. Fixed Firebase test-phone codes belong only to tests in ignored
+configuration, never public Demo access. Demo business state stays behind the
+BFF Confidential Storage boundary; Test Network separately proves the complete
+organization/employee/subject lifecycle through its real authority and GW.
+
+The first implementation of a workflow may be proven in the animal-care
+portals. That does not make every future human-health consumer depend
+permanently on an animal-care component. Promotion into this package happens
+only after the shared contract is understood. Research, genomics and other
+specialist areas remain in their current package until their long-term
+boundary is deliberately chosen.
+
+## Ownership boundaries
+
+- This package owns reusable portal presentation and controlled user intents.
+- Applications own branding, routes, environment selection, BFF calls and
+  server-resolved sector/role policy.
+- `antifraud-hosting-components-react` owns neutral host- and
+  tenant-controller administration. SOS may compose it but does not fork it.
+- `antifraud-portal-components-react` owns neutral evidence and conversation
+  primitives used beyond health.
+- `terminology-components-react` owns terminology controls; the terminology
+  service and SDK own canonical systems, releases and searches.
+- FHIR/SOS/Vet data utilities and SDKs own data contracts, validation,
+  transport, signatures and persistence. React never derives authority.
+- Sector packages own their human-health, animal-care and other
+  domain-specific extensions.
+
+Browser state, a visible tab or a selected role never grants authority. Every
+protected action is enabled from trusted host capabilities and remains
+revalidated by the BFF/Gateway.
+
+## Implemented exports
+
+This is the current runtime inventory, not completion of the whole catalogue:
+
+| Export | Owner / responsibility |
+| --- | --- |
+| `SubjectConversationChat` | SOS projection of authorized subject Communications into the neutral Antifraud conversation renderer. |
+| `createLiveKitRealtimeCallClient` | Host-configured RTC client adapter; the BFF retains authorization, credentials and Communication persistence. |
+| `useRealtimeCallSessionLifecycle` | Shared persisted-end observation and profile-owned session cleanup for Personal and Professional, including React Strict Mode replay. |
+| `DeviceAssistancePreferences` | Reexport of Antifraud's controlled web preferences renderer. |
+| `PushNotificationRegistration` | Controlled browser-registration status, explicit enable and per-device revoke actions. The host owns permission, subscription/token, verified identity, BFF and transport. |
+| `EmergencyContactCardDirectory` | Controlled card-linked emergency recipients and primary priority; host callbacks retain contact mutation, controller authority and persistence. |
+
+The complete base-UI extraction is still pending. `PortalHeader`,
+`PortalSettingsPanel`, profile protection, subject/card navigation and several
+contact, permission and clinical controls remain in
+`uhc-portal-components-react`; application composition also remains in the
+owning portals. Research stays there pending its future owner. The catalogue
+below is acceptance scope and must not be read as an implemented export list.
+Controller administration is owned separately by
+`antifraud-hosting-components-react`.
+
+- `sos-portal-components-react/device-assistance-preferences` reexports the
+  controlled `DeviceAssistancePreferences` owned by the neutral Antifraud
+  package. Import `antifraud-portal-components-react/device-assistance-preferences.css`
+  once in the application shell. It separates consent, runtime availability
+  and explicit preparation; hosts supply localized labels, storage and runtime
+  adapters. Rendering/toggling does not prepare a model or grant subject access.
+  Use this independent entry on account pages to avoid loading conversation
+  and RTC modules. Do not fork another device preferences panel per flavour.
+
+- `sos-portal-components-react/subject-conversation-chat` provides the
+  canonical React Native/Web adapter for an already-authorized subject
+  conversation. It projects the stable SOS entry model into the neutral
+  Antifraud conversation surface backed by
+  `@kesha-antonov/react-native-chat`. Hosts retain BFF delivery, attachment
+  opening, FHIR rendering, WebRTC signaling and authorization.
+
+The compatibility export currently present in the human-health component
+package is deprecated and will delegate to this package while consumers move
+to the SOS-owned path.
+
+## Tuskr use-case catalogue
+
+The stable IDs below are intended to become Tuskr cases. Each case must be
+executed for every applicable flavour, actor, viewport and environment. Demo
+uses synthetic state and must say so; Test Network and Production must use
+their real authorized BFF path.
+
+Use [02 — Cross-portal Tuskr cases](docs/02-CROSS_PORTAL_TUSKR_CASES.md)
+for Personal ↔ Professional prerequisites, numbered actions, both-side
+readback, rejected access, reset/revocation and execution evidence. A documented
+case is an acceptance target, not an end-to-end pass claim.
+
+| ID | Area | Governed journey and acceptance target |
+|---|---|---|
+| SOS-PORTAL-001 | Shell | Render the shared top bar, brand slot, account/profile menu, current subject and responsive navigation without flavour-specific forks. |
+| SOS-PORTAL-002 | Entry | Choose an enabled Demo, Test Network or Production entry supplied by trusted host configuration; a browser choice never selects network infrastructure. |
+| SOS-PORTAL-003 | Sign-in | Sign in through the host adapter, restore the exact protected profile and reject a profile belonging to another access path. |
+| SOS-PORTAL-004 | Biometrics | Unlock a protected profile with platform biometrics/passkey when available and use the governed PIN/password recovery fallback without exposing keys to React. |
+| SOS-PORTAL-005 | Registration | Register or accept an invitation for the applicable person, professional or animal-responsible profile; registration alone grants no subject access. |
+| SOS-PORTAL-006 | Cards | List only server-authorized individual or animal cards, select one card and preserve its stable identifier across navigation/reload. |
+| SOS-PORTAL-007 | Card sections | Resolve card sections from subject kind, sector, role and backend capabilities; hidden or read-only sections cannot be enabled by URL or browser state. |
+| SOS-PORTAL-008 | Identity | View and edit the permitted identity fields, provenance and attestations for a selected card while preserving immutable identifiers. |
+| SOS-PORTAL-009 | Related entities | Add, view, update or remove authorized related people, animals and organizations with explicit relationship type and provenance. |
+| SOS-PORTAL-010 | Contacts | Manage ordinary and emergency contacts independently, including priority, relationship, availability and emergency-only disclosure. |
+| SOS-PORTAL-011 | Encounters | List, open and author permitted encounters; bind contributions to the acting professional, organization, subject and server-confirmed scope. |
+| SOS-PORTAL-012 | Communications | Render one canonical conversation of DIDComm/FHIR Communications with text and governed attachments such as Bundles, documents, ICS, images and audio in both Personal and an authorized Professional card channel. |
+| SOS-PORTAL-013 | Calls | Initiate and display authorized audio/video calls and outgoing, incoming, completed, rejected, cancelled or missed call events without treating call signaling as clinical authority. |
+| SOS-PORTAL-014 | Appointments | Search availability and create, update or cancel appointments for applicable services, including blood-donation centres and other scheduled providers. |
+| SOS-PORTAL-015 | Clinical viewer | View authorized clinical documents, IPS summaries, sections, timelines and source/provenance details for human or animal cards. |
+| SOS-PORTAL-016 | Clinical authoring | Create and edit clinical documents through the canonical section-based editor, including encounters, observations, immunizations and host-enabled sections. |
+| SOS-PORTAL-017 | Credentials | Create, display, scan and verify supported health/data-card credentials and QR transports while keeping signing and verification outside React. |
+| SOS-PORTAL-018 | Permissions | View and change only permitted Consent/access relationships, group memberships and card grants; notifications never substitute for authorization. |
+| SOS-PORTAL-019 | Employee lifecycle | Compose the canonical Antifraud Hosting workforce screen for invitations, licences, employees and devices; SOS supplies sector labels and adapters, not a duplicate implementation. |
+| SOS-PORTAL-020 | Individual members | Manage an individual's authorized members/delegates separately from organization employees, with explicit lifecycle and revocation. |
+| SOS-PORTAL-021 | Emergency access | Show protected emergency data and request governed exceptional/break-glass access with reason, expiry, audit and clear post-access state. |
+| SOS-PORTAL-022 | Subject index | Display real index-update Communications from authorized providers and open linked records without manufacturing parallel chat events. |
+| SOS-PORTAL-023 | Provider directory | Select authorized card/index, clinical, appointment or emergency providers from host-supplied directories without hard-coded flavour endpoints. |
+| SOS-PORTAL-024 | Accessibility | Complete every shared journey by keyboard and screen reader with visible focus, labelled controls, status announcements and responsive layouts. |
+| SOS-PORTAL-025 | Expo reuse | Render platform-neutral contracts in Expo Android/iOS adapters and web adapters while retaining one message/card/action model and host-owned native capabilities. |
+| SOS-PORTAL-026 | Preferences | Reuse one device/account Preferences surface across modes: appearance, text size, locale, accessibility and actual speech/language-model enablement/availability/preparation, with explicit disabled states and no implied subject authorization. |
+| SOS-PORTAL-027 | Failure safety | Fail closed on missing capabilities, expired sessions, invalid attachments, unavailable providers or rejected persistence and preserve an actionable, non-sensitive error. |
+| SOS-PORTAL-028 | Controller embedding | In CH Management, embed the published Antifraud controller components for groups, departments, workforce and memberships until controller access is removed from branded professional portals. |
+| SOS-PORTAL-029 | Conversation threads | Open the individual card's root channel and authorized child threads for members, related entities or emergency contacts; each thread keeps stable subject/relationship/participant identifiers, and contact status alone grants no message access. |
+
+### Communications execution matrix
+
+Tuskr must exercise `SOS-PORTAL-012`, `SOS-PORTAL-013` and
+`SOS-PORTAL-029` together:
+
+| Actor/surface | Root card channel | Authorized child thread | Required call events |
+|---|---|---|---|
+| Personal portal | View/send according to the individual's capability | Open a member, related-entity or emergency-contact thread only after the BFF confirms participation | outgoing, incoming, completed, rejected/cancelled and missed audio/video calls |
+| Professional portal | View/send in the selected individual's card channel only with professional subject scope | Open only child threads included in the professional's server-resolved scope | the same persisted call-event projection; no browser-manufactured duplicate |
+| Reload/cross-surface | Preserve stable channel, thread and message identifiers | Preserve the exact relationship reference and participant set | Personal and Professional render the same authorized event status and attachment metadata |
+
+Acceptance requires real persisted Communications (or the explicit synthetic
+Demo adapter), chronological projection without a parallel chat record, and
+negative tests proving that a contact listed for emergencies cannot enumerate
+or open a thread without separate authorization.
+
+## Tracked specialist integration cases
+
+These cases must remain visible in Tuskr and in CH while they are migrated,
+but they are not owned by the initial SOS core package.
+
+| ID | Current owner | Planned direction | Acceptance target |
+|---|---|---|---|
+| HEALTH-RESEARCH-001 | Human-health components / host adapter | Candidate for animal-care components | Create, update, activate and revoke a research study with server-confirmed controller or delegated authority. |
+| HEALTH-RESEARCH-002 | Human-health components / host adapter | Candidate for animal-care components | Search and add authorized research subjects without turning discovery into access. |
+| HEALTH-RESEARCH-003 | Human-health components / host adapter | Candidate for animal-care components | Import research data, map source fields, track jobs and review/reclassify/discard staged records. |
+| HEALTH-RESEARCH-004 | Human-health components / host adapter | Candidate for animal-care components | Manage research contracts, study invitations, subscriptions and governed data access separately from ordinary card permissions. |
+| HEALTH-RESEARCH-005 | Human-health components / host adapter | Undecided specialist package | Use transcription/edge models and future genomic workflows only through explicit capability, provenance and privacy policy. |
+
+The current source inventory still contains host-local research panels.
+Migration is complete only when consuming portals import their published
+human-health implementation and the local alternatives are deprecated.
+Group-management source already lives in
+the Antifraud Controller application; its controlled UI must be exported by
+the Antifraud Hosting component package before CH can remove its final local
+group adapter.
+
+## Explicitly outside the initial core
+
+- host registry, tenant admission and organization lifecycle policy (Antifraud
+  Controller/Hosting);
+- research-study administration, research-subject import and genomic workflows
+  (tracked above through their human-health to animal-care/specialist migration);
+- terminology databases and searches;
+- FHIR validation/conversion, DIDComm transport, wallets, signatures, QR
+  cryptography, WebRTC signaling and persistence;
+- application-specific routes, branding and deployment configuration.
+
+## Delivery order
+
+1. Inventory the current verified components in deprecated sector portals,
+   human-health components and consuming portal flavours.
+2. Add a contract test for one canonical component per use case.
+3. Move the current implementation without changing its data/authority
+   boundary, then switch all CH flavours to the published package.
+4. Mark old exports deprecated and keep their legacy tests separately runnable.
+5. Add web plus Expo adapters only where the same controlled contract is
+   genuinely reusable.
+6. Remove compatibility implementations only in a later breaking release.
+

package/dist/EmergencyContactCardDirectory.d.ts

@@ -0,0 +1,30 @@
+import type { SoschainDemoContact, SoschainDemoSubject } from 'sos-data-utils-ts/portal-demo-fixtures';
+export type EmergencyContactCardDirectoryCopy = Readonly<{
+    title: string;
+    controller: string;
+    contactCard: string;
+    add: string;
+    remove: string;
+    makePrimary: string;
+    primary: string;
+    empty: string;
+    noCandidates: string;
+    authority: string;
+}>;
+export type EmergencyContactCardDirectoryProps = Readonly<{
+    copy: EmergencyContactCardDirectoryCopy;
+    contacts: readonly SoschainDemoContact<string>[];
+    candidates: readonly Pick<SoschainDemoSubject, 'uhcId' | 'nickname'>[];
+    controllerLabel: string;
+    busy?: boolean;
+    error?: string;
+    className?: string;
+    actionClassName?: string;
+    selectClassName?: string;
+    onAdd(subjectIdentifier: string): void | Promise<void>;
+    onRemove(contactId: string): void | Promise<void>;
+    onMakePrimary(contactId: string): void | Promise<void>;
+}>;
+/** Controlled card relationships; the host owns persistence and authorization. */
+export declare function EmergencyContactCardDirectory({ copy, contacts, candidates, controllerLabel, busy, error, className, actionClassName, selectClassName, onAdd, onRemove, onMakePrimary }: EmergencyContactCardDirectoryProps): import("react").JSX.Element;
+//# sourceMappingURL=EmergencyContactCardDirectory.d.ts.map

package/dist/EmergencyContactCardDirectory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmergencyContactCardDirectory.d.ts","sourceRoot":"","sources":["../src/EmergencyContactCardDirectory.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,mBAAmB,EAAC,mBAAmB,EAAC,MAAM,wCAAwC,CAAA;AAGnG,MAAM,MAAM,iCAAiC,GAAC,QAAQ,CAAC;IACrD,KAAK,EAAC,MAAM,CAAC;IAAA,UAAU,EAAC,MAAM,CAAC;IAAA,WAAW,EAAC,MAAM,CAAC;IAAA,GAAG,EAAC,MAAM,CAAC;IAAA,MAAM,EAAC,MAAM,CAAA;IAC1E,WAAW,EAAC,MAAM,CAAC;IAAA,OAAO,EAAC,MAAM,CAAC;IAAA,KAAK,EAAC,MAAM,CAAC;IAAA,YAAY,EAAC,MAAM,CAAC;IAAA,SAAS,EAAC,MAAM,CAAA;CACpF,CAAC,CAAA;AAEF,MAAM,MAAM,kCAAkC,GAAC,QAAQ,CAAC;IACtD,IAAI,EAAC,iCAAiC,CAAA;IACtC,QAAQ,EAAC,SAAS,mBAAmB,CAAC,MAAM,CAAC,EAAE,CAAA;IAC/C,UAAU,EAAC,SAAS,IAAI,CAAC,mBAAmB,EAAC,OAAO,GAAC,UAAU,CAAC,EAAE,CAAA;IAClE,eAAe,EAAC,MAAM,CAAA;IACtB,IAAI,CAAC,EAAC,OAAO,CAAA;IACb,KAAK,CAAC,EAAC,MAAM,CAAA;IACb,SAAS,CAAC,EAAC,MAAM,CAAA;IACjB,eAAe,CAAC,EAAC,MAAM,CAAA;IACvB,eAAe,CAAC,EAAC,MAAM,CAAA;IACvB,KAAK,CAAC,iBAAiB,EAAC,MAAM,GAAE,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IAClD,QAAQ,CAAC,SAAS,EAAC,MAAM,GAAE,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7C,aAAa,CAAC,SAAS,EAAC,MAAM,GAAE,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC,CAAA;CACnD,CAAC,CAAA;AAEF,kFAAkF;AAClF,wBAAgB,6BAA6B,CAAC,EAAC,IAAI,EAAC,QAAQ,EAAC,UAAU,EAAC,eAAe,EAAC,IAAI,EAAC,KAAK,EAAC,SAAS,EAAC,eAAe,EAAC,eAAe,EAAC,KAAK,EAAC,QAAQ,EAAC,aAAa,EAAC,EAAC,kCAAkC,+BA2B5M"}

package/dist/EmergencyContactCardDirectory.js

@@ -0,0 +1,13 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, useState } from 'react';
+/** Controlled card relationships; the host owns persistence and authorization. */
+export function EmergencyContactCardDirectory({ copy, contacts, candidates, controllerLabel, busy, error, className, actionClassName, selectClassName, onAdd, onRemove, onMakePrimary }) {
+    const id = useId();
+    const [selection, setSelection] = useState('');
+    const available = candidates.filter(candidate => !contacts.some(contact => contact.subjectId === candidate.uhcId));
+    const selected = available.some(candidate => candidate.uhcId === selection) ? selection : '';
+    return _jsxs("section", { "aria-labelledby": `${id}-title`, className: ['emergency-contact-card-directory', className].filter(Boolean).join(' '), children: [_jsx("h3", { id: `${id}-title`, children: copy.title }), _jsxs("p", { children: [_jsxs("strong", { children: [copy.controller, ": "] }), controllerLabel] }), _jsx("p", { children: copy.authority }), _jsxs("fieldset", { disabled: busy, children: [contacts.length ? _jsx("ul", { children: contacts.map(contact => _jsxs("li", { children: [_jsx("strong", { children: contact.label }), _jsx("p", { children: contact.relationshipLabel }), contact.primary ? _jsx("p", { children: copy.primary }) : _jsx("button", { type: "button", className: actionClassName, disabled: busy, onClick: () => void onMakePrimary(contact.contactId), children: copy.makePrimary }), _jsx("button", { type: "button", className: actionClassName, disabled: busy, onClick: () => void onRemove(contact.contactId), children: copy.remove })] }, contact.contactId)) }) : _jsx("p", { children: copy.empty }), available.length ? _jsxs("form", { onSubmit: event => { event.preventDefault(); if (!busy && selected)
+                            void onAdd(selected); }, children: [_jsx("label", { htmlFor: `${id}-contact`, children: copy.contactCard }), _jsxs("select", { id: `${id}-contact`, className: selectClassName, value: selected, onChange: event => setSelection(event.target.value), required: true, children: [_jsx("option", { value: "", disabled: true, children: copy.contactCard }), available.map(candidate => _jsx("option", { value: candidate.uhcId, children: candidate.nickname }, candidate.uhcId))] }), _jsx("button", { type: "submit", className: actionClassName, disabled: busy || !selected, children: copy.add })] }) : _jsx("p", { children: copy.noCandidates })] }), error ? _jsx("p", { role: "alert", children: error }) : null] });
+}
+//# sourceMappingURL=EmergencyContactCardDirectory.js.map

package/dist/EmergencyContactCardDirectory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmergencyContactCardDirectory.js","sourceRoot":"","sources":["../src/EmergencyContactCardDirectory.tsx"],"names":[],"mappings":"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"}