@pie-players/pie-context 0.1.1

package/README.md

@@ -0,0 +1,59 @@
+# @pie-players/pie-context
+
+Framework-agnostic Context Protocol helpers for PIE web components.
+
+This package implements the Web Components community `context-request` protocol
+so orchestration/runtime dependencies can be shared without prop drilling.
+
+## Included APIs
+
+- `createContext<T>(key)` for typed context keys
+- `ContextRequestEvent` and `ContextProviderEvent`
+- `ContextProvider` and `provideContext(...)`
+- `ContextConsumer`, `consumeContext(...)`, and `requestContext(...)`
+- `ContextRoot` for late-provider replay of pending subscribing requests
+
+## Design notes
+
+- Events are emitted with `bubbles: true` and `composed: true`.
+- Provider matching uses strict key identity (`===`).
+- `ContextRequestEvent.subscribe` defaults to `false` (one-shot request).
+- Providers call `stopPropagation()` when they satisfy a matching request.
+- Providers re-dispatch existing subscriptions when a nested provider for the
+  same context announces itself.
+- Subscriptions are opt-in (`subscribe: true`) and include unsubscribe callbacks.
+- `ContextRoot` only tracks subscribing requests to avoid unnecessary retention.
+- `ContextRoot` dedupes pending replay by `(requestor, callback)` pair.
+
+See `LIT_PARITY_CHECKLIST.md` for the parity checklist used to align semantics
+with `../lit/packages/context` core APIs.
+
+## Svelte usage pattern
+
+Keep Svelte reactivity for internal state and use this package for ambient
+runtime dependencies between components:
+
+```ts
+import { onMount } from "svelte";
+import { ContextConsumer, createContext } from "@pie-players/pie-context";
+
+const toolkitContext = createContext<{ assessmentId: string }>(
+  Symbol("toolkit-runtime"),
+);
+
+let host: HTMLElement;
+let assessmentId = "";
+let consumer: ContextConsumer<typeof toolkitContext>;
+
+onMount(() => {
+  consumer = new ContextConsumer(host, {
+    context: toolkitContext,
+    subscribe: true,
+    onValue: (value) => {
+      assessmentId = value.assessmentId;
+    },
+  });
+  consumer.connect();
+  return () => consumer.disconnect();
+});
+```

package/dist/consumer.d.ts

@@ -0,0 +1,24 @@
+import type { ContextType, UnknownContext } from "./types.js";
+export interface ContextConsumerOptions<T extends UnknownContext> {
+    context: T;
+    subscribe?: boolean;
+    onValue?: (value: ContextType<T>) => void;
+}
+export declare class ContextConsumer<T extends UnknownContext> {
+    private readonly host;
+    private readonly context;
+    private readonly subscribe;
+    private readonly onValue?;
+    private isConnected;
+    private unsubscribe?;
+    private currentValue?;
+    constructor(host: Element, options: ContextConsumerOptions<T>);
+    connect(): void;
+    disconnect(): void;
+    get value(): ContextType<T> | undefined;
+    private readonly handleValue;
+    requestValue(): void;
+}
+export declare const consumeContext: <T extends UnknownContext>(host: Element, options: ContextConsumerOptions<T>) => ContextConsumer<T>;
+export declare const requestContext: <T extends UnknownContext>(host: Element, context: T) => ContextType<T> | undefined;
+//# sourceMappingURL=consumer.d.ts.map

package/dist/consumer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumer.d.ts","sourceRoot":"","sources":["../src/consumer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE9D,MAAM,WAAW,sBAAsB,CAAC,CAAC,SAAS,cAAc;IAC/D,OAAO,EAAE,CAAC,CAAC;IACX,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;CAC1C;AAED,qBAAa,eAAe,CAAC,CAAC,SAAS,cAAc;IACpD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAU;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAI;IAC5B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAU;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAkC;IAC3D,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,WAAW,CAAC,CAAa;IACjC,OAAO,CAAC,YAAY,CAAC,CAAiB;gBAEnB,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC;IAO7D,OAAO,IAAI,IAAI;IAMf,UAAU,IAAI,IAAI;IAOzB,IAAW,KAAK,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG,SAAS,CAE7C;IAED,OAAO,CAAC,QAAQ,CAAC,WAAW,CAc1B;IAEK,YAAY,IAAI,IAAI;CAU3B;AAED,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,cAAc,EACtD,MAAM,OAAO,EACb,SAAS,sBAAsB,CAAC,CAAC,CAAC,KAChC,eAAe,CAAC,CAAC,CAAuC,CAAC;AAE5D,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,cAAc,EACtD,MAAM,OAAO,EACb,SAAS,CAAC,KACR,WAAW,CAAC,CAAC,CAAC,GAAG,SAanB,CAAC"}

