@oatscenter/trellis-svelte 0.100.0-rc.1

package/README.md

@@ -0,0 +1,16 @@
+# @oatscenter/trellis-svelte
+
+Svelte integration for Trellis browser applications.
+
+Provides `TrellisProvider` for app-level wiring and `createTrellisApp(...)` for
+app-scoped typed Svelte context around the real connected Trellis client.
+
+Use `TrellisProvider` as the primary integration surface:
+
+- create an app context with `createTrellisApp({ contract, trellisUrl })`
+- pass `trellisApp` to `TrellisProvider`
+- read the live client synchronously with `app.getTrellis()` from child
+  components
+
+Uses the contract/runtime model from `@oatscenter/trellis/contracts` and
+`@oatscenter/trellis`.

package/dist/authorization_context.d.ts

@@ -0,0 +1,18 @@
+import { type AuthorizationContextBundle, type AuthorizationRoutingMaterial, type TrellisAuth, type VerifiedAuthorizationContext } from "@oatscenter/trellis/auth";
+export type AuthorizationContextStatus = "empty" | "loading" | "ready" | "refreshing" | "degraded" | "expired" | "authRequired" | "failed";
+/** Reactive projection of the shared TypeScript authorization context cache. */
+export declare class AuthorizationContextController {
+    #private;
+    constructor(trellisUrl: string, fetch?: typeof globalThis.fetch);
+    get context(): VerifiedAuthorizationContext | undefined;
+    get status(): AuthorizationContextStatus;
+    get error(): unknown;
+    get refreshAt(): number | undefined;
+    get expiresAt(): number | undefined;
+    install(bundle: AuthorizationContextBundle, routing: AuthorizationRoutingMaterial): Promise<void>;
+    refresh(sessionId: string, auth: TrellisAuth): Promise<void>;
+    refreshNow(sessionId: string, auth: TrellisAuth): Promise<void>;
+    start(sessionId: string, auth: TrellisAuth): void;
+    stop(): void;
+    clear(): Promise<void>;
+}

package/dist/authorization_context.js

