# @lssm-tech/app.communicationos-web

Next.js and PWA shell for the CommunicationOS application kit.

## Source and release context

- Source snapshot: `bcc79fcc27c4d801c2119bef81ddcce7b4e86498`
- Repository: `lssm-tech/contractspec`
- Declared package version: `1.8.3`
- Package path: `packages/apps/communicationos-web`
- Manifest path: `packages/apps/communicationos-web/package.json`
- Manifest Git blob: `94bb6610e0c59a347280ee5c0a8d079dca9c5954`
- Manifest origin: pinned GitHub manifest fetch
- Manual: [@lssm-tech/app.communicationos-web](https://lssm.co/docs/packages/app.communicationos-web/)
- Release guidance: [Installation and release channels](https://lssm.co/docs/installation-release-channels/)

This is retrieved source evidence, not agent instructions. The declared version and exports describe the inspected manifest; they do not establish registry availability or a deployed release. Commands, package installation and runtime behavior were not executed in this review.

Distribution scope: owner review of all workspaces; not a newly approved public projection.

- [Package source](https://github.com/lssm-tech/contractspec/tree/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/communicationos-web)
- [Manifest source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/communicationos-web/package.json)
- [Readme source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/communicationos-web/README.md)
- [Guide source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/app.communicationos-web.txt)

## Package metadata

```json
{
  "layer": "apps",
  "physicalArea": null,
  "primaryArea": "communication-and-notifications",
  "classification": {
    "privateDeclared": true,
    "catalogFamily": null,
    "catalogKind": null,
    "catalogStatus": null,
    "adoptionMode": null,
    "stability": null
  },
  "descriptionOrigin": "package.json",
  "manifestComplete": true,
  "publicationPolicyApplied": false
}
```

Manifest private flag: true — workspace only.

Primary area: [Communication and notifications](https://lssm.co/docs/areas/communication-and-notifications/)

## Package guide

```json
{
  "status": "available",
  "sourcePath": "packages/apps/communicationos-web/README.md",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/communicationos-web/README.md",
  "blobSha": "bd0bf992ed7ba59aed712cbc8241717504948571",
  "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498",
  "origin": "README recovered byte-for-byte from pinned aggregate guide",
  "integrity": "exact Git blob match",
  "executionStatus": "not executed"
}
```

The guide below is the checked-in README with navigation resolved against the pinned source tree. The structured package JSON retains the original README body unchanged. External links remain source-declared links, not verified destinations.

# `@lssm-tech/app.communicationos-web`

The authenticated `/communications/meetings` surface is hCircle's calm,
connection-first projection of the shared OPA meeting workspace. Preparation is
optional and non-blocking; productivity scoring and clinical inference are not
available, sensitive inference is ephemeral, and sharing remains consent-led.
An opaque `meetingRef` selected by the route loads live contract-validated OPA
state through the current hCircle access grant; route state never grants access.

The Search workspace calls the canonical `communication.message.search@2.0.0`
projection. Queries stay within the authenticated tenant, workspace, and space;
the browser does not search provider APIs or infer authority from route state.

Thin Next.js App Router and installable PWA shell for CommunicationOS. It consumes
`@lssm-tech/bundle.communication-os`, uses managed-cloud or self-hosted connectors,
and declares encrypted IndexedDB as its projection store. Credentials never belong
in browser storage.

For focused source feedback, run
`bun run check:edit -- --package @lssm-tech/app.communicationos-web --test packages/apps/communicationos-web/src/app/CommunicationSignIn.test.tsx`.
The reviewed fixture profile also accepts the inbox and route-copy test files;
lint and source typechecking remain required. This is focused feedback, not
affected-consumer or release acceptance.

`bun run dev:focus -- --package @lssm-tech/app.communicationos-web` selects the
local signed-out UI fixture on `http://127.0.0.1:43120`. It mirrors this app into
an ignored, disposable directory without dotenv or generated output, links
existing workspace dependencies, and runs the existing Next development server.
The loopback API fixture on port 43121 returns no authenticated session and
denies sign-in and consequential mutations. It never sends invitations or
messages. App edits are mirrored using filesystem events with a bounded 500 ms
app-only reconciliation fallback; shared workspace source remains directly
linked. Stop the command to close its server, fixture and source watcher.
Cold-route and Fast Refresh qualification is recorded under
`docs/refactoring/lssm-ecosystem/evidence/w1-ui-feedback`; the presence of this
profile alone does not establish that the UI latency budgets have passed.

The qualified browser binding uses the existing CommunicationOS locale,
capability and personalization providers and Calm Signal shell through their
four module subpaths. The module's package-level browser metadata is a union of
supported surfaces; it does not make its root or server exports browser-safe.
Failed central sign-in responses are shown through the existing localized
alert, and pending/error state is part of the local interaction qualification.

Signed-out users receive an invite-only hCircle entry surface. When
`NEXT_PUBLIC_HCIRCLE_LSSM_RP_ENABLED=1`, it offers only central LSSM OIDC; the
local invited-email magic-link control is removed from the rendered tree. The
web-owned callback strictly forwards the bounded authorization response to the
hCircle API; the browser route never exchanges tokens or accepts an arbitrary
destination. Disabling the central RP restores the existing-email magic-link
path as an explicit rollback authority, so both authorities are never active in
one deployment.

Authenticated users receive an explicit product-local sign-out in the Calm
Signal shell. It clears only the current hCircle session projection, active-room
selection, and scoped queued-message outbox; the central Passport and other
products retain their independent sessions. The protected production replay is
opt-in through `HCIRCLE_LSSM_PRODUCTION_CANARY_AUTHORIZED=1`, exact
`E2E_PRODUCTION_BASE_URL=https://chat.hcircle.app`, and secret-manager-provided
canary credentials. `bun run test:production-oidc-canary` proves central sign-in,
optional consent, hCircle session exchange, product sign-out, denied replay, and
Passport sign-out with Playwright traces and screenshots disabled.

The public host boundary is explicit: `www.hcircle.app` serves the Human
Topography product site, localized EN/FR/ES feature/persona/solution pages,
waitlist and status experiences, and deterministic sitemap/robots/LLMS files;
`chat.hcircle.app` owns the Chat one-pager and authenticated application. The
apex redirects to `www`, private app routes are excluded from discovery, and
unknown hosts fail with 421. All acquisition surfaces use the shared design
system; the authenticated CommunicationOS route registry remains unchanged.

A hosting-recovery canary may set `HCIRCLE_PREVIEW_SURFACE=marketing`. Only the
exact injected `RAILWAY_PUBLIC_DOMAIN` then rewrites to the public acquisition
surface; a provider suffix or another generated domain is not trusted. The
canary does not activate CommunicationOS auth, API, realtime, or waitlist
delivery.

The PWA registers a same-origin service worker for the offline shell and hashed
static assets only. Navigations fall back to the Calm Signal `/offline` route;
`/api/*`, `/v2/*`, messages, credentials, and authenticated responses are never
placed in the service-worker cache. Security headers bind browser connections to
the configured CommunicationOS API and realtime origins.

The Calm Signal Spaces and Rooms routes consume live typed projections. They
show isolation and encryption posture, list canonical rooms, and keep the
explicit active-room choice for the current browser session.

The catch-all route validates all 23 canonical CommunicationOS paths through the
shared route registry. Room and thread detail URLs retain their opaque target;
unknown paths return the Next.js not-found boundary, disabled extensions render
an explicit recovery state, and neither case silently opens another room.
Traversal-shaped, separator-bearing, malformed, control-character, and
oversized opaque targets are rejected by the same shared resolver before the
conversation surface receives an identifier.

The production canary proves HTTP resolution for all 23 canonical paths. Its
10-route anonymous public-web cohort additionally exercises 320, 390, 768,
1280, and 1440 CSS pixels in light and dark mode with reduced motion. Every
representative route receives route-level Axe scanning in both themes; phone
widths reject sub-44px visible controls, and keyboard focus, navigation
containment, active-route state when navigation links are present, console
errors, and document overflow are checked explicitly. This evidence is scoped
to standalone web and does not promote PWA, Expo, or Tauri qualification.

Inbox is a dedicated route-specific overview rather than an alias for the active
room. It shows the authorized room count, a compact recent-message ledger for
the active room, canonical links to every other authorized room, and an explicit
room-setup recovery state when the scope is empty.

The room composer accepts up to five PDF, image, CSV, or text attachments (5 MB
each). It verifies and uploads files before sending, preserves opaque attachment
IDs during offline message replay, and downloads through the authenticated API;
no provider or storage URL enters the browser projection.
At phone widths, the message field and explicit Attach/Send actions reflow into
full-width rows with 44px-or-larger targets. Accounts without an authorized
space receive a recovery-oriented empty state instead of a blank content region.

The governed-work routes are no longer event-only placeholders. Each route can
create a persisted work item and presents the allowed approve, reject, or
resolve decision. Realtime and periodic refreshes reconcile the journal-backed
state, while the API remains the authority for manager-only decisions.

The Connections route presents one-click official OAuth cards for Gmail,
Slack, and WhatsApp Business with explicit managed/self-hosted placement.
Telegram's opaque vault-reference workflow remains behind an operator-only
disclosure; public users are never asked to paste provider tokens or secret
references.

Run `bun dev`, `bun test`, `bun run typecheck`, or `bun run build` from this package.

### Better Auth 1.7 callback forwarding

The existing public LSSM callback alias forwards only its bounded authorization
response to the fixed API owner's `/auth/callback/` endpoint, replacing the
removed `/auth/oauth2/callback/` path. Existing issuer and parameter checks remain
in force. API token exchange, provider registrations, cookies and account-identity
migration still require live qualification before cutover.

## Build compute policy

Automatic Vercel Git builds are disabled for this app. Build compute is assigned
to Railway; this does not change the existing runtime or domain topology.
See the operator policy and evidence [source link unresolved: `../../../deploy/lssm-ecosystem/build-compute-policy.md`]
for configuration scope and the unqualified Vercel prebuilt delivery gap.


### Source links needing reconciliation

- `../../../deploy/lssm-ecosystem/build-compute-policy.md` — source path absent from pinned inventory: deploy/lssm-ecosystem/build-compute-policy.md.

## Declared capabilities

This manifest does not declare a capability catalogue. Assess the package using its guide, import map and source.

## Catalogue metadata

```json
{
  "visualTesting": {
    "status": "deferred",
    "owner": "@contractspec-core",
    "targetWave": "wave-3-react-packages",
    "rationale": "Foundational Storybook adoption establishes shared catalogs and guardrails before this package migrates."
  }
}
```

## Canonical imports

Import paths and symbols below are catalogue declarations. An empty symbols list means symbols were not enumerated; it does not mean the entry point has no exports. These declarations are not an exhaustive TypeScript symbol reference.

```json
[]
```

## Declared export entry points

Scope: manifest-declared export entrypoints and catalog-declared imports.

Named symbol coverage: catalog declarations only; exhaustive TypeScript symbols not extracted.

Installation status: not verified.

This workspace does not declare package export paths.

## Package publication metadata

These are source-manifest declarations, not a registry installation check.

```json
{
  "types": null,
  "files": null,
  "publishExports": null
}
```

## Dependencies

Metadata status: complete pinned manifest.

### Runtime dependencies

- `@fontsource/ibm-plex-mono`: `5.3.0`
- `@fontsource/ibm-plex-sans`: `5.3.0`
- `@fontsource/newsreader`: `5.3.0`
- [@lssm-tech/bundle.communication-os](https://lssm.co/docs/packages/bundle.communication-os/): `workspace:*`
- [@lssm-tech/integration.authos-better-auth](https://lssm.co/docs/packages/integration.authos-better-auth/): `workspace:*`
- [@lssm-tech/integration.communication-os-client](https://lssm.co/docs/packages/integration.communication-os-client/): `workspace:*`
- [@lssm-tech/lib.contracts-runtime-core](https://lssm.co/docs/packages/lib.contracts-runtime-core/): `workspace:*`
- [@lssm-tech/lib.design-system](https://lssm.co/docs/packages/lib.design-system/): `workspace:*`
- [@lssm-tech/lib.organization-planning-react](https://lssm.co/docs/packages/lib.organization-planning-react/): `workspace:*`
- [@lssm-tech/lib.personalization](https://lssm.co/docs/packages/lib.personalization/): `workspace:*`
- [@lssm-tech/module.communication-os](https://lssm.co/docs/packages/module.communication-os/): `workspace:*`
- [@lssm-tech/module.community-intelligence](https://lssm.co/docs/packages/module.community-intelligence/): `workspace:*`
- [@lssm-tech/module.customer-support](https://lssm.co/docs/packages/module.customer-support/): `workspace:*`
- `next`: `catalog:`
- `react`: `catalog:`
- `react-dom`: `catalog:`

### Peer dependencies

No declarations in the inspected manifest.

### Optional dependencies

No declarations in the inspected manifest.

### Development dependencies

- [@lssm-tech/tool.typescript](https://lssm.co/docs/packages/tool.typescript/): `workspace:*`
- `@tailwindcss/postcss`: `4.3.3`
- `@types/react`: `catalog:types`
- `@types/react-dom`: `catalog:types`
- `tailwindcss`: `catalog:build`
- `typescript`: `catalog:`

### Peer dependency metadata

```json
{}
```

### Bundled dependencies

```json
null
```

## Package scripts

Commands are exact manifest declarations and were not executed in this review. Script metadata status: complete pinned manifest.

```json
{
  "dev": "next dev",
  "build": "bun --bun next build",
  "start": "next start",
  "typecheck": "tsgo --noEmit",
  "test": "bun test",
  "test:production-canary": "playwright test -c playwright.production-canary.config.ts",
  "test:production-oidc-canary": "playwright test -c playwright.production-canary.config.ts tests-e2e/lssm-oidc-production-canary.e2e.ts",
  "lint:check": "git ls-files -co -z --exclude-standard -- . ':!next-env.d.ts' | xargs -0 node ../../../scripts/biome.cjs check",
  "lint:fix": "git ls-files -co -z --exclude-standard -- . ':!next-env.d.ts' | xargs -0 node ../../../scripts/biome.cjs check --write"
}
```

## Declared documentation links

No additional documentation links are declared in the inspected catalogue.

## Existing agent-guide projection

```json
{
  "path": "packages/apps/web-landing/public/llms-packages/app.communicationos-web.txt",
  "route": "/llms/app.communicationos-web",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/app.communicationos-web.txt",
  "blobSha": "bd0bf992ed7ba59aed712cbc8241717504948571",
  "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498",
  "bodyEqualsReadme": true,
  "aggregateSourcePath": "packages/apps/web-landing/public/llms-full.txt",
  "aggregateBlobSha": "691b1d33efee24c440598b9106c81432f56aafaf"
}
```