package/dist/consumer.js

@@ -0,0 +1,56 @@
+import { ContextRequestEvent } from "./events.js";
+export class ContextConsumer {
+    host;
+    context;
+    subscribe;
+    onValue;
+    isConnected = false;
+    unsubscribe;
+    currentValue;
+    constructor(host, options) {
+        this.host = host;
+        this.context = options.context;
+        this.subscribe = options.subscribe ?? true;
+        this.onValue = options.onValue;
+    }
+    connect() {
+        if (this.isConnected)
+            return;
+        this.isConnected = true;
+        this.requestValue();
+    }
+    disconnect() {
+        if (!this.isConnected)
+            return;
+        this.isConnected = false;
+        this.unsubscribe?.();
+        this.unsubscribe = undefined;
+    }
+    get value() {
+        return this.currentValue;
+    }
+    handleValue = (value, unsubscribe) => {
+        if (unsubscribe !== this.unsubscribe) {
+            this.unsubscribe?.();
+            this.unsubscribe = unsubscribe;
+        }
+        if (!this.subscribe && this.unsubscribe) {
+            this.unsubscribe();
+            this.unsubscribe = undefined;
+        }
+        this.currentValue = value;
+        this.onValue?.(value);
+    };
+    requestValue() {
+        this.host.dispatchEvent(new ContextRequestEvent(this.context, this.host, this.handleValue, this.subscribe));
+    }
+}
+export const consumeContext = (host, options) => new ContextConsumer(host, options);
+export const requestContext = (host, context) => {
+    let value;
+    host.dispatchEvent(new ContextRequestEvent(context, host, (nextValue) => {
+        value = nextValue;
+    }, false));
+    return value;
+};
+//# sourceMappingURL=consumer.js.map

package/dist/consumer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumer.js","sourceRoot":"","sources":["../src/consumer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AASlD,MAAM,OAAO,eAAe;IACV,IAAI,CAAU;IACd,OAAO,CAAI;IACX,SAAS,CAAU;IACnB,OAAO,CAAmC;IACnD,WAAW,GAAG,KAAK,CAAC;IACpB,WAAW,CAAc;IACzB,YAAY,CAAkB;IAEtC,YAAmB,IAAa,EAAE,OAAkC;QACnE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC;QAC3C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAChC,CAAC;IAEM,OAAO;QACb,IAAI,IAAI,CAAC,WAAW;YAAE,OAAO;QAC7B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QACxB,IAAI,CAAC,YAAY,EAAE,CAAC;IACrB,CAAC;IAEM,UAAU;QAChB,IAAI,CAAC,IAAI,CAAC,WAAW;YAAE,OAAO;QAC9B,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;QACzB,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;QACrB,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;IAC9B,CAAC;IAED,IAAW,KAAK;QACf,OAAO,IAAI,CAAC,YAAY,CAAC;IAC1B,CAAC;IAEgB,WAAW,GAAG,CAC9B,KAAqB,EACrB,WAAwB,EACjB,EAAE;QACT,IAAI,WAAW,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC;YACtC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;YACrB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAChC,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACzC,IAAI,CAAC,WAAW,EAAE,CAAC;YACnB,IAAI,CAAC,WAAW,GAAG,SAAS,CAAC;QAC9B,CAAC;QACD,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC;QAC1B,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC,CAAC;IAEK,YAAY;QAClB,IAAI,CAAC,IAAI,CAAC,aAAa,CACtB,IAAI,mBAAmB,CACtB,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,IAAI,EACT,IAAI,CAAC,WAAW,EAChB,IAAI,CAAC,SAAS,CACd,CACD,CAAC;IACH,CAAC;CACD;AAED,MAAM,CAAC,MAAM,cAAc,GAAG,CAC7B,IAAa,EACb,OAAkC,EACb,EAAE,CAAC,IAAI,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAE5D,MAAM,CAAC,MAAM,cAAc,GAAG,CAC7B,IAAa,EACb,OAAU,EACmB,EAAE;IAC/B,IAAI,KAAiC,CAAC;IACtC,IAAI,CAAC,aAAa,CACjB,IAAI,mBAAmB,CACtB,OAAO,EACP,IAAI,EACJ,CAAC,SAAS,EAAE,EAAE;QACb,KAAK,GAAG,SAAS,CAAC;IACnB,CAAC,EACD,KAAK,CACL,CACD,CAAC;IACF,OAAO,KAAK,CAAC;AACd,CAAC,CAAC"}