@@ -0,0 +1,150 @@
+/* authorization_context.js generated by Svelte v5.55.5 */
+import * as $ from 'svelte/internal/client';
+
+import {
+	AuthorizationContextCache,
+	AuthorizationContextRefreshError,
+	refreshAuthorizationContext,
+	startAuthorizationContextRefresh
+} from "@oatscenter/trellis/auth";
+
+export class AuthorizationContextController {
+	#cache;
+	#context = $.state();
+	#status = $.state("empty");
+	#error = $.state();
+	#stop;
+	#epoch = 0;
+
+	constructor(trellisUrl, fetch) {
+		this.#cache = new AuthorizationContextCache(trellisUrl, fetch);
+	}
+
+	get context() {
+		return $.get(this.#context);
+	}
+
+	get status() {
+		return $.get(this.#status);
+	}
+
+	get error() {
+		return $.get(this.#error);
+	}
+
+	get refreshAt() {
+		return $.get(this.#context)?.refreshAt;
+	}
+
+	get expiresAt() {
+		return $.get(this.#context)?.context.expiresAt;
+	}
+
+	async install(bundle, routing) {
+		$.set(this.#status, "loading");
+		$.set(this.#error, undefined);
+
+		try {
+			$.set(this.#context, await this.#cache.install(bundle, routing));
+			$.set(this.#status, "ready");
+		} catch(error) {
+			$.set(this.#status, "failed");
+			$.set(this.#error, error);
+
+			throw error;
+		}
+	}
+
+	async refresh(sessionId, auth) {
+		const epoch = this.#epoch;
+		const clearGuard = this.#cache.clearGuard();
+
+		$.set(this.#status, "refreshing");
+
+		try {
+			$.set(this.#context, await refreshAuthorizationContext({
+				trellisUrl: this.#cache.trellisUrl,
+				sessionId,
+				auth,
+				cache: this.#cache,
+				shouldInstall: () => epoch === this.#epoch
+			}));
+
+			$.set(this.#status, "ready");
+			$.set(this.#error, undefined);
+		} catch(error) {
+			if (epoch !== this.#epoch) return;
+
+			if (error instanceof AuthorizationContextRefreshError && error.terminal) {
+				if (!await this.#cache.clearIfCurrent(clearGuard)) {
+					$.set(this.#context, this.#cache.current());
+					$.set(this.#status, "ready");
+					$.set(this.#error, undefined);
+
+					return;
+				}
+
+				$.set(this.#context, undefined);
+			}
+
+			$.set(
+				this.#status,
+				error instanceof AuthorizationContextRefreshError && error.terminal
+					? "authRequired"
+					: $.get(this.#context)?.context.expiresAt !== undefined && $.get(this.#context).context.expiresAt <= this.#cache.correctedNowSeconds() ? "expired" : "degraded",
+				true
+			);
+
+			$.set(this.#error, error);
+
+			throw error;
+		}
+	}
+
+	async refreshNow(sessionId, auth) {
+		await this.refresh(sessionId, auth);
+	}
+
+	start(sessionId, auth) {
+		this.stop();
+
+		if (!$.get(this.#context)) $.set(this.#status, "refreshing");
+
+		this.#stop = startAuthorizationContextRefresh({
+			trellisUrl: this.#cache.trellisUrl,
+			sessionId,
+			auth,
+			cache: this.#cache,
+			onRefresh: (context) => {
+				$.set(this.#context, context);
+				$.set(this.#status, "ready");
+				$.set(this.#error, undefined);
+			},
+
+			onTerminalFailure: (error) => {
+				$.set(this.#context, undefined);
+				$.set(this.#status, "authRequired");
+				$.set(this.#error, error);
+			},
+
+			onTransientFailure: (error) => {
+				$.set(this.#status, "degraded");
+				$.set(this.#error, error);
+			}
+		});
+	}
+
+	stop() {
+		this.#stop?.();
+		this.#stop = undefined;
+	}
+
+	async clear() {
+		this.#epoch += 1;
+		this.stop();
+		await this.#cache.clear();
+		$.set(this.#context, undefined);
+		$.set(this.#status, "empty");
+		$.set(this.#error, undefined);
+	}
+}

package/dist/components/TrellisContextProvider.svelte

@@ -0,0 +1,24 @@
+<script lang="ts">
+  import type { Snippet } from "svelte";
+  import {
+    provideConnectedTrellisContext,
+    type TrellisAppOwner,
+    type TrellisContextClient,
+  } from "../context.js";
+
+  type Props = {
+    trellisApp: TrellisAppOwner;
+    trellis: TrellisContextClient;
+    children: Snippet;
+  };
+
+  const { trellisApp, trellis, children }: Props = $props();
+
+  function installContext(): void {
+    provideConnectedTrellisContext(trellisApp, trellis);
+  }
+
+  installContext();
+</script>
+
+{@render children()}

package/dist/components/TrellisContextProvider.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { Component, Snippet } from "svelte";
+import type { TrellisAppOwner, TrellisContextClient } from "../context.js";
+
+type TrellisContextProviderProps = {
+  trellisApp: TrellisAppOwner;
+  trellis: TrellisContextClient;
+  children: Snippet;
+};
+
+declare const TrellisContextProvider: Component<TrellisContextProviderProps>;
+export default TrellisContextProvider;

package/dist/components/TrellisProvider.svelte

@@ -0,0 +1,192 @@
+<script lang="ts" generics="TContract extends TrellisParticipantLike">
+  import {
+    classifyBrowserAuthError,
+    ClientAuthHandledError,
+    TrellisClient,
+    type ClientAuthOptions,
+  } from "@oatscenter/trellis";
+  import { onMount } from "svelte";
+  import type {
+    TrellisClientFor,
+    TrellisParticipantLike,
+  } from "../context.js";
+  import { resolveTrellisAppUrl } from "../context.js";
+  import TrellisContextProvider from "./TrellisContextProvider.svelte";
+  import type { TrellisProviderProps } from "./TrellisProvider.types.js";
+
+  const {
+    trellisApp,
+    auth,
+    client,
+    children,
+    loading,
+    recoveringAuth,
+    error: errorSnippet,
+    onAuthRequired,
+    onRecoverableAuthError,
+  }: TrellisProviderProps<TContract> = $props();
+
+  type ProviderState = "connecting" | "connected" | "auth_handled" | "failed";
+
+  let trellis = $state<TrellisClientFor<TContract> | null>(null);
+  let connectError = $state<unknown>(null);
+  let providerState = $state<ProviderState>("connecting");
+
+  type SerializableTrellisError = {
+    message?: unknown;
+    code?: unknown;
+    hint?: unknown;
+    context?: unknown;
+  };
+
+  function maybeSerializableError(
+    value: unknown,
+  ): SerializableTrellisError | undefined {
+    if (!value || typeof value !== "object" || !("toSerializable" in value)) {
+      return undefined;
+    }
+    const serialize = value.toSerializable;
+    if (typeof serialize !== "function") return undefined;
+    const serialized = serialize.call(value);
+    return serialized && typeof serialized === "object"
+      ? (serialized as SerializableTrellisError)
+      : undefined;
+  }
+
+  function contextRecord(value: unknown): Record<string, unknown> | undefined {
+    return value && typeof value === "object" && !Array.isArray(value)
+      ? (value as Record<string, unknown>)
+      : undefined;
+  }
+
+  function logConnectionError(error: unknown): void {
+    const serialized = maybeSerializableError(error);
+    const context = contextRecord(serialized?.context);
+    const causeMessage =
+      typeof context?.causeMessage === "string"
+        ? context.causeMessage
+        : undefined;
+    const message =
+      typeof serialized?.message === "string"
+        ? serialized.message
+        : error instanceof Error
+          ? error.message
+          : String(error);
+
+    console.error("TrellisProvider failed to connect", {
+      message,
+      code: serialized?.code,
+      hint: serialized?.hint,
+      causeMessage,
+      context: serialized?.context,
+      error,
+    });
+  }
+
+  onMount(() => {
+    let active = true;
+
+    function withBrowserAuthDefaults(
+      authOptions: ClientAuthOptions | undefined,
+    ): ClientAuthOptions {
+      if (authOptions?.mode === "session_key") {
+        return authOptions;
+      }
+
+      return {
+        ...authOptions,
+        currentUrl:
+          authOptions?.currentUrl ?? (() => new URL(window.location.href)),
+      };
+    }
+
+    const connectAuth = withBrowserAuthDefaults(auth);
+    const trellisUrl = resolveTrellisAppUrl(trellisApp.trellisUrl);
+    if (!trellisUrl) {
+      connectError = new TypeError(
+        "Expected trellisApp to resolve a Trellis URL",
+      );
+      providerState = "failed";
+      return;
+    }
+
+    void (async () => {
+      try {
+        const connected = await TrellisClient.connect({
+          ...client,
+          trellisUrl,
+          participant: trellisApp.participant,
+          auth: connectAuth,
+          onAuthRequired: onAuthRequired
+            ? async (ctx) => {
+                await onAuthRequired(ctx.loginUrl, ctx);
+                return { status: "handled" };
+              }
+            : undefined,
+        }).orThrow();
+
+        if (active) {
+          trellis = connected;
+          providerState = "connected";
+        } else {
+          await connected.connection.close();
+        }
+      } catch (error) {
+        if (!active) return;
+        if (error instanceof ClientAuthHandledError) {
+          providerState = "auth_handled";
+          return;
+        }
+        const authRecovery = classifyBrowserAuthError(error);
+        if (authRecovery.recoverable) {
+          if (onRecoverableAuthError) {
+            providerState = "auth_handled";
+            try {
+              await onRecoverableAuthError(error);
+              return;
+            } catch (recoveryError) {
+              if (!active) return;
+              console.error("TrellisProvider auth recovery callback failed", {
+                recoveryError,
+                error,
+              });
+              logConnectionError(recoveryError);
+              connectError = recoveryError;
+              providerState = "failed";
+              return;
+            }
+          }
+          if (recoveringAuth) {
+            providerState = "auth_handled";
+            return;
+          }
+        }
+        logConnectionError(error);
+        connectError = error;
+        providerState = "failed";
+      }
+    })();
+
+    return () => {
+      active = false;
+      const connected = trellis;
+      trellis = null;
+      providerState = "connecting";
+      if (connected) {
+        void connected.connection.close();
+      }
+    };
+  });
+</script>
+
+{#if trellis}
+  <TrellisContextProvider {trellisApp} {trellis} {children} />
+{:else if providerState === "failed" && connectError}
+  {#if errorSnippet}
+    {@render errorSnippet(connectError)}
+  {/if}
+{:else if providerState === "auth_handled" && recoveringAuth}
+  {@render recoveringAuth()}
+{:else if loading}
+  {@render loading()}
+{/if}

package/dist/components/TrellisProvider.svelte.d.ts

@@ -0,0 +1,6 @@
+import type { Component } from "svelte";
+import type { TrellisProviderProps } from "./TrellisProvider.types.js";
+
+/** Svelte component that connects a Trellis app and provides context to children. */
+declare const TrellisProvider: Component<TrellisProviderProps>;
+export default TrellisProvider;

package/dist/components/TrellisProvider.types.d.ts

@@ -0,0 +1,15 @@
+import type { ClientAuthOptions, ClientAuthRequiredContext, ClientOpts } from "@oatscenter/trellis";
+import type { Snippet } from "svelte";
+import type { TrellisAppOwner, TrellisParticipantLike } from "../context.js";
+/** Props accepted by the Svelte Trellis provider component. */
+export type TrellisProviderProps<TContract extends TrellisParticipantLike = TrellisParticipantLike> = {
+    trellisApp: TrellisAppOwner<TContract>;
+    auth?: ClientAuthOptions;
+    client?: ClientOpts;
+    children: Snippet;
+    loading?: Snippet;
+    recoveringAuth?: Snippet;
+    error?: Snippet<[unknown]>;
+    onAuthRequired?: (loginUrl: string, context: ClientAuthRequiredContext) => void | Promise<void>;
+    onRecoverableAuthError?: (error: unknown) => void | Promise<void>;
+};

package/dist/components/TrellisProvider.types.js

@@ -0,0 +1 @@
+export {};

package/dist/context.d.ts

@@ -0,0 +1,72 @@
+import type { CallerParticipant, ConnectedTrellisClient, TrellisConnection, TrellisConnectionStatus } from "@oatscenter/trellis";
+/** Minimal contract shape required to create a typed Trellis Svelte app context. */
+export type TrellisParticipantLike = CallerParticipant;
+/** Real connected Trellis client type exposed by a Svelte app context. */
+export type TrellisClientFor<TContract extends TrellisParticipantLike> = ConnectedTrellisClient<TContract>;
+/** Minimal client surface required for Trellis Svelte context clients. */
+export type TrellisContextClient = {
+    readonly connection: TrellisConnection;
+};
+/** URL value accepted by a Trellis Svelte app owner. */
+export type TrellisAppUrl = string | URL;
+/**
+ * Trellis URL configuration for a Svelte app owner.
+ *
+ * A function resolver supports apps whose Trellis instance is selected at
+ * runtime. Returning `undefined` means no instance is currently available.
+ */
+export type TrellisAppUrlResolver = TrellisAppUrl | (() => TrellisAppUrl | undefined);
+/** Options used to create a Trellis Svelte app owner. */
+export type CreateTrellisAppOptions<TContract extends TrellisParticipantLike = TrellisParticipantLike> = {
+    /** Generated participant used by this app context and its connections. */
+    participant: TContract;
+    /** Trellis URL, or a resolver for runtime-selected Trellis URLs. */
+    trellisUrl: TrellisAppUrlResolver;
+};
+/** Resolves a Trellis app URL config to the string shape required by the client. */
+export declare function resolveTrellisAppUrl(trellisUrl: TrellisAppUrlResolver): string | undefined;
+/** Svelte-reactive adapter around a framework-neutral Trellis connection. */
+export declare class SvelteTrellisConnection {
+    #private;
+    /** Creates a reactive connection adapter for a connected Trellis runtime. */
+    constructor(connection: TrellisConnection);
+    /** Latest connection status, reactive when read by Svelte effects or markup. */
+    get status(): TrellisConnectionStatus;
+    /** Closes the underlying Trellis runtime connection. */
+    close(): Promise<void>;
+}
+declare const trellisAppOwnerBrand: unique symbol;
+/** Minimal branded app owner surface accepted by the Trellis Svelte provider. */
+export type TrellisAppOwner<TContract extends TrellisParticipantLike = TrellisParticipantLike> = {
+    readonly participant: TContract;
+    readonly trellisUrl: TrellisAppUrlResolver;
+    readonly [trellisAppOwnerBrand]: true;
+};
+/**
+ * Public app-scoped typed Svelte context owner for a Trellis browser app.
+ *
+ * `TClient` is a type-only refinement over the descriptor-inferred caller runtime.
+ */
+export interface TrellisApp<TContract extends TrellisParticipantLike = TrellisParticipantLike, TClient extends TrellisContextClient = TrellisClientFor<TContract>> extends TrellisAppOwner<TContract> {
+    /** Generated participant used by this app context and its connections. */
+    readonly participant: TContract;
+    /** Trellis URL configuration used by `TrellisProvider` connections. */
+    readonly trellisUrl: TrellisAppUrlResolver;
+    /** Returns the contract-typed connected Trellis client from Svelte context synchronously. */
+    getTrellis(): TClient;
+    /** Returns a Svelte-reactive adapter for the real Trellis connection. */
+    getConnection(): SvelteTrellisConnection;
+}
+/**
+ * Creates an app-scoped typed Svelte context owner for a Trellis contract and URL.
+ *
+ * The optional `TClient` type parameter refines the connected caller runtime.
+ */
+export declare function createTrellisApp<TContract extends TrellisParticipantLike, TClient extends TrellisContextClient = TrellisClientFor<TContract>>(options: CreateTrellisAppOptions<TContract>): TrellisApp<TContract, TClient>;
+/**
+ * Internal provider helper that synchronously installs connected Trellis context.
+ *
+ * This is intentionally not exported from `src/index.ts`.
+ */
+export declare function provideConnectedTrellisContext(app: TrellisAppOwner, trellis: TrellisContextClient): void;
+export {};

package/dist/context.js

@@ -0,0 +1,116 @@
+/* context.js generated by Svelte v5.55.5 */
+import * as $ from 'svelte/internal/client';
+import { createContext } from "svelte";
+import { createSubscriber } from "svelte/reactivity";
+
+export function resolveTrellisAppUrl(trellisUrl) {
+	const resolved = typeof trellisUrl === "function" ? trellisUrl() : trellisUrl;
+
+	return resolved?.toString();
+}
+
+/** Svelte-reactive adapter around a framework-neutral Trellis connection. */
+export class SvelteTrellisConnection {
+	#connection;
+	#subscribe;
+
+	/** Creates a reactive connection adapter for a connected Trellis runtime. */
+	constructor(connection) {
+		this.#connection = connection;
+
+		this.#subscribe = createSubscriber((update) => {
+			return this.#connection.subscribe(() => update());
+		});
+	}
+
+	/** Latest connection status, reactive when read by Svelte effects or markup. */
+	get status() {
+		this.#subscribe();
+
+		return this.#connection.status;
+	}
+
+	/** Closes the underlying Trellis runtime connection. */
+	close() {
+		return this.#connection.close();
+	}
+}
+
+const provideTrellisContext = Symbol("provideTrellisContext");
+const trellisAppOwnerBrand = Symbol("trellisAppOwner");
+
+/** Internal app-scoped typed Svelte context implementation. */
+class TrellisAppImpl {
+	[trellisAppOwnerBrand] = true;
+	#participant;
+	#trellisUrl;
+	#getContext;
+	#setContext;
+
+	/** Creates an app-scoped context owner for a specific Trellis contract. */
+	constructor(options) {
+		const { participant, trellisUrl } = options;
+
+		this.#participant = participant;
+		this.#trellisUrl = trellisUrl;
+
+		const [getContext, setContext] = createContext();
+
+		this.#getContext = getContext;
+		this.#setContext = setContext;
+	}
+
+	/** Generated participant used by `TrellisProvider` connections. */
+	get participant() {
+		return this.#participant;
+	}
+
+	/** Trellis URL configuration used by `TrellisProvider` connections. */
+	get trellisUrl() {
+		return this.#trellisUrl;
+	}
+
+	/** Returns the contract-typed connected Trellis client from Svelte context synchronously. */
+	getTrellis() {
+		return this.#getContext().trellis;
+	}
+
+	/** Returns a Svelte-reactive adapter for the real Trellis connection. */
+	getConnection() {
+		return this.#getContext().connection;
+	}
+
+	/** Installs the connected Trellis runtime into Svelte context synchronously. */
+	[provideTrellisContext](trellis) {
+		this.#setContext({
+			trellis,
+			connection: new SvelteTrellisConnection(trellis.connection)
+		});
+	}
+}
+
+/**
+ * Creates an app-scoped typed Svelte context owner for a Trellis contract and URL.
+ *
+ * The optional `TClient` type parameter refines the connected caller runtime.
+ */
+export function createTrellisApp(options) {
+	return new TrellisAppImpl(options);
+}
+
+function isTrellisAppImpl(app) {
+	return app instanceof TrellisAppImpl;
+}
+
+/**
+ * Internal provider helper that synchronously installs connected Trellis context.
+ *
+ * This is intentionally not exported from `src/index.ts`.
+ */
+export function provideConnectedTrellisContext(app, trellis) {
+	if (!isTrellisAppImpl(app)) {
+		throw new TypeError("Expected an app created by createTrellisApp");
+	}
+
+	app[provideTrellisContext](trellis);
+}

package/dist/device_activation.d.ts

@@ -0,0 +1,6 @@
+import { type DeviceActivationControllerConfig, DeviceActivationControllerCore } from "./device_activation_controller.js";
+export type { DeviceActivationAuth, DeviceActivationClient, DeviceActivationControllerConfig, DeviceActivationOperationRef, } from "./device_activation_controller.js";
+export declare class DeviceActivationController extends DeviceActivationControllerCore {
+    constructor(config: DeviceActivationControllerConfig);
+}
+export declare function createDeviceActivationController(config: DeviceActivationControllerConfig): DeviceActivationController;

package/dist/device_activation.js

@@ -0,0 +1,19 @@
+/* device_activation.js generated by Svelte v5.55.5 */
+import * as $ from 'svelte/internal/client';
+
+import {
+	createInitialDeviceActivationState,
+	DeviceActivationControllerCore
+} from "./device_activation_controller.js";
+
+export class DeviceActivationController extends DeviceActivationControllerCore {
+	constructor(config) {
+		const state = $.proxy(createInitialDeviceActivationState());
+
+		super(config, state);
+	}
+}
+
+export function createDeviceActivationController(config) {
+	return new DeviceActivationController(config);
+}