@effect.healthcare/messenger 0.4.2 → 0.6.0

package/README.md

@@ -8,6 +8,8 @@ It renders nothing — no template, no styles. You configure it, bind an event,
 
 > This foundation is **receive‑only**; outbound collaboration messaging is a future capability.
 
+The messenger is built on `@scalable.software/component` `^0.5.0`. The API, the events and their `detail` are unchanged. A host that serves the base component through an import map must serve `^0.5.0`.
+
 ## Overview
 
 ```js

package/dist/index.d.ts

@@ -1,3 +1,4 @@
-export { Tag, Session, Protocol, Message, Attributes, State, Connection, Operation, Event, Gesture, } from "./messenger.meta.js";
+export { Tag, Session, Endpoint, Protocol, Message, Attributes, State, Connection, Operation, Event, Gesture, } from "./messenger.meta.js";
+export { type Path } from "./messenger.meta.js";
 export { Validate } from "./messenger.validation.js";
 export { Messenger } from "./messenger.js";

package/dist/index.js

@@ -1,3 +1,3 @@
-export { Tag, Session, Protocol, Message, Attributes, State, Connection, Operation, Event, Gesture, } from "./messenger.meta.js";
+export { Tag, Session, Endpoint, Protocol, Message, Attributes, State, Connection, Operation, Event, Gesture, } from "./messenger.meta.js";
 export { Validate } from "./messenger.validation.js";
 export { Messenger } from "./messenger.js";

package/dist/messenger.d.ts

@@ -4,7 +4,7 @@
 import { Component } from "@scalable.software/component";
 import { type Configuration } from "@scalable.software/component";
 import { Attributes, Connection } from "./messenger.meta.js";
-import { type Endpoint } from "./messenger.meta.js";
+import { type Path } from "./messenger.meta.js";
 /**
  * Configuration for the headless component — no template or stylesheet.
  * @category Configuration
@@ -31,11 +31,11 @@ export declare class Messenger extends Component {
      */
     private _connection;
     /**
-     * The negotiate endpoint URL. When absent the messenger stays disconnected.
+     * The negotiate request path. When absent the messenger stays disconnected.
      * @category State
      * @hidden
      */
-    private _endpoint;
+    private _path;
     /**
      * The live Web PubSub socket. Held so it can be closed and replaced.
      * @category State
@@ -47,7 +47,7 @@ export declare class Messenger extends Component {
      * @category Event
      * @hidden
      */
-    private _onendpointchange;
+    private _onpathchange;
     private _onconnecting;
     private _onconnected;
     private _ondisconnected;
@@ -70,11 +70,11 @@ export declare class Messenger extends Component {
     get connection(): Connection;
     protected set connection(connection: Connection);
     /**
-     * The negotiate endpoint URL. When absent the messenger stays disconnected.
+     * The negotiate request path. When absent the messenger stays disconnected.
      * @category State
      */
-    get endpoint(): Endpoint | null;
-    set endpoint(endpoint: Endpoint | null);
+    get path(): Path | null;
+    set path(path: Path | null);
     /**
      * The session token, read fresh from local storage on every access — never
      * cached — because the License component renews and rewrites the key.
@@ -83,9 +83,18 @@ export declare class Messenger extends Component {
      */
     private get _token();
     /**
-     * Negotiates a client access URL from the configured endpoint, authenticating
+     * The endpoint host base URL, read fresh from local storage on every access —
+     * never cached — mirroring the session token. Composed with the `path` state
+     * to form the negotiate URL. When absent the messenger stays disconnected.
+     * @category State
+     * @hidden
+     */
+    private get _host();
+    /**
+     * Negotiates a client access URL from the configured path, authenticating
      * with the session token, then opens the live connection. No-op when the
-     * endpoint or token is unavailable, or when already connecting or connected.
+     * path or token is unavailable, or when already connecting or connected.
+     * When negotiate fails the connection returns to `disconnected`.
      * @category Operation
      */
     connect: () => Promise<void>;
@@ -103,11 +112,11 @@ export declare class Messenger extends Component {
      */
     send: (message: object) => boolean;
     /**
-     * Subscribes to the `onendpointchange` event. Assigning replaces the previous
+     * Subscribes to the `onpathchange` event. Assigning replaces the previous
      * handler; assigning `null` removes it.
      * @category Event
      */
-    set onendpointchange(handler: EventListener | null);
+    set onpathchange(handler: EventListener | null);
     /**
      * Subscribes to the `onconnecting` event. Assigning replaces the previous
      * handler; assigning `null` removes it.
@@ -139,7 +148,7 @@ export declare class Messenger extends Component {
      */
     protected _attributeHandlers: {
         connection: (value: Connection) => false | void;
-        endpoint: (value: Endpoint) => string;
+        path: (value: Path) => string;
     };
     /**
      * Cache element references to improve performance
@@ -166,7 +175,15 @@ export declare class Messenger extends Component {
      */
     protected _removeEventListeners: () => void;
     /**
-     * Negotiates a short-lived Web PubSub client access URL from the endpoint,
+     * Called by the disconnectedCallback prototypical method, after
+     * `_removeEventListeners`. Closes the live connection so a removed element
+     * does not keep a socket open.
+     * @category Configuration
+     * @hidden
+     */
+    protected _dispose: () => void;
+    /**
+     * Negotiates a short-lived Web PubSub client access URL from the path,
      * authenticating the request with the session token.
      * @category Operation
      * @hidden

package/dist/messenger.js

@@ -4,7 +4,7 @@
 // Base Component
 import { Component } from "@scalable.software/component";
 // Component Metadata
-import { Tag, Attributes, Connection, Event, Gesture, Session, Protocol, Message, } from "./messenger.meta.js";
+import { Tag, Attributes, Connection, Event, Gesture, Session, Endpoint, Protocol, Message, } from "./messenger.meta.js";
 // Component Validation
 import { Validate } from "./messenger.validation.js";
 /**
@@ -39,11 +39,11 @@ export class Messenger extends Component {
      */
     _connection = Connection.DISCONNECTED;
     /**
-     * The negotiate endpoint URL. When absent the messenger stays disconnected.
+     * The negotiate request path. When absent the messenger stays disconnected.
      * @category State
      * @hidden
      */
-    _endpoint = null;
+    _path = null;
     /**
      * The live Web PubSub socket. Held so it can be closed and replaced.
      * @category State
@@ -55,7 +55,7 @@ export class Messenger extends Component {
      * @category Event
      * @hidden
      */
-    _onendpointchange = null;
+    _onpathchange = null;
     _onconnecting = null;
     _onconnected = null;
     _ondisconnected = null;
@@ -88,36 +88,36 @@ export class Messenger extends Component {
         this._connection = connection;
         this.setAttribute(Attributes.CONNECTION, connection);
         // Dispatch
-        const event = { detail: { connection } };
+        const detail = { connection };
         connection === Connection.CONNECTING &&
-            this._dispatchEvent(Event.ON_CONNECTING, event);
+            this._dispatch(Event.ON_CONNECTING, detail);
         connection === Connection.CONNECTED &&
-            this._dispatchEvent(Event.ON_CONNECTED, event);
+            this._dispatch(Event.ON_CONNECTED, detail);
         connection === Connection.DISCONNECTED &&
-            this._dispatchEvent(Event.ON_DISCONNECTED, event);
+            this._dispatch(Event.ON_DISCONNECTED, detail);
     }
     /**
-     * The negotiate endpoint URL. When absent the messenger stays disconnected.
+     * The negotiate request path. When absent the messenger stays disconnected.
      * @category State
      */
-    get endpoint() {
-        return this._endpoint;
+    get path() {
+        return this._path;
     }
-    set endpoint(endpoint) {
+    set path(path) {
         // Normalize
-        endpoint = endpoint ?? null;
+        path = path ?? null;
         // Validate
-        endpoint = endpoint ? Validate.endpoint(endpoint) : null;
+        path = path ? Validate.path(path) : null;
         // Guard
-        if (this._endpoint === endpoint)
+        if (this._path === path)
             return;
         // Mutate
-        this._endpoint = endpoint;
-        endpoint === null
-            ? this.removeAttribute(Attributes.ENDPOINT)
-            : this.setAttribute(Attributes.ENDPOINT, endpoint);
+        this._path = path;
+        path === null
+            ? this.removeAttribute(Attributes.PATH)
+            : this.setAttribute(Attributes.PATH, path);
         // Dispatch
-        this._dispatchEvent(Event.ON_ENDPOINT_CHANGE, { detail: { endpoint } });
+        this._dispatch(Event.ON_PATH_CHANGE, { path });
     }
     /**
      * The session token, read fresh from local storage on every access — never
@@ -129,22 +129,40 @@ export class Messenger extends Component {
         return localStorage.getItem(Session);
     }
     /**
-     * Negotiates a client access URL from the configured endpoint, authenticating
+     * The endpoint host base URL, read fresh from local storage on every access —
+     * never cached — mirroring the session token. Composed with the `path` state
+     * to form the negotiate URL. When absent the messenger stays disconnected.
+     * @category State
+     * @hidden
+     */
+    get _host() {
+        return localStorage.getItem(Endpoint);
+    }
+    /**
+     * Negotiates a client access URL from the configured path, authenticating
      * with the session token, then opens the live connection. No-op when the
-     * endpoint or token is unavailable, or when already connecting or connected.
+     * path or token is unavailable, or when already connecting or connected.
+     * When negotiate fails the connection returns to `disconnected`.
      * @category Operation
      */
     connect = async () => {
         const token = this._token;
         // Gate + guard
-        if (!this.endpoint || !token)
+        if (!this._host || !this.path || !token)
             return;
         if (this._connection !== Connection.DISCONNECTED)
             return;
-        // Establish
+        // Establish — on negotiate failure, recover to disconnected
         this.connection = Connection.CONNECTING;
-        const url = await this._negotiate(token);
-        this._socket = this._open(url);
+        try {
+            const url = await this._negotiate(token);
+            if (this.connection !== Connection.CONNECTING)
+                return;
+            this._socket = this._open(url);
+        }
+        catch {
+            this.connection = Connection.DISCONNECTED;
+        }
     };
     /**
      * Closes the live connection.
@@ -176,16 +194,16 @@ export class Messenger extends Component {
         return true;
     };
     /**
-     * Subscribes to the `onendpointchange` event. Assigning replaces the previous
+     * Subscribes to the `onpathchange` event. Assigning replaces the previous
      * handler; assigning `null` removes it.
      * @category Event
      */
-    set onendpointchange(handler) {
-        this._onendpointchange &&
-            this.removeEventListener(Event.ON_ENDPOINT_CHANGE, this._onendpointchange);
-        this._onendpointchange = handler;
-        this._onendpointchange &&
-            this.addEventListener(Event.ON_ENDPOINT_CHANGE, this._onendpointchange);
+    set onpathchange(handler) {
+        this._onpathchange &&
+            this.removeEventListener(Event.ON_PATH_CHANGE, this._onpathchange);
+        this._onpathchange = handler;
+        this._onpathchange &&
+            this.addEventListener(Event.ON_PATH_CHANGE, this._onpathchange);
     }
     /**
      * Subscribes to the `onconnecting` event. Assigning replaces the previous
@@ -243,7 +261,7 @@ export class Messenger extends Component {
     _attributeHandlers = {
         [Attributes.CONNECTION]: (value) => value !== this._connection &&
             this.setAttribute(Attributes.CONNECTION, this._connection),
-        [Attributes.ENDPOINT]: (value) => (this.endpoint = value),
+        [Attributes.PATH]: (value) => (this.path = value),
     };
     /**
      * Cache element references to improve performance
@@ -273,16 +291,26 @@ export class Messenger extends Component {
      */
     _removeEventListeners = () => { };
     /**
-     * Negotiates a short-lived Web PubSub client access URL from the endpoint,
+     * Called by the disconnectedCallback prototypical method, after
+     * `_removeEventListeners`. Closes the live connection so a removed element
+     * does not keep a socket open.
+     * @category Configuration
+     * @hidden
+     */
+    _dispose = () => this.disconnect();
+    /**
+     * Negotiates a short-lived Web PubSub client access URL from the path,
      * authenticating the request with the session token.
      * @category Operation
      * @hidden
      */
     _negotiate = async (token) => {
-        const response = await fetch(this.endpoint, {
+        const response = await fetch(`${this._host}${this.path}`, {
             headers: { Authorization: `Bearer ${token}` },
         });
         const { url } = await response.json();
+        if (!url)
+            throw new Error("Invalid negotiate response: missing url");
         return url;
     };
     /**
@@ -307,8 +335,8 @@ export class Messenger extends Component {
     _handleMessage = (event) => {
         const message = JSON.parse(event.data);
         message.data?.type === Message.MASTER_DATA_CHANGED &&
-            this._dispatchEvent(Event.ON_MASTERDATACHANGE, {
-                detail: { datetime: new Date().toISOString() },
+            this._dispatch(Event.ON_MASTERDATACHANGE, {
+                datetime: new Date().toISOString(),
             });
     };
 }

package/dist/messenger.meta.d.ts

@@ -11,6 +11,12 @@ export declare const Tag: "app-messenger";
  * @category Configuration
  */
 export declare const Session: "app-license.session";
+/**
+ * Local storage key under which the endpoint host base URL is cached by the
+ * Configurator component. Composed with the `path` state to form the negotiate URL.
+ * @category Configuration
+ */
+export declare const Endpoint: "data";
 /**
  * The Azure Web PubSub subprotocol required for structured group messaging.
  * @category Configuration
@@ -36,7 +42,7 @@ export type Message = (typeof Message)[keyof typeof Message];
  */
 export declare const Attributes: {
     readonly CONNECTION: "connection";
-    readonly ENDPOINT: "endpoint";
+    readonly PATH: "path";
 };
 /**
  * HTML Attributes available to set
@@ -50,7 +56,7 @@ export type Attributes = typeof Attributes;
  */
 export declare const State: {
     readonly CONNECTION: "connection";
-    readonly ENDPOINT: "endpoint";
+    readonly PATH: "path";
 };
 /**
  * HTML Attributes available to set
@@ -73,10 +79,10 @@ export declare const Connection: {
  */
 export type Connection = (typeof Connection)[keyof typeof Connection];
 /**
- * The negotiate endpoint URL value domain
+ * The negotiate request path value domain
  * @category Metadata
  */
-export type Endpoint = string;
+export type Path = string;
 /**
  * @category Metadata
  * @enum
@@ -95,7 +101,7 @@ export type Operation = (typeof Operation)[keyof typeof Operation];
  * @enum
  */
 export declare const Event: {
-    readonly ON_ENDPOINT_CHANGE: "onendpointchange";
+    readonly ON_PATH_CHANGE: "onpathchange";
     readonly ON_CONNECTING: "onconnecting";
     readonly ON_CONNECTED: "onconnected";
     readonly ON_DISCONNECTED: "ondisconnected";

package/dist/messenger.meta.js

@@ -11,6 +11,12 @@ export const Tag = "app-messenger";
  * @category Configuration
  */
 export const Session = "app-license.session";
+/**
+ * Local storage key under which the endpoint host base URL is cached by the
+ * Configurator component. Composed with the `path` state to form the negotiate URL.
+ * @category Configuration
+ */
+export const Endpoint = "data";
 /**
  * The Azure Web PubSub subprotocol required for structured group messaging.
  * @category Configuration
@@ -31,7 +37,7 @@ export const Message = {
  */
 export const Attributes = {
     CONNECTION: "connection",
-    ENDPOINT: "endpoint",
+    PATH: "path",
 };
 /**
  * HTML Attributes available to set
@@ -65,7 +71,7 @@ export const Operation = {
  * @enum
  */
 export const Event = {
-    ON_ENDPOINT_CHANGE: "onendpointchange",
+    ON_PATH_CHANGE: "onpathchange",
     ON_CONNECTING: "onconnecting",
     ON_CONNECTED: "onconnected",
     ON_DISCONNECTED: "ondisconnected",

package/dist/messenger.validation.d.ts

@@ -1,15 +1,15 @@
 /**
  * @module Component
  */
-import { type Endpoint } from "./messenger.meta.js";
+import { type Path } from "./messenger.meta.js";
 /**
  * Runtime enforcement of declared value domains.
  * @category Validation
  */
 export declare class Validate {
     /**
-     * Validates the negotiate endpoint URL value domain.
+     * Validates the negotiate request path value domain.
      * @category Validation
      */
-    static endpoint: (value: string) => Endpoint;
+    static path: (value: string) => Path;
 }

package/dist/messenger.validation.js

@@ -7,15 +7,12 @@
  */
 export class Validate {
     /**
-     * Validates the negotiate endpoint URL value domain.
+     * Validates the negotiate request path value domain.
      * @category Validation
      */
-    static endpoint = (value) => {
-        try {
-            new URL(value);
-        }
-        catch {
-            throw new Error(`Invalid endpoint value: ${value}`);
+    static path = (value) => {
+        if (!value.startsWith("/")) {
+            throw new Error(`Invalid path value: ${value}`);
         }
         return value;
     };

package/package.json

@@ -1,12 +1,17 @@
 {
   "name": "@effect.healthcare/messenger",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "description": "Azure Pub Sub Messenger Web Component",
   "keywords": [
     "web component"
   ],
+  "files": [
+    "dist",
+    "!dist/.gitkeep"
+  ],
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     }
   },
@@ -50,6 +55,6 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@scalable.software/component": "^0.3.0"
+    "@scalable.software/component": "^0.5.0"
   }
 }

package/.claude/CLAUDE.md

@@ -1,88 +0,0 @@
-# Web Component
-
-A web component built on the `@scalable.software/component` framework. The policies in `.claude/context/` govern how component specifications are transformed into solid implementations.
-
-## How This Project Works
-
-Every component is developed through a specification-driven, test-first pipeline. The specification declares the public contract; the implementation honors it; the tests verify it; the commit history records the transformation.
-
-When working on a component, translate the specification into an implementation that conforms to all applicable policies — without inventing structure, behavior, or vocabulary the specification does not declare.
-
-## Translation Pipeline
-
-```
-<component>.specifications.json     ← source of truth
-        │
-        ├─→ <component>.meta.ts            vocabulary + value-domain types
-        ├─→ <component>.validation.ts      Validate class — runtime enforcement
-        ├─→ <component>.ts                 state, operations, events, gestures
-        ├─→ <component>.template.html      realized composition
-        └─→ <component>.style.css          realized presentation
-
-verified by:
-        test/unit/<component>.meta.test.ts        — vocabulary tests
-        test/unit/<component>.validation.test.ts  — validator tests
-        test/unit/<component>.test.ts             — component behavioral tests
-
-recorded by:
-        FAIL/PASS commit pairs, policy-ordered, one prefix per commit
-        DOCUMENTATION → FEATURE closes each feature branch
-```
-
-Names predictably transform across layers. A state named `visibility` in the specification becomes `Attributes.VISIBILITY` + `State.VISIBILITY` in metadata, `Validate.visibility` in validation, `get visibility()`/`set visibility(...)` on the class, `state(State.VISIBILITY, ...)` in tests, and `STATE: ...` in commits.
-
-## Implementation Order
-
-Within any behavioral feature, work proceeds top-down through the policy hierarchy:
-
-```
-COMPOSITION → STATE → VALIDATION → OPERATION → EVENT → STYLE → GESTURE → DOCUMENTATION → FEATURE
-```
-
-Each layer depends on the layers above. CSS-only features collapse to `STYLE → FEATURE`. See `@context/workflow.md` for the full sequence and per-layer commit format.
-
-## Implementation Policies
-
-Each policy file opens with a **How to Read This Policy** rubric that classifies its rules as one of three strengths:
-
-- **Principles** — non-negotiable; derived from framework correctness or TDD discipline.
-- **Templates** — invariant skeletons with explicit variation points based on declared classification (e.g., attribute-backed vs non-attribute, readonly vs writable, payload-bearing vs payload-free).
-- **Conventions** — canonical defaults that keep implementations readable across components.
-
-When a new component's shape conflicts with a rule, classify the rule before reconciling: a principle conflict is a defect; a template conflict means a variation point needs to be made explicit; a convention conflict is a documented deviation.
-
-### Specification-driven (per component)
-
-@context/composition.md — structural parts and cached references
-@context/data.md — canonical component-owned content
-@context/state.md — runtime mode, visibility, status, persistence
-@context/operation.md — public imperative actions
-@context/event.md — observable semantic outcomes
-@context/gesture.md — interaction inputs
-@context/validation.md — runtime enforcement of declared value domains
-
-### Cross-cutting (every component)
-
-@context/testing.md — test file structure, BDD vocabulary, coverage contracts
-@context/workflow.md — branching, commit sequencing, TDD discipline
-
-## Working Principles
-
-- **Test first.** Every behavioral change starts with a failing test. The FAIL commit precedes the PASS commit. No exceptions.
-- **One feature per branch.** Behavioral work is never committed directly to main.
-- **One concern per commit.** Every commit message begins with a canonical prefix.
-- **Trace names across layers.** A specification name reappears unchanged — modulo standard transformations — in metadata, validation, class API, tests, and commits.
-- **Specification is authoritative.** Implementations do not invent structure, behavior, or vocabulary the specification does not declare. If a component's shape does not fit a policy rule, examine the policy's variation points — do not bypass them.
-
-## Running the Demo in a Browser (chrome-devtools MCP)
-
-For advanced testing or debugging, the live web component can be served and driven through the `chrome-devtools` MCP. This gives access to the rendered component, its shadow DOM, the console, and DOM manipulation.
-
-1. **Start the dev server** — `npm run serve`. The `preserve` hook builds first (`src/` → `dist/`), and `web-dev-server.config.mjs` is auto-loaded (`rootDir: "."`, `port: 8000`, `watch: true`). Run it in the background. The server serves the repo root because the demo loads `../importmap` and `./dist` via the import map.
-2. **Navigate the controlled browser** — `mcp__chrome-devtools__navigate_page` to `http://localhost:8000/demo/index.html`. Always use the explicit `/demo/index.html` path; the demo uses relative asset paths and will not resolve at `/`.
-3. **Verify** — `mcp__chrome-devtools__evaluate_script` to inspect the component (e.g. `customElements.get("app-messenger")` is defined; the base framework exposes the shadow root as `el.root`); `mcp__chrome-devtools__list_console_messages` to check for errors.
-4. **Clean up when done** — navigate the page to `about:blank` (the MCP keeps one page alive, so the last page cannot be closed), then stop the dev server process on port 8000.
-
-Notes:
-- MCP tool schemas must be loaded via `ToolSearch` (`select:<name>`) before first use each session.
-- If a stale server already holds port 8000, the new one fails to bind — kill the straggler rather than letting it drift to another port.