@viniaraujo68/plinth 0.0.0-stage → 0.2.0

package/dist/toast/Toaster.svelte

@@ -0,0 +1,257 @@
+<script lang="ts">
+  import { fly, scale } from "svelte/transition";
+  import type { ClassValue } from "svelte/elements";
+  import {
+    getDefaultToastManager,
+    type ToastManager,
+    type ToastPosition,
+    type ToastVariant,
+  } from "./toast-manager.svelte.js";
+
+  interface Props {
+    class?: ClassValue;
+    /** Queue to render. Defaults to the one behind the module-level `toast` helper. */
+    manager?: ToastManager;
+    position?: ToastPosition;
+    /** Stack newest first. The default puts the newest at the bottom of the stack. */
+    reverseOrder?: boolean;
+    /** Accessible name of the live region, for apps that are not in English. */
+    label?: string;
+    /** Accessible name of every toast's dismiss button. */
+    dismissLabel?: string;
+  }
+
+  let {
+    class: cls,
+    manager,
+    position = "bottom-end",
+    reverseOrder = false,
+    label = "Notifications",
+    dismissLabel = "Dismiss notification",
+  }: Props = $props();
+
+  const resolvedManager = $derived(manager ?? getDefaultToastManager());
+  const toasts = $derived(
+    reverseOrder ? resolvedManager.toasts.toReversed() : resolvedManager.toasts,
+  );
+
+  const POSITION_CLASSES: Record<ToastPosition, string> = {
+    "top-start": "toast-top toast-start",
+    "top-center": "toast-top toast-center",
+    "top-end": "toast-top toast-end",
+    "middle-start": "toast-middle toast-start",
+    "middle-center": "toast-middle toast-center",
+    "middle-end": "toast-middle toast-end",
+    "bottom-start": "toast-bottom toast-start",
+    "bottom-center": "toast-bottom toast-center",
+    "bottom-end": "toast-bottom toast-end",
+  };
+
+  const VARIANT_CLASSES: Record<ToastVariant, string> = {
+    info: "alert-info",
+    success: "alert-success",
+    warning: "alert-warning",
+    error: "alert-error",
+  };
+
+  // Inline paths rather than an icon font or an iconify plugin: the library must render correctly
+  // in a consumer that installed nothing but the package. Variant is never signalled by color
+  // alone, which is what makes the four alerts distinguishable to a colorblind reader.
+  const VARIANT_ICONS: Record<ToastVariant, string[]> = {
+    info: ["M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18", "M12 16v-5", "M12 8h.01"],
+    success: ["M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18", "m8.5 12.4 2.4 2.4 4.6-5.2"],
+    warning: [
+      "M10.3 3.9 1.8 18a2 2 0 0 0 1.7 3h17a2 2 0 0 0 1.7-3L13.7 3.9a2 2 0 0 0-3.4 0",
+      "M12 9v4",
+      "M12 17h.01",
+    ],
+    error: ["M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18", "m14.5 9.5-5 5", "m9.5 9.5 5 5"],
+  };
+
+  const edgeOf = (value: ToastPosition) => {
+    if (value.startsWith("top")) return "top";
+    if (value.startsWith("middle")) return "middle";
+    return "bottom";
+  };
+
+  const edge = $derived(edgeOf(position));
+
+  // A toast that enters from off-stage would fly past the viewport edge it is anchored to, so the
+  // offset points back towards the middle of the screen.
+  const flyOffset = $derived(edge === "top" ? -8 : 8);
+
+  const containsNode = (element: HTMLElement, node: EventTarget | null) =>
+    node instanceof Node && element.contains(node);
+
+  const resumeUnlessStillHeld = (id: string, event: MouseEvent | FocusEvent) => {
+    const toastElement = event.currentTarget;
+    if (!(toastElement instanceof HTMLElement)) return;
+
+    // A pointer leaving for a child, or focus moving between the toast's own controls, is not a
+    // reader letting go of the toast — the countdown has to stay frozen.
+    if (containsNode(toastElement, event.relatedTarget)) return;
+    if (containsNode(toastElement, document.activeElement)) return;
+    if (toastElement.matches(":hover")) return;
+
+    resolvedManager.resume(id);
+  };
+
+  // Toasts have to outrank a modal `<dialog>`, and z-index cannot do it: a modal dialog lives in
+  // the browser's top layer, above every positioned element in the document. A popover reaches
+  // the top layer too, but a modal dialog still paints over a popover anchored in <body> — the
+  // only popover that wins is one nested inside that dialog. So the stack is hosted inside the
+  // topmost open modal when there is one, and in <body> otherwise.
+  let host = $state<HTMLElement>();
+
+  $effect(() => {
+    const pickHost = () => {
+      const modals = document.querySelectorAll<HTMLDialogElement>("dialog:modal");
+      host = modals[modals.length - 1] ?? document.body;
+    };
+
+    pickHost();
+    // `:modal` flips with the `open` attribute that showModal()/close() write, so watching that
+    // one attribute re-parents live toasts as dialogs come and go.
+    const observer = new MutationObserver(pickHost);
+    observer.observe(document.documentElement, {
+      subtree: true,
+      attributes: true,
+      attributeFilter: ["open"],
+    });
+    return () => {
+      observer.disconnect();
+    };
+  });
+
+  const hostInTopLayer = (target: HTMLElement | undefined) => (element: HTMLElement) => {
+    const parent = target ?? document.body;
+    if (element.parentElement !== parent) {
+      if (element.matches(":popover-open")) element.hidePopover();
+      parent.appendChild(element);
+    }
+    if (!element.matches(":popover-open")) element.showPopover();
+  };
+</script>
+
+<!--
+@component
+Renders a `ToastManager`'s queue. Mount exactly one, unconditionally, in the app's root layout —
+it has to outlive navigation so a toast fired just before a `goto()` survives to the next page.
+
+With no `manager` prop it renders the queue behind the module-level `toast` helper, which is what
+lets any module in the app call `toast.error(...)` with nothing plumbed through.
+
+```svelte
+<Toaster position="top-end" />
+```
+
+The stack is a top-layer popover, re-parented into the topmost open modal `<dialog>` while one is
+open, so toasts stay visible and clickable above a modal.
+
+Its live region stays mounted even with nothing to show: a screen reader announces additions
+reliably only into a region that was already in the accessibility tree when the content arrived.
+It is `pointer-events: none` for that reason — an empty region must never swallow a tap.
+-->
+
+<div
+  class={["pointer-events-none toast gap-2", POSITION_CLASSES[position], cls]}
+  data-edge={edge}
+  popover="manual"
+  role="region"
+  aria-label={label}
+  aria-live="polite"
+  aria-relevant="additions text"
+  {@attach hostInTopLayer(host)}
+>
+  {#each toasts as toast (toast.id)}
+    <div
+      class={[
+        "pointer-events-auto alert w-80 max-w-full shadow-lg",
+        VARIANT_CLASSES[toast.variant],
+      ]}
+      data-testid="toast"
+      data-variant={toast.variant}
+      role={toast.variant === "info" || toast.variant === "success" ? "status" : "alert"}
+      aria-atomic="true"
+      onmouseenter={() => resolvedManager.pause(toast.id)}
+      onmouseleave={(event) => resumeUnlessStillHeld(toast.id, event)}
+      onfocusin={() => resolvedManager.pause(toast.id)}
+      onfocusout={(event) => resumeUnlessStillHeld(toast.id, event)}
+      in:fly|global={{ y: flyOffset, duration: 140 }}
+      out:scale|global={{ start: 0.96, duration: 160 }}
+    >
+      <svg
+        class="size-5 shrink-0"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        aria-hidden="true"
+      >
+        {#each VARIANT_ICONS[toast.variant] as d (d)}
+          <path {d} />
+        {/each}
+      </svg>
+
+      <div class="flex min-w-0 flex-col">
+        <span class="break-words whitespace-pre-line">{toast.message}</span>
+        {#if toast.description}
+          <span class="text-xs opacity-80">{toast.description}</span>
+        {/if}
+      </div>
+
+      {#if toast.dismissible}
+        <button
+          type="button"
+          class="btn btn-square btn-ghost btn-sm"
+          aria-label={dismissLabel}
+          onclick={() => resolvedManager.dismiss(toast.id)}
+        >
+          <svg
+            class="size-4"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+            stroke-linecap="round"
+            aria-hidden="true"
+          >
+            <path d="M18 6 6 18" />
+            <path d="m6 6 12 12" />
+          </svg>
+        </button>
+      {/if}
+    </div>
+  {/each}
+</div>
+
+<style>
+  /* The stack is a popover, so the UA popover styles apply on top of daisyUI's `.toast`: they add
+     a border, padding, a Canvas background and `overflow: auto`. daisyUI resets none of those
+     because it never expected the element to be in the top layer. */
+  .toast {
+    margin: 0;
+    border: 0;
+    padding: 0;
+    overflow: visible;
+    background: transparent;
+  }
+
+  /* Phone chrome: the home indicator and the notch overlap a viewport-edge stack. daisyUI's flat
+     1rem does not know about either. */
+  .toast[data-edge="bottom"] {
+    bottom: calc(1rem + env(safe-area-inset-bottom));
+  }
+  .toast[data-edge="top"] {
+    top: calc(1rem + env(safe-area-inset-top));
+  }
+
+  /* Svelte's in:/out: transitions own the toast lifecycle. daisyUI's own entry keyframe would
+     replay on every re-parent between hosts (each modal open and close), flashing the whole
+     stack back in. */
+  .toast > :global(*) {
+    animation: none;
+  }
+</style>

package/dist/toast/Toaster.svelte.d.ts

@@ -0,0 +1,35 @@
+import type { ClassValue } from "svelte/elements";
+import { type ToastManager, type ToastPosition } from "./toast-manager.svelte.js";
+interface Props {
+    class?: ClassValue;
+    /** Queue to render. Defaults to the one behind the module-level `toast` helper. */
+    manager?: ToastManager;
+    position?: ToastPosition;
+    /** Stack newest first. The default puts the newest at the bottom of the stack. */
+    reverseOrder?: boolean;
+    /** Accessible name of the live region, for apps that are not in English. */
+    label?: string;
+    /** Accessible name of every toast's dismiss button. */
+    dismissLabel?: string;
+}
+/**
+ * Renders a `ToastManager`'s queue. Mount exactly one, unconditionally, in the app's root layout —
+ * it has to outlive navigation so a toast fired just before a `goto()` survives to the next page.
+ *
+ * With no `manager` prop it renders the queue behind the module-level `toast` helper, which is what
+ * lets any module in the app call `toast.error(...)` with nothing plumbed through.
+ *
+ * ```svelte
+ * <Toaster position="top-end" />
+ * ```
+ *
+ * The stack is a top-layer popover, re-parented into the topmost open modal `<dialog>` while one is
+ * open, so toasts stay visible and clickable above a modal.
+ *
+ * Its live region stays mounted even with nothing to show: a screen reader announces additions
+ * reliably only into a region that was already in the accessibility tree when the content arrived.
+ * It is `pointer-events: none` for that reason — an empty region must never swallow a tap.
+ */
+declare const Toaster: import("svelte").Component<Props, {}, "">;
+type Toaster = ReturnType<typeof Toaster>;
+export default Toaster;

package/dist/toast/index.d.ts

@@ -0,0 +1,2 @@
+export { createToastManager, getDefaultToastManager, toast, ToastManager, type Toast, type ToastApi, type ToastManagerOptions, type ToastOptions, type ToastPosition, type ToastVariant, } from "./toast-manager.svelte.js";
+export { default as Toaster } from "./Toaster.svelte";

package/dist/toast/index.js

@@ -0,0 +1,2 @@
+export { createToastManager, getDefaultToastManager, toast, ToastManager, } from "./toast-manager.svelte.js";
+export { default as Toaster } from "./Toaster.svelte";

package/dist/toast/toast-manager.svelte.d.ts

@@ -0,0 +1,99 @@
+/** Severity a toast carries. Maps to a daisyUI alert modifier and an icon in `Toaster`. */
+export type ToastVariant = "info" | "success" | "warning" | "error";
+/**
+ * Where a `Toaster` anchors its stack. Mirrors daisyUI's two-axis toast placement, so the value
+ * is a rendering concern only — the manager never sees it.
+ */
+export type ToastPosition = "top-start" | "top-center" | "top-end" | "middle-start" | "middle-center" | "middle-end" | "bottom-start" | "bottom-center" | "bottom-end";
+/** A queued notification. Produced by the manager; consumed by `Toaster`. */
+export interface Toast {
+    id: string;
+    variant: ToastVariant;
+    message: string;
+    /** Secondary line, rendered smaller under the message. */
+    description?: string;
+    /** Milliseconds on screen. Anything non-finite or non-positive makes the toast sticky. */
+    duration: number;
+    dismissible: boolean;
+    /** Set once per id, so an in-place update keeps the moment the toast first appeared. */
+    createdAt: number;
+}
+export interface ToastOptions {
+    /**
+     * Reuse an id to replace a toast in place instead of stacking a second one. Everything except
+     * `createdAt` is replaced, so an option left out falls back to the default rather than to the
+     * previous toast's value.
+     */
+    id?: string;
+    duration?: number;
+    description?: string;
+    dismissible?: boolean;
+}
+export interface ToastManagerOptions {
+    /**
+     * How many toasts may be on screen at once; the oldest is dropped to make room. A cap exists
+     * because a failing loop can fire dozens of identical errors, and a stack taller than the
+     * viewport hides the newest one — the only one still worth reading.
+     */
+    limit?: number;
+    /** Per-variant auto-dismiss delays, merged over the defaults. */
+    durations?: Partial<Record<ToastVariant, number>>;
+}
+/**
+ * The queue behind `Toaster`. Owns ids, ordering, the stack cap and every auto-dismiss timer.
+ *
+ * Most apps never touch this class: `toast.success(...)` goes through the process-wide default
+ * manager, and a single `<Toaster />` near the app root renders it. Construct one explicitly to
+ * scope a queue to a subtree, or to give a test a manager it can throw away afterwards.
+ */
+export declare class ToastManager {
+    #private;
+    constructor({ limit, durations }?: ToastManagerOptions);
+    /** Oldest first. Read-only by contract — every mutation goes through a method. */
+    get toasts(): readonly Toast[];
+    /** Push a toast (or replace the one already holding `options.id`) and return its id. */
+    show: (message: string, options?: ToastOptions, variant?: ToastVariant) => string;
+    info: (message: string, options?: ToastOptions) => string;
+    success: (message: string, options?: ToastOptions) => string;
+    warning: (message: string, options?: ToastOptions) => string;
+    error: (message: string, options?: ToastOptions) => string;
+    /** Remove one toast. Unknown ids are ignored, so a caller may dismiss twice. */
+    dismiss: (id: string) => void;
+    /** Empty the queue. Useful on sign-out or on a navigation that invalidates every message. */
+    clear: () => void;
+    /**
+     * Freeze a toast's countdown. `Toaster` calls this on hover and on focus so a toast cannot
+     * vanish while it is being read or while its dismiss button is the focused element.
+     */
+    pause: (id: string) => void;
+    /** Resume a frozen countdown from where `pause` left it. */
+    resume: (id: string) => void;
+}
+export declare const createToastManager: (options?: ToastManagerOptions) => ToastManager;
+/**
+ * The manager backing the module-level `toast` helper.
+ *
+ * A singleton only in the browser. On the server every call hands back a fresh manager, because
+ * a module-level queue there is shared by every concurrent request — one user's toast would be
+ * rendered into another user's HTML.
+ */
+export declare const getDefaultToastManager: () => ToastManager;
+export interface ToastApi {
+    show: (message: string, options?: ToastOptions, variant?: ToastVariant) => string;
+    info: (message: string, options?: ToastOptions) => string;
+    success: (message: string, options?: ToastOptions) => string;
+    warning: (message: string, options?: ToastOptions) => string;
+    error: (message: string, options?: ToastOptions) => string;
+    dismiss: (id: string) => void;
+    clear: () => void;
+    pause: (id: string) => void;
+    resume: (id: string) => void;
+}
+/**
+ * The ergonomic entry point: `toast.error("Could not save")` from anywhere, with no context to
+ * plumb and no import of the manager.
+ *
+ * Each call resolves the default manager rather than capturing it, so importing this module on
+ * the server never creates the browser singleton.
+ */
+export declare const toast: ToastApi;

package/dist/toast/toast-manager.svelte.js

@@ -0,0 +1,176 @@
+/** Errors and warnings linger: they carry something the reader has to act on. */
+const DEFAULT_DURATIONS = {
+    info: 4000,
+    success: 3000,
+    warning: 5000,
+    error: 5000,
+};
+const DEFAULT_LIMIT = 5;
+let nextSequence = 0;
+const createToastId = () => `toast-${++nextSequence}`;
+/**
+ * The queue behind `Toaster`. Owns ids, ordering, the stack cap and every auto-dismiss timer.
+ *
+ * Most apps never touch this class: `toast.success(...)` goes through the process-wide default
+ * manager, and a single `<Toaster />` near the app root renders it. Construct one explicitly to
+ * scope a queue to a subtree, or to give a test a manager it can throw away afterwards.
+ */
+export class ToastManager {
+    #toasts = $state([]);
+    #limit;
+    #durations;
+    // A plain Map, not `SvelteMap`: nothing renders from the clocks, so reactivity here would be
+    // pure overhead. The rendered surface is `#toasts` and nothing else.
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity
+    #clocks = new Map();
+    constructor({ limit = DEFAULT_LIMIT, durations } = {}) {
+        this.#limit = Math.max(1, limit);
+        this.#durations = { ...DEFAULT_DURATIONS, ...durations };
+    }
+    /** Oldest first. Read-only by contract — every mutation goes through a method. */
+    get toasts() {
+        return this.#toasts;
+    }
+    /** Push a toast (or replace the one already holding `options.id`) and return its id. */
+    show = (message, options = {}, variant = "info") => {
+        const id = options.id ?? createToastId();
+        const existing = this.#toasts.find((toast) => toast.id === id);
+        const next = {
+            id,
+            variant,
+            message,
+            description: options.description,
+            duration: options.duration ?? this.#durations[variant],
+            dismissible: options.dismissible ?? true,
+            createdAt: existing?.createdAt ?? Date.now(),
+        };
+        this.#upsert(next);
+        this.#enforceLimit();
+        this.#restartClock(next);
+        return id;
+    };
+    info = (message, options) => this.show(message, options, "info");
+    success = (message, options) => this.show(message, options, "success");
+    warning = (message, options) => this.show(message, options, "warning");
+    error = (message, options) => this.show(message, options, "error");
+    /** Remove one toast. Unknown ids are ignored, so a caller may dismiss twice. */
+    dismiss = (id) => {
+        this.#remove(id);
+    };
+    /** Empty the queue. Useful on sign-out or on a navigation that invalidates every message. */
+    clear = () => {
+        for (const clock of this.#clocks.values())
+            if (clock.handle)
+                clearTimeout(clock.handle);
+        this.#clocks.clear();
+        this.#toasts = [];
+    };
+    /**
+     * Freeze a toast's countdown. `Toaster` calls this on hover and on focus so a toast cannot
+     * vanish while it is being read or while its dismiss button is the focused element.
+     */
+    pause = (id) => {
+        const clock = this.#clocks.get(id);
+        if (!clock || clock.paused)
+            return;
+        clock.paused = true;
+        if (clock.handle === null)
+            return;
+        clearTimeout(clock.handle);
+        clock.handle = null;
+        clock.remainingMs = Math.max(0, (clock.deadline ?? Date.now()) - Date.now());
+        clock.deadline = null;
+    };
+    /** Resume a frozen countdown from where `pause` left it. */
+    resume = (id) => {
+        const clock = this.#clocks.get(id);
+        if (!clock)
+            return;
+        clock.paused = false;
+        this.#start(id);
+    };
+    #upsert(toast) {
+        const index = this.#toasts.findIndex((current) => current.id === toast.id);
+        if (index === -1)
+            this.#toasts.push(toast);
+        else
+            this.#toasts[index] = toast;
+    }
+    #enforceLimit() {
+        // Drop from the front: the newest toast was just appended, and it is the one the caller
+        // actually wants seen.
+        while (this.#toasts.length > this.#limit)
+            this.#remove(this.#toasts[0].id);
+    }
+    #remove(id) {
+        const clock = this.#clocks.get(id);
+        if (clock?.handle)
+            clearTimeout(clock.handle);
+        this.#clocks.delete(id);
+        this.#toasts = this.#toasts.filter((toast) => toast.id !== id);
+    }
+    #restartClock(toast) {
+        const previous = this.#clocks.get(toast.id);
+        if (previous?.handle)
+            clearTimeout(previous.handle);
+        this.#clocks.set(toast.id, {
+            handle: null,
+            sticky: !Number.isFinite(toast.duration) || toast.duration <= 0,
+            remainingMs: toast.duration,
+            deadline: null,
+            // An update that lands while the pointer rests on the toast (a retry turning an error into
+            // a success) must stay frozen; starting a fresh countdown under the cursor would take the
+            // message away without the reader ever leaving it.
+            paused: previous?.paused ?? false,
+        });
+        this.#start(toast.id);
+    }
+    #start(id) {
+        const clock = this.#clocks.get(id);
+        if (!clock || clock.paused || clock.sticky || clock.handle !== null)
+            return;
+        // Only reachable when a pause landed exactly on the deadline: the countdown is spent, so the
+        // toast has already earned its exit.
+        if (clock.remainingMs <= 0) {
+            this.#remove(id);
+            return;
+        }
+        clock.deadline = Date.now() + clock.remainingMs;
+        clock.handle = setTimeout(() => {
+            this.#remove(id);
+        }, clock.remainingMs);
+    }
+}
+export const createToastManager = (options) => new ToastManager(options);
+let browserManager = null;
+/**
+ * The manager backing the module-level `toast` helper.
+ *
+ * A singleton only in the browser. On the server every call hands back a fresh manager, because
+ * a module-level queue there is shared by every concurrent request — one user's toast would be
+ * rendered into another user's HTML.
+ */
+export const getDefaultToastManager = () => {
+    if (typeof document === "undefined")
+        return createToastManager();
+    browserManager ??= createToastManager();
+    return browserManager;
+};
+/**
+ * The ergonomic entry point: `toast.error("Could not save")` from anywhere, with no context to
+ * plumb and no import of the manager.
+ *
+ * Each call resolves the default manager rather than capturing it, so importing this module on
+ * the server never creates the browser singleton.
+ */
+export const toast = {
+    show: (message, options, variant) => getDefaultToastManager().show(message, options, variant),
+    info: (message, options) => getDefaultToastManager().info(message, options),
+    success: (message, options) => getDefaultToastManager().success(message, options),
+    warning: (message, options) => getDefaultToastManager().warning(message, options),
+    error: (message, options) => getDefaultToastManager().error(message, options),
+    dismiss: (id) => getDefaultToastManager().dismiss(id),
+    clear: () => getDefaultToastManager().clear(),
+    pause: (id) => getDefaultToastManager().pause(id),
+    resume: (id) => getDefaultToastManager().resume(id),
+};