package/dist/events.d.ts

@@ -0,0 +1,20 @@
+import type { ContextCallback, ContextType, UnknownContext } from "./types.js";
+export declare class ContextRequestEvent<T extends UnknownContext = UnknownContext> extends Event {
+    readonly context: T;
+    readonly contextTarget: Element;
+    readonly callback: ContextCallback<ContextType<T>>;
+    readonly subscribe?: boolean;
+    constructor(context: T, contextTarget: Element, callback: ContextCallback<ContextType<T>>, subscribe?: boolean);
+}
+export declare class ContextProviderEvent<T extends UnknownContext = UnknownContext> extends Event {
+    readonly context: T;
+    readonly contextTarget: Element;
+    constructor(context: T, contextTarget: Element);
+}
+declare global {
+    interface HTMLElementEventMap {
+        "context-request": ContextRequestEvent<UnknownContext>;
+        "context-provider": ContextProviderEvent<UnknownContext>;
+    }
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,eAAe,EACf,WAAW,EACX,cAAc,EACd,MAAM,YAAY,CAAC;AAEpB,qBAAa,mBAAmB,CAC/B,CAAC,SAAS,cAAc,GAAG,cAAc,CACxC,SAAQ,KAAK;IACd,SAAgB,OAAO,EAAE,CAAC,CAAC;IAC3B,SAAgB,aAAa,EAAE,OAAO,CAAC;IACvC,SAAgB,QAAQ,EAAE,eAAe,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1D,SAAgB,SAAS,CAAC,EAAE,OAAO,CAAC;gBAGnC,OAAO,EAAE,CAAC,EACV,aAAa,EAAE,OAAO,EACtB,QAAQ,EAAE,eAAe,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EACzC,SAAS,CAAC,EAAE,OAAO;CAQpB;AAED,qBAAa,oBAAoB,CAChC,CAAC,SAAS,cAAc,GAAG,cAAc,CACxC,SAAQ,KAAK;IACd,SAAgB,OAAO,EAAE,CAAC,CAAC;IAC3B,SAAgB,aAAa,EAAE,OAAO,CAAC;gBAEpB,OAAO,EAAE,CAAC,EAAE,aAAa,EAAE,OAAO;CAKrD;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,mBAAmB;QAC5B,iBAAiB,EAAE,mBAAmB,CAAC,cAAc,CAAC,CAAC;QACvD,kBAAkB,EAAE,oBAAoB,CAAC,cAAc,CAAC,CAAC;KACzD;CACD"}

package/dist/events.js

@@ -0,0 +1,23 @@
+export class ContextRequestEvent extends Event {
+    context;
+    contextTarget;
+    callback;
+    subscribe;
+    constructor(context, contextTarget, callback, subscribe) {
+        super("context-request", { bubbles: true, composed: true });
+        this.context = context;
+        this.contextTarget = contextTarget;
+        this.callback = callback;
+        this.subscribe = subscribe ?? false;
+    }
+}
+export class ContextProviderEvent extends Event {
+    context;
+    contextTarget;
+    constructor(context, contextTarget) {
+        super("context-provider", { bubbles: true, composed: true });
+        this.context = context;
+        this.contextTarget = contextTarget;
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAMA,MAAM,OAAO,mBAEX,SAAQ,KAAK;IACE,OAAO,CAAI;IACX,aAAa,CAAU;IACvB,QAAQ,CAAkC;IAC1C,SAAS,CAAW;IAEpC,YACC,OAAU,EACV,aAAsB,EACtB,QAAyC,EACzC,SAAmB;QAEnB,KAAK,CAAC,iBAAiB,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,SAAS,GAAG,SAAS,IAAI,KAAK,CAAC;IACrC,CAAC;CACD;AAED,MAAM,OAAO,oBAEX,SAAQ,KAAK;IACE,OAAO,CAAI;IACX,aAAa,CAAU;IAEvC,YAAmB,OAAU,EAAE,aAAsB;QACpD,KAAK,CAAC,kBAAkB,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7D,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACpC,CAAC;CACD"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { ContextProviderEvent, ContextRequestEvent, } from "./events.js";
+export { consumeContext, ContextConsumer, requestContext, } from "./consumer.js";
+export { provideContext, ContextProvider } from "./provider.js";
+export { ContextRoot } from "./root.js";
+export type { Context, ContextCallback, ContextType, UnknownContext, } from "./types.js";
+export { createContext } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,oBAAoB,EACpB,mBAAmB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,cAAc,EACd,eAAe,EACf,cAAc,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,YAAY,EACX,OAAO,EACP,eAAe,EACf,WAAW,EACX,cAAc,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { ContextProviderEvent, ContextRequestEvent, } from "./events.js";
+export { consumeContext, ContextConsumer, requestContext, } from "./consumer.js";
+export { provideContext, ContextProvider } from "./provider.js";
+export { ContextRoot } from "./root.js";
+export { createContext } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,oBAAoB,EACpB,mBAAmB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,cAAc,EACd,eAAe,EACf,cAAc,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAOxC,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}

package/dist/provider.d.ts

@@ -0,0 +1,23 @@
+import type { ContextType, UnknownContext } from "./types.js";
+export interface ContextProviderOptions<T extends UnknownContext> {
+    context: T;
+    initialValue: ContextType<T>;
+}
+export declare class ContextProvider<T extends UnknownContext> {
+    private readonly host;
+    private readonly context;
+    private currentValue;
+    private readonly subscriptions;
+    private isConnected;
+    constructor(host: Element, options: ContextProviderOptions<T>);
+    connect(): void;
+    disconnect(): void;
+    setValue(value: ContextType<T>, force?: boolean): void;
+    get value(): ContextType<T>;
+    private getContextTarget;
+    private readonly handleContextRequest;
+    private readonly handleContextProvider;
+    private notifySubscribers;
+}
+export declare const provideContext: <T extends UnknownContext>(host: Element, options: ContextProviderOptions<T>) => ContextProvider<T>;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAQ9D,MAAM,WAAW,sBAAsB,CAAC,CAAC,SAAS,cAAc;IAC/D,OAAO,EAAE,CAAC,CAAC;IACX,YAAY,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;CAC7B;AAED,qBAAa,eAAe,CAAC,CAAC,SAAS,cAAc;IACpD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAU;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAI;IAC5B,OAAO,CAAC,YAAY,CAAiB;IACrC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAG1B;IACJ,OAAO,CAAC,WAAW,CAAS;gBAET,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC;IAM7D,OAAO,IAAI,IAAI;IAcf,UAAU,IAAI,IAAI;IAclB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,KAAK,UAAQ,GAAG,IAAI;IAM3D,IAAW,KAAK,IAAI,WAAW,CAAC,CAAC,CAAC,CAEjC;IAED,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CA0BnC;IAEF,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAepC;IAEF,OAAO,CAAC,iBAAiB;CAKzB;AAED,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,cAAc,EACtD,MAAM,OAAO,EACb,SAAS,sBAAsB,CAAC,CAAC,CAAC,KAChC,eAAe,CAAC,CAAC,CAAuC,CAAC"}

package/dist/provider.js

@@ -0,0 +1,93 @@
+import { ContextProviderEvent, ContextRequestEvent } from "./events.js";
+export class ContextProvider {
+    host;
+    context;
+    currentValue;
+    subscriptions = new Map();
+    isConnected = false;
+    constructor(host, options) {
+        this.host = host;
+        this.context = options.context;
+        this.currentValue = options.initialValue;
+    }
+    connect() {
+        if (this.isConnected)
+            return;
+        this.isConnected = true;
+        this.host.addEventListener("context-request", this.handleContextRequest);
+        this.host.addEventListener("context-provider", this.handleContextProvider);
+        this.host.dispatchEvent(new ContextProviderEvent(this.context, this.host));
+    }
+    disconnect() {
+        if (!this.isConnected)
+            return;
+        this.isConnected = false;
+        this.host.removeEventListener("context-request", this.handleContextRequest);
+        this.host.removeEventListener("context-provider", this.handleContextProvider);
+        this.subscriptions.clear();
+    }
+    setValue(value, force = false) {
+        if (!force && Object.is(this.currentValue, value))
+            return;
+        this.currentValue = value;
+        this.notifySubscribers();
+    }
+    get value() {
+        return this.currentValue;
+    }
+    getContextTarget(event, fallback) {
+        if ("contextTarget" in event && event.contextTarget) {
+            return event.contextTarget;
+        }
+        const path = typeof event.composedPath === "function" ? event.composedPath() : [];
+        const firstPathTarget = path[0];
+        return firstPathTarget ? firstPathTarget : fallback;
+    }
+    handleContextRequest = (event) => {
+        if (event.context !== this.context)
+            return;
+        const consumerHost = this.getContextTarget(event, this.host);
+        if (consumerHost === this.host)
+            return;
+        // Closest provider wins for this context key.
+        event.stopPropagation();
+        if (!event.subscribe) {
+            event.callback(this.currentValue);
+            return;
+        }
+        const existing = this.subscriptions.get(event.callback);
+        existing?.unsubscribe();
+        const unsubscribe = () => {
+            this.subscriptions.delete(event.callback);
+        };
+        this.subscriptions.set(event.callback, {
+            consumerHost,
+            callback: event.callback,
+            unsubscribe,
+        });
+        event.callback(this.currentValue, unsubscribe);
+    };
+    handleContextProvider = (event) => {
+        if (event.context !== this.context)
+            return;
+        const providerHost = this.getContextTarget(event, this.host);
+        if (providerHost === this.host)
+            return;
+        // A newly connected nested provider should take over matching consumers.
+        const seen = new Set();
+        for (const [callback, { consumerHost }] of this.subscriptions) {
+            if (seen.has(callback))
+                continue;
+            seen.add(callback);
+            consumerHost.dispatchEvent(new ContextRequestEvent(this.context, consumerHost, callback, true));
+        }
+        event.stopPropagation();
+    };
+    notifySubscribers() {
+        for (const subscription of this.subscriptions.values()) {
+            subscription.callback(this.currentValue, subscription.unsubscribe);
+        }
+    }
+}
+export const provideContext = (host, options) => new ContextProvider(host, options);
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

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

package/dist/root.d.ts

@@ -0,0 +1,11 @@
+export declare class ContextRoot {
+    private readonly host;
+    private readonly pendingByContext;
+    private attached;
+    constructor(host: Element);
+    attach(): void;
+    detach(): void;
+    private readonly onContextRequest;
+    private readonly onContextProvider;
+}
+//# sourceMappingURL=root.d.ts.map

package/dist/root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root.d.ts","sourceRoot":"","sources":["../src/root.ts"],"names":[],"mappings":"AA4BA,qBAAa,WAAW;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAU;IAC/B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA6C;IAC9E,OAAO,CAAC,QAAQ,CAAS;gBAEN,IAAI,EAAE,OAAO;IAIzB,MAAM,IAAI,IAAI;IAad,MAAM,IAAI,IAAI;IAcrB,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CA2B/B;IAEF,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAahC;CACF"}

package/dist/root.js

@@ -0,0 +1,74 @@
+import { ContextRequestEvent, } from "./events.js";
+const getLivePending = (pending) => {
+    const requests = [];
+    for (const entry of pending) {
+        if (entry.requestorRef.deref() && entry.callbackRef.deref()) {
+            requests.push(entry);
+        }
+    }
+    return requests;
+};
+export class ContextRoot {
+    host;
+    pendingByContext = new Map();
+    attached = false;
+    constructor(host) {
+        this.host = host;
+    }
+    attach() {
+        if (this.attached)
+            return;
+        this.attached = true;
+        this.host.addEventListener("context-request", this.onContextRequest);
+        this.host.addEventListener("context-provider", this.onContextProvider);
+    }
+    detach() {
+        if (!this.attached)
+            return;
+        this.attached = false;
+        this.host.removeEventListener("context-request", this.onContextRequest);
+        this.host.removeEventListener("context-provider", this.onContextProvider);
+        this.pendingByContext.clear();
+    }
+    onContextRequest = (event) => {
+        if (!event.subscribe)
+            return;
+        let pending = this.pendingByContext.get(event.context);
+        if (!pending) {
+            pending = {
+                callbacks: new WeakMap(),
+                requests: [],
+            };
+            this.pendingByContext.set(event.context, pending);
+        }
+        const requestor = event.contextTarget;
+        const callback = event.callback;
+        let seenForRequestor = pending.callbacks.get(requestor);
+        if (!seenForRequestor) {
+            seenForRequestor = new WeakSet();
+            pending.callbacks.set(requestor, seenForRequestor);
+        }
+        if (seenForRequestor.has(callback))
+            return;
+        seenForRequestor.add(callback);
+        pending.requests.push({
+            requestorRef: new WeakRef(requestor),
+            callbackRef: new WeakRef(callback),
+        });
+        pending.requests = getLivePending(pending.requests);
+    };
+    onContextProvider = (event) => {
+        const pending = this.pendingByContext.get(event.context);
+        if (!pending || pending.requests.length === 0)
+            return;
+        this.pendingByContext.delete(event.context);
+        for (const entry of pending.requests) {
+            const requestor = entry.requestorRef.deref();
+            const callback = entry.callbackRef.deref();
+            if (!requestor || !callback)
+                continue;
+            requestor.dispatchEvent(new ContextRequestEvent(event.context, requestor, callback, true));
+        }
+    };
+}
+//# sourceMappingURL=root.js.map

package/dist/root.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,8 @@
+export type Context<KeyType, ValueType> = KeyType & {
+    __context__: ValueType;
+};
+export type UnknownContext = Context<unknown, unknown>;
+export type ContextType<T extends UnknownContext> = T extends Context<infer _K, infer V> ? V : never;
+export type ContextCallback<ValueType> = (value: ValueType, unsubscribe?: () => void) => void;
+export declare const createContext: <ValueType, KeyType = unknown>(key: KeyType) => Context<KeyType, ValueType>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,OAAO,CAAC,OAAO,EAAE,SAAS,IAAI,OAAO,GAAG;IAAE,WAAW,EAAE,SAAS,CAAA;CAAE,CAAC;AAE/E,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAEvD,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,cAAc,IAC/C,CAAC,SAAS,OAAO,CAAC,MAAM,EAAE,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAElD,MAAM,MAAM,eAAe,CAAC,SAAS,IAAI,CACxC,KAAK,EAAE,SAAS,EAChB,WAAW,CAAC,EAAE,MAAM,IAAI,KACpB,IAAI,CAAC;AAEV,eAAO,MAAM,aAAa,GAAI,SAAS,EAAE,OAAO,GAAG,OAAO,EAAE,KAAK,OAAO,KAChE,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export const createContext = (key) => key;
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAYA,MAAM,CAAC,MAAM,aAAa,GAAG,CAA+B,GAAY,EAAE,EAAE,CAC3E,GAAkC,CAAC"}

package/package.json

@@ -0,0 +1,46 @@
+{
+	"name": "@pie-players/pie-context",
+	"version": "0.1.1",
+	"type": "module",
+	"description": "Framework-agnostic Context Protocol helpers for PIE web components",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/pie-framework/pie-players.git",
+		"directory": "packages/pie-context"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"license": "MIT",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"scripts": {
+		"build": "tsc -p tsconfig.json",
+		"dev": "tsc -p tsconfig.json --watch",
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"lint": "biome check .",
+		"test": "bun test"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.10",
+		"typescript": "^5.9.3"
+	},
+	"homepage": "https://github.com/pie-framework/pie-players/tree/master/packages/pie-context#readme",
+	"bugs": {
+		"url": "https://github.com/pie-framework/pie-players/issues"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"sideEffects": false
+}