@atlasauth/svelte 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atlas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,231 @@
+# @atlas/svelte
+
+The official **Svelte / SvelteKit** SDK for Atlas — the Svelte peer of
+[`@atlas/react`](../react). Same surface, expressed the Svelte way: a client
+installed through **context**, reactive auth state exposed as **stores**, and
+`.svelte` **components** for the common flows.
+
+It wraps [`@atlas/js`](../js), the framework-agnostic browser client, exactly as
+the React SDK does — so both frameworks drive the same FAPI endpoints through one
+implementation and cannot diverge in what the server sees.
+
+- Works with Svelte **4 and 5** (uses `export let` / stores; runes are optional).
+- The refresh token is HttpOnly and never touched by this code; only the
+  short-lived JWT lives in memory, only as long as the tab.
+
+> Install & build note: this package builds with `svelte-package` and tests with
+> Vitest + `@testing-library/svelte` under the toolchain declared in
+> `package.json`. It is wired for the pnpm workspace (`workspace:*` deps) and has
+> not been `pnpm install`ed in this checkout.
+
+## Install
+
+```bash
+pnpm add @atlas/svelte
+```
+
+Peer dependencies: `svelte >= 4`. `@sveltejs/kit` is an **optional** peer, needed
+only for the server helper.
+
+## Quick start
+
+### 1. Install the client — `initAtlas` or `<AtlasProvider>`
+
+`initAtlas` puts the Atlas client into Svelte context. Call it once, high in the
+tree — typically from your root layout, or use the `<AtlasProvider>` convenience
+component which also paints the appearance tokens onto a host-DOM wrapper.
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script lang="ts">
+  import { AtlasProvider } from '@atlas/svelte';
+</script>
+
+<AtlasProvider publishableKey="pk_live_…" frontendApi="https://<instance>.atlas.dev">
+  <slot />
+</AtlasProvider>
+```
+
+Or imperatively, from any component's `<script>`:
+
+```svelte
+<script lang="ts">
+  import { initAtlas } from '@atlas/svelte';
+  const atlas = initAtlas({ publishableKey: 'pk_live_…' });
+</script>
+```
+
+`initAtlas` boots automatically in the browser (handles an OAuth/hosted-page
+redirect, then loads `/v1/client`) and is a no-op during SSR.
+
+### 2. Read state — stores & accessors
+
+Every accessor returns a **store**, so `$`-prefix it in a template and it stays
+live. They mirror the React hooks one-to-one:
+
+| React hook        | Svelte accessor      | Returns a store of …                                   |
+| ----------------- | -------------------- | ------------------------------------------------------ |
+| `useUser()`       | `getUser()`          | `{ isLoaded, isSignedIn, user, getProviderToken }`     |
+| `useSession()`    | `getSession()`       | `{ isLoaded, session }`                                |
+| `useAuth()`       | `getAuth()`          | `{ isLoaded, isSignedIn, userId, sessionId, orgId, orgRole, getToken, getProviderToken, signOut, has }` |
+| `useOrganization()` | `getOrganization()` | `{ isLoaded, organization, membership, memberships, setActive }` |
+| `useAtlas()`      | `useAtlas()`         | the client itself (raw stores + actions)               |
+
+```svelte
+<script lang="ts">
+  import { getUser, getAuth } from '@atlas/svelte';
+  const user = getUser();
+  const auth = getAuth();
+
+  async function callApi() {
+    const token = await $auth.getToken();      // fresh JWT, refreshed if stale
+    // fetch('/api/thing', { headers: { authorization: `Bearer ${token}` } })
+  }
+</script>
+
+{#if $user.isLoaded}
+  <p>Hello {$user.user?.first_name ?? 'stranger'}</p>
+{/if}
+```
+
+The raw stores are also on the client: `useAtlas().user`, `.session`,
+`.status`, `.claims`, `.memberships`, `.isSignedIn`, `.isLoaded`.
+
+**Action helpers** (import and call from a component `<script>`): `getToken()`,
+`signOut()`, and `signIn()` / `signUp()` (which return a flow controller —
+`{ state, submit, destroy }` — the same driver `<SignIn>` uses).
+
+### 3. Components
+
+Mirror `@atlas/react`'s `components.tsx`:
+
+| Component               | Purpose                                                        |
+| ----------------------- | ------------------------------------------------------------- |
+| `<SignedIn>`            | renders its slot only when signed in                          |
+| `<SignedOut>`           | renders its slot only when signed out                         |
+| `<AtlasLoading>`        | slot only while the SDK is still booting                      |
+| `<AtlasLoaded>`         | slot only once booted (symmetric partner of `<AtlasLoading>`) |
+| `<Protect>`             | slot when the auth condition holds; `fallback` slot otherwise |
+| `<SignIn>` / `<SignUp>` | full server-driven, multi-step flows                          |
+| `<UserButton>`          | avatar + account menu                                         |
+| `<UserProfile>`         | account-management card                                       |
+| `<OrganizationSwitcher>`| switch the active organization                                |
+| `<OrganizationProfile>` | active organization's card                                    |
+
+```svelte
+<script lang="ts">
+  import { SignedIn, SignedOut, SignIn, UserButton, Protect } from '@atlas/svelte';
+</script>
+
+<SignedOut><SignIn /></SignedOut>
+<SignedIn><UserButton /></SignedIn>
+
+<Protect permission="org:sys_memberships:manage">
+  <button>Invite member</button>
+  <p slot="fallback">You don't have access.</p>
+</Protect>
+```
+
+> `<Protect>` is a **rendering** helper, never an authorization boundary —
+> anyone can flip the condition in devtools. The server checking the same
+> permission is what actually stops them.
+
+### Theming & i18n
+
+Same as `@atlas/react`: pass `appearance` (design tokens + per-element class
+overrides — components render in the host DOM, no iframe, so Tailwind/CSS just
+work) and `localization` (a flat i18n catalog, merged over `en-US`) to
+`initAtlas` / `<AtlasProvider>`.
+
+```svelte
+<AtlasProvider
+  publishableKey="pk_live_…"
+  appearance={{ baseTheme: 'dark', elements: { formButtonPrimary: 'rounded-xl' } }}
+>
+  <slot />
+</AtlasProvider>
+```
+
+## SvelteKit SSR
+
+The server helper lives at the separate `@atlas/svelte/server` entry (it depends
+on `@atlas/backend` and must never enter a browser bundle). It verifies the
+session JWT **locally at the edge** — the JWKS is cached in-process, so a warm
+server verifies with no network round-trip.
+
+### `hooks.server.ts`
+
+```ts
+import { handleAtlas } from '@atlas/svelte/server';
+
+export const handle = handleAtlas({
+  jwksUrl: 'https://<instance>.atlas.dev/.well-known/jwks.json',
+  issuer: 'https://<instance>.atlas.dev',
+  // authorizedParties: ['https://app.example.com'], // optional azp allowlist
+});
+```
+
+This resolves the session once per request and stashes it on
+`event.locals.auth`.
+
+### In a `load` or endpoint
+
+```ts
+// +layout.server.ts
+import { getServerAuth } from '@atlas/svelte/server';
+
+export const load = (event) => {
+  const auth = getServerAuth(event);
+  return { userId: auth.userId, isSignedIn: auth.isSignedIn };
+};
+```
+
+```ts
+// a protected +page.server.ts
+import { getServerAuth } from '@atlas/svelte/server';
+import { error } from '@sveltejs/kit';
+
+export const load = (event) => {
+  const auth = getServerAuth(event);
+  try {
+    auth.protect({ permission: 'org:reports:read' }); // throws ForbiddenError if unmet
+  } catch {
+    throw error(403, 'Forbidden');
+  }
+  return { ok: true };
+};
+```
+
+`getServerAuth(event).has(condition)` answers a condition without throwing;
+`.protect(condition)` asserts it (throwing `ForbiddenError`). Both use the shared
+`@atlas/authz` primitive — the same one `<Protect>` evaluates in the browser — so
+a check reads identically on the client, here, and in the React/Next SDKs.
+
+For strong typing of `event.locals.auth`, add to `src/app.d.ts`:
+
+```ts
+import type { ServerAuth } from '@atlas/svelte/server';
+declare global {
+  namespace App {
+    interface Locals {
+      auth: ServerAuth;
+    }
+  }
+}
+export {};
+```
+
+## Development
+
+```bash
+pnpm --filter @atlas/svelte build       # svelte-package → dist/
+pnpm --filter @atlas/svelte typecheck   # svelte-check
+pnpm --filter @atlas/svelte test        # vitest (jsdom + @testing-library/svelte)
+```
+
+Tests cover the context init, the reactive stores, and `<SignedIn>`/`<SignedOut>`
+(with `@atlas/js` mocked).
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/accessors.d.ts

@@ -0,0 +1,81 @@
+import { type Readable } from 'svelte/store';
+import { type FlowState, type ProviderToken } from '@atlasauth/js';
+import { type ProtectCondition } from './protect';
+import type { AtlasOrganizationMembership, AtlasSession, AtlasUser } from './types';
+/**
+ * §10.1 accessors — the Svelte peer of React's hooks (`useUser`, `useSession`,
+ * `useAuth`, `useOrganization`).
+ *
+ * React returns a plain snapshot that re-runs on every render. Svelte has no
+ * render loop, so each accessor returns a **derived store** instead: `$user`
+ * in a template updates exactly when the underlying state changes, and
+ * `get(user)` reads it once in plain code.
+ *
+ * Every one carries `isLoaded`, and that is not ceremony. Without it a component
+ * cannot tell "still booting" from "signed out", so it flashes a sign-in form
+ * for a fraction of a second on every page load.
+ */
+export interface UseUser {
+    isLoaded: boolean;
+    isSignedIn: boolean;
+    user: AtlasUser | null;
+    /**
+     * §6.6 the signed-in user's own live token at a connected provider — the
+     * `user.getToken({ provider })` equivalent. Always the caller's own token,
+     * refreshed on read if stale, never the refresh token.
+     */
+    getProviderToken(provider: string): Promise<ProviderToken | null>;
+}
+export declare function getUser(): Readable<UseUser>;
+export interface UseSession {
+    isLoaded: boolean;
+    session: AtlasSession | null;
+}
+export declare function getSession(): Readable<UseSession>;
+export interface UseAuth {
+    isLoaded: boolean;
+    isSignedIn: boolean;
+    userId: string | null;
+    sessionId: string | null;
+    orgId: string | null;
+    orgRole: string | null;
+    /** Always fresh: refreshes first if the cached token is close to expiry. */
+    getToken(): Promise<string | null>;
+    /** §6.6 the user's own live access token at a connected social provider. */
+    getProviderToken(provider: string): Promise<ProviderToken | null>;
+    signOut(): Promise<void>;
+    /** Mirrors `<Protect>`, for logic that is not a render decision. */
+    has(condition: ProtectCondition): boolean;
+}
+export declare function getAuth(): Readable<UseAuth>;
+export interface UseOrganization {
+    isLoaded: boolean;
+    organization: AtlasOrganizationMembership['organization'] | null;
+    membership: AtlasOrganizationMembership | null;
+    memberships: AtlasOrganizationMembership[];
+    setActive(organizationId: string | null): Promise<void>;
+}
+export declare function getOrganization(): Readable<UseOrganization>;
+/** Refresh-if-stale, then hand over the JWT. The `useAuth().getToken` shortcut. */
+export declare function getToken(): Promise<string | null>;
+/** Revoke the session and drop all in-memory state. */
+export declare function signOut(): Promise<void>;
+/**
+ * A running sign-in / sign-up attempt: a reactive `state` store plus `submit`.
+ *
+ * This is the imperative peer of React's `useFlow`. The whole flow is
+ * server-driven — `advance` (from `@atlasauth/js`) owns the step-to-endpoint
+ * mapping, so this controller never decides what comes next. It posts whatever
+ * the current step needs, renders the status the server returned, and on
+ * completion exchanges the one-time ticket for cookies then re-boots.
+ */
+export interface FlowController {
+    state: Readable<FlowState>;
+    submit(values: Record<string, string>): void;
+    /** Stop the magic-link poll loop — call from `onDestroy`. */
+    destroy(): void;
+}
+/** Start (or resume) a sign-in flow. Drives `<SignIn>`; usable standalone too. */
+export declare function signIn(): FlowController;
+/** Start a sign-up flow. Drives `<SignUp>`; usable standalone too. */
+export declare function signUp(): FlowController;

package/dist/accessors.js

@@ -0,0 +1,126 @@
+import { derived, get, writable } from 'svelte/store';
+import { FapiClient, advance, flowFromPending, pollAttempt, shouldKeepPolling, } from '@atlasauth/js';
+import { useAtlas } from './context';
+import { evaluate } from './protect';
+export function getUser() {
+    const atlas = useAtlas();
+    return derived([atlas.status, atlas.user], ([$status, $user]) => ({
+        isLoaded: $status !== 'loading',
+        isSignedIn: $status === 'signed_in',
+        user: $user,
+        getProviderToken: atlas.getProviderToken,
+    }));
+}
+export function getSession() {
+    const atlas = useAtlas();
+    return derived([atlas.status, atlas.session], ([$status, $session]) => ({
+        isLoaded: $status !== 'loading',
+        session: $session,
+    }));
+}
+export function getAuth() {
+    const atlas = useAtlas();
+    return derived([atlas.status, atlas.claims], ([$status, $claims]) => ({
+        isLoaded: $status !== 'loading',
+        isSignedIn: $status === 'signed_in',
+        userId: $claims?.sub ?? null,
+        sessionId: $claims?.sid ?? null,
+        orgId: $claims?.org_id ?? null,
+        orgRole: $claims?.org_role ?? null,
+        getToken: atlas.getToken,
+        getProviderToken: atlas.getProviderToken,
+        signOut: atlas.signOut,
+        has: (condition) => evaluate($claims, condition).allowed,
+    }));
+}
+export function getOrganization() {
+    const atlas = useAtlas();
+    return derived([atlas.status, atlas.claims, atlas.memberships], ([$status, $claims, $memberships]) => {
+        const active = $memberships.find((m) => m.organization.id === $claims?.org_id) ?? null;
+        return {
+            isLoaded: $status !== 'loading',
+            organization: active?.organization ?? null,
+            membership: active,
+            memberships: $memberships,
+            setActive: atlas.setActiveOrganization,
+        };
+    });
+}
+/* ------------------------------------------------------------------ actions */
+/** Refresh-if-stale, then hand over the JWT. The `useAuth().getToken` shortcut. */
+export function getToken() {
+    return useAtlas().getToken();
+}
+/** Revoke the session and drop all in-memory state. */
+export function signOut() {
+    return useAtlas().signOut();
+}
+function createFlow() {
+    const atlas = useAtlas();
+    const client = new FapiClient({
+        publishableKey: atlas.publishableKey,
+        baseUrl: atlas.frontendApi,
+    });
+    // Seeded from a redirect that came back mid-flow (e.g. OAuth needing a second
+    // factor), so the user resumes at the demanded step instead of starting over.
+    const state = writable(flowFromPending(atlas.pendingAttempt));
+    let pollTimer = null;
+    function stopPolling() {
+        if (pollTimer)
+            clearInterval(pollTimer);
+        pollTimer = null;
+    }
+    /** §5.3: collect a sign-in completed by a link opened on another device. */
+    function maybeStartPolling() {
+        if (pollTimer || !shouldKeepPolling(get(state)))
+            return;
+        pollTimer = setInterval(() => {
+            void (async () => {
+                const { state: next, ticket } = await pollAttempt(client, get(state));
+                state.set(next);
+                if (!shouldKeepPolling(next))
+                    stopPolling();
+                if (!ticket || !next.attempt)
+                    return;
+                // The ticket is exchanged by a normal request, so no session token has
+                // ever appeared in a URL.
+                await client.post('/v1/client/tickets/exchange', {
+                    attempt_id: next.attempt.id,
+                    ticket,
+                });
+                await atlas.reload();
+            })();
+        }, 2_000);
+    }
+    function submit(values) {
+        void (async () => {
+            state.update((current) => ({ ...current, busy: true, errors: [] }));
+            const next = await advance(client, get(state), values);
+            state.set(next);
+            // On completion the response carries a one-time ticket (§7.1). Exchange it
+            // for cookies over a same-origin request — FAPI is cross-origin to the app
+            // and cannot set the cookie on the completion response itself — THEN
+            // re-boot so the rest of the app sees a signed-in user.
+            if (next.attempt?.status === 'complete') {
+                if (next.ticket) {
+                    await client.post('/v1/client/tickets/exchange', {
+                        attempt_id: next.attempt.id,
+                        ticket: next.ticket,
+                    });
+                }
+                await atlas.reload();
+                return;
+            }
+            maybeStartPolling();
+        })();
+    }
+    return { state: { subscribe: state.subscribe }, submit, destroy: stopPolling };
+}
+/** Start (or resume) a sign-in flow. Drives `<SignIn>`; usable standalone too. */
+export function signIn() {
+    return createFlow();
+}
+/** Start a sign-up flow. Drives `<SignUp>`; usable standalone too. */
+export function signUp() {
+    return createFlow();
+}

package/dist/appearance.d.ts

@@ -0,0 +1,85 @@
+/**
+ * §10.3 theming.
+ *
+ * "appearance prop: design tokens (colors, radius, font, spacing) + per-element
+ * class overrides (elements: { formButtonPrimary: "…" }). No iframe — components
+ * render in the host DOM so Tailwind/CSS just works."
+ *
+ * Rendering in the host DOM is the decision everything else follows from. An
+ * iframe would isolate styles perfectly and be unusable: it cannot be sized to
+ * its content reliably, it breaks password managers, it breaks autofill, and a
+ * Tailwind class the customer writes has no effect inside it. Sharing the DOM
+ * means the customer's CSS reaches our markup, which is exactly what they want
+ * and what makes an override system necessary rather than decorative.
+ *
+ * Element classes are APPENDED to ours, never replacing them. A customer adding
+ * `className="rounded-xl"` wants a rounder button, not an unstyled one — and
+ * replacement is a support burden where every override starts by rebuilding the
+ * component's base styles from scratch.
+ */
+export interface DesignTokens {
+    colorPrimary?: string;
+    colorText?: string;
+    colorBackground?: string;
+    colorDanger?: string;
+    colorBorder?: string;
+    borderRadius?: string;
+    fontFamily?: string;
+    spacingUnit?: string;
+}
+/** Every element a customer may target. Named for what it IS, not where it sits. */
+export type ElementKey = 'root' | 'card' | 'headerTitle' | 'headerSubtitle' | 'formField' | 'formFieldLabel' | 'formFieldInput' | 'formFieldError' | 'formButtonPrimary' | 'formButtonSecondary' | 'socialButton' | 'dividerText' | 'footerAction' | 'avatar' | 'menu' | 'menuItem' | 'badge';
+export interface Appearance {
+    /** A prebuilt theme to start from. */
+    baseTheme?: keyof typeof THEMES;
+    variables?: DesignTokens;
+    elements?: Partial<Record<ElementKey, string>>;
+}
+export declare const DEFAULT_TOKENS: Required<DesignTokens>;
+/**
+ * §10.3: "prebuilt themes shipped (default, dark, neobrutalist as a demo of the
+ * override system)". Neobrutalist exists to prove the token set is expressive
+ * enough for a theme that looks nothing like the default — a theming system
+ * that only produces tasteful variations of itself is not a theming system.
+ */
+export declare const THEMES: {
+    readonly default: Required<DesignTokens>;
+    readonly dark: {
+        readonly colorText: "#e6e9ef";
+        readonly colorBackground: "#14171c";
+        readonly colorBorder: "#242932";
+        readonly colorPrimary: "#6ea8fe";
+        readonly colorDanger: string;
+        readonly borderRadius: string;
+        readonly fontFamily: string;
+        readonly spacingUnit: string;
+    };
+    readonly neobrutalist: {
+        readonly colorPrimary: "#ffe600";
+        readonly colorText: "#000000";
+        readonly colorBackground: "#ffffff";
+        readonly colorBorder: "#000000";
+        readonly borderRadius: "0px";
+        readonly fontFamily: "\"Courier New\", ui-monospace, monospace";
+        readonly colorDanger: string;
+        readonly spacingUnit: string;
+    };
+};
+/**
+ * Resolve tokens: defaults, then the base theme, then explicit variables.
+ *
+ * Later wins, and `undefined` never overwrites. A customer setting one variable
+ * on the dark theme expects the other eleven to stay dark, not silently revert
+ * to the light defaults.
+ */
+export declare function resolveTokens(appearance?: Appearance): Required<DesignTokens>;
+/** Tokens as CSS custom properties, for the host DOM to inherit. */
+export declare function cssVariables(tokens: Required<DesignTokens>): Record<string, string>;
+/**
+ * Combine our base class with the customer's override.
+ *
+ * Appended, never replaced — a customer adding `rounded-xl` wants a rounder
+ * button, not an unstyled one. Theirs comes last so it wins on equal
+ * specificity, which is the behaviour anyone writing Tailwind expects.
+ */
+export declare function classFor(element: ElementKey, appearance: Appearance | undefined, base: string): string;

package/dist/appearance.js

@@ -0,0 +1,91 @@
+/**
+ * §10.3 theming.
+ *
+ * "appearance prop: design tokens (colors, radius, font, spacing) + per-element
+ * class overrides (elements: { formButtonPrimary: "…" }). No iframe — components
+ * render in the host DOM so Tailwind/CSS just works."
+ *
+ * Rendering in the host DOM is the decision everything else follows from. An
+ * iframe would isolate styles perfectly and be unusable: it cannot be sized to
+ * its content reliably, it breaks password managers, it breaks autofill, and a
+ * Tailwind class the customer writes has no effect inside it. Sharing the DOM
+ * means the customer's CSS reaches our markup, which is exactly what they want
+ * and what makes an override system necessary rather than decorative.
+ *
+ * Element classes are APPENDED to ours, never replacing them. A customer adding
+ * `className="rounded-xl"` wants a rounder button, not an unstyled one — and
+ * replacement is a support burden where every override starts by rebuilding the
+ * component's base styles from scratch.
+ */
+export const DEFAULT_TOKENS = {
+    colorPrimary: '#5b5bd6',
+    colorText: '#1c1c1f',
+    colorBackground: '#ffffff',
+    colorDanger: '#d64545',
+    colorBorder: '#e4e4e9',
+    borderRadius: '8px',
+    fontFamily: 'ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif',
+    spacingUnit: '4px',
+};
+/**
+ * §10.3: "prebuilt themes shipped (default, dark, neobrutalist as a demo of the
+ * override system)". Neobrutalist exists to prove the token set is expressive
+ * enough for a theme that looks nothing like the default — a theming system
+ * that only produces tasteful variations of itself is not a theming system.
+ */
+export const THEMES = {
+    default: DEFAULT_TOKENS,
+    dark: {
+        ...DEFAULT_TOKENS,
+        colorText: '#e6e9ef',
+        colorBackground: '#14171c',
+        colorBorder: '#242932',
+        colorPrimary: '#6ea8fe',
+    },
+    neobrutalist: {
+        ...DEFAULT_TOKENS,
+        colorPrimary: '#ffe600',
+        colorText: '#000000',
+        colorBackground: '#ffffff',
+        colorBorder: '#000000',
+        borderRadius: '0px',
+        fontFamily: '"Courier New", ui-monospace, monospace',
+    },
+};
+/**
+ * Resolve tokens: defaults, then the base theme, then explicit variables.
+ *
+ * Later wins, and `undefined` never overwrites. A customer setting one variable
+ * on the dark theme expects the other eleven to stay dark, not silently revert
+ * to the light defaults.
+ */
+export function resolveTokens(appearance) {
+    const base = appearance?.baseTheme ? THEMES[appearance.baseTheme] : DEFAULT_TOKENS;
+    const overrides = appearance?.variables ?? {};
+    const resolved = { ...DEFAULT_TOKENS, ...base };
+    for (const [key, value] of Object.entries(overrides)) {
+        if (value !== undefined)
+            resolved[key] = value;
+    }
+    return resolved;
+}
+/** Tokens as CSS custom properties, for the host DOM to inherit. */
+export function cssVariables(tokens) {
+    const vars = {};
+    for (const [key, value] of Object.entries(tokens)) {
+        // camelCase → --atlas-kebab-case, which is what a customer writes in CSS.
+        vars[`--atlas-${key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`] = value;
+    }
+    return vars;
+}
+/**
+ * Combine our base class with the customer's override.
+ *
+ * Appended, never replaced — a customer adding `rounded-xl` wants a rounder
+ * button, not an unstyled one. Theirs comes last so it wins on equal
+ * specificity, which is the behaviour anyone writing Tailwind expects.
+ */
+export function classFor(element, appearance, base) {
+    const override = appearance?.elements?.[element];
+    return override ? `${base} ${override}` : base;
+}

package/dist/components/AtlasLoaded.svelte

@@ -0,0 +1,7 @@
+<script>import { getUser } from "../accessors";
+const user = getUser();
+</script>
+
+{#if $user.isLoaded}
+  <slot />
+{/if}

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

@@ -0,0 +1,18 @@
+import { SvelteComponent } from "svelte";
+declare const __propDef: {
+    props: Record<string, never>;
+    events: {
+        [evt: string]: CustomEvent<any>;
+    };
+    slots: {
+        default: {};
+    };
+    exports?: {} | undefined;
+    bindings?: string | undefined;
+};
+export type AtlasLoadedProps = typeof __propDef.props;
+export type AtlasLoadedEvents = typeof __propDef.events;
+export type AtlasLoadedSlots = typeof __propDef.slots;
+export default class AtlasLoaded extends SvelteComponent<AtlasLoadedProps, AtlasLoadedEvents, AtlasLoadedSlots> {
+}
+export {};

package/dist/components/AtlasLoading.svelte

@@ -0,0 +1,7 @@
+<script>import { getUser } from "../accessors";
+const user = getUser();
+</script>
+
+{#if !$user.isLoaded}
+  <slot />
+{/if}