package/dist/user/ScopedComponent.svelte

@@ -0,0 +1,47 @@
+<script lang="ts">
+  import type { Snippet } from "svelte";
+  import { getUserContext } from "./context.js";
+
+  interface Props {
+    /** Roles the user must hold. An empty list is an open gate. */
+    roles: readonly string[];
+    /** Require every role instead of at least one. */
+    requiresAll?: boolean;
+    children: Snippet;
+    /** Rendered instead of `children` when the check fails. Nothing renders without it. */
+    fallback?: Snippet;
+  }
+
+  let { roles, requiresAll = false, children, fallback }: Props = $props();
+
+  const user = getUserContext();
+
+  // Reading the check inside `$derived` rather than at init is what makes the gate follow a
+  // sign-in: the user context is expected to be reactive, so this re-runs when its status or
+  // roles change and the subtree appears without a remount.
+  const allowed = $derived(requiresAll ? user.hasAllRoles(roles) : user.hasAnyRole(roles));
+</script>
+
+<!--
+@component
+Renders its children only for a user holding the required roles.
+
+The check delegates entirely to the `UserContext` in scope; with no context set, the anonymous
+default lets everything through, so a gated subtree still renders in an app that has no
+authentication yet.
+
+```svelte
+<ScopedComponent roles={["orders:write"]}>
+  <button>Approve</button>
+  {#snippet fallback()}
+    <span class="opacity-50">Read-only</span>
+  {/snippet}
+</ScopedComponent>
+```
+-->
+
+{#if allowed}
+  {@render children()}
+{:else if fallback}
+  {@render fallback()}
+{/if}

package/dist/user/ScopedComponent.svelte.d.ts

@@ -0,0 +1,29 @@
+import type { Snippet } from "svelte";
+interface Props {
+    /** Roles the user must hold. An empty list is an open gate. */
+    roles: readonly string[];
+    /** Require every role instead of at least one. */
+    requiresAll?: boolean;
+    children: Snippet;
+    /** Rendered instead of `children` when the check fails. Nothing renders without it. */
+    fallback?: Snippet;
+}
+/**
+ * Renders its children only for a user holding the required roles.
+ *
+ * The check delegates entirely to the `UserContext` in scope; with no context set, the anonymous
+ * default lets everything through, so a gated subtree still renders in an app that has no
+ * authentication yet.
+ *
+ * ```svelte
+ * <ScopedComponent roles={["orders:write"]}>
+ * <button>Approve</button>
+ * {#snippet fallback()}
+ *   <span class="opacity-50">Read-only</span>
+ * {/snippet}
+ * </ScopedComponent>
+ * ```
+ */
+declare const ScopedComponent: import("svelte").Component<Props, {}, "">;
+type ScopedComponent = ReturnType<typeof ScopedComponent>;
+export default ScopedComponent;

package/dist/user/anonymous.d.ts

@@ -0,0 +1,21 @@
+import type { UserContext } from "./context.js";
+/**
+ * The user context in force until an app installs its own.
+ *
+ * Nobody is signed in, and every role check answers `true`. That reads backwards for something
+ * whose job is to deny, so it is worth being explicit about why it is the right default.
+ *
+ * A role gate is a *statement about the app's intent*, not a security control — the server is
+ * what actually refuses to serve the data. So the question is only what an unauthenticated
+ * library should do with an intent it has no way to evaluate. Denying would mean a route tree
+ * annotated with `requiredRoles` renders as an empty shell the moment you clone it, and the
+ * annotation would have to be commented out to develop against it. Allowing makes the gates
+ * advisory: they sit in the config, describing the eventual policy, doing nothing, until the
+ * day the app calls `setUserContext` with something that can actually answer. From that call
+ * on, every gate is live at once, with no other edit.
+ *
+ * The failure mode of the opposite choice — an app that ships without ever setting a context
+ * and hides its own UI — is silent and confusing. This one is loud: everything is visible,
+ * `status` says `"anonymous"`, and nothing pretends a user exists.
+ */
+export declare const anonymousUser: UserContext;