@xforge-dev/forge-kit 0.0.0-stage → 0.15.0

package/README.md

@@ -1,3 +1,132 @@
-# Temporary Holding Version
+# @xforge-dev/forge-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared auth, app registry and UI for xForge apps (`*.xforge.dev`).
+
+```ts
+import { accountUrl, resolveNext, FORGE_APPS } from '@xforge-dev/forge-kit';
+import { createForgeServerClient, updateForgeSession } from '@xforge-dev/forge-kit/server';
+import { AppSwitcher, GuestBanner, useForgeUser } from '@xforge-dev/forge-kit/client';
+```
+
+Env: `NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` (`sb_publishable_…`),
+`NEXT_PUBLIC_FORGE_COOKIE_DOMAIN` (`.xforge.dev` in production, empty locally),
+`NEXT_PUBLIC_FORGE_ACCOUNT_URL` (defaults to `https://accounts.xforge.dev`).
+
+Without both Supabase vars, `isForgeAuthConfigured()` returns `false`: `useForgeUser` reports a
+signed-out user without loading, `updateForgeSession` returns `user: null` and `supabase: null`,
+and the client factories throw a clear error. Apps can therefore run guest-only.
+
+## Tailwind 4
+
+Add an `@source` line to your `globals.css`. The path is relative to that file:
+
+- `app/globals.css`: `@source "../node_modules/@xforge-dev/forge-kit/dist";`
+- `src/app/globals.css`: `@source "../../node_modules/@xforge-dev/forge-kit/dist";`
+
+## Design tokens and font
+
+Every app takes its palette, the 12 colour themes, radii, dark variant and base styles from the
+kit. Import the tokens right after Tailwind, and keep only app-specific tokens in `globals.css`:
+
+```css
+@import "tailwindcss";
+@import "@xforge-dev/forge-kit/tokens.css";
+@source "../node_modules/@xforge-dev/forge-kit/dist";
+```
+
+Colours are full `hsl()` values: use `var(--primary)` directly and `color-mix()` for alpha, never
+`hsl(var(--primary))`. The body font is Rubik, loaded by each app (next/font can't run from a
+package) into `--font-forge-sans`:
+
+```tsx
+import { Rubik } from 'next/font/google';
+const forgeSans = Rubik({ subsets: ['latin'], variable: '--font-forge-sans', display: 'swap' });
+<html className={forgeSans.variable}>
+```
+
+Shared component sizes, so the apps feel the same: buttons and inputs 36px (`h-9`), inputs use
+`text-base md:text-sm` (16px on phones, so iOS doesn't zoom), cards and dialogs `rounded-xl`.
+
+## Showing the banner and switcher
+
+```tsx
+const { user, account, loading } = useForgeUser();
+
+<GuestBanner appId="legion" appName="LegionForge" signedIn={loading ? undefined : !!user} />
+<AppSwitcher account={account} … />
+```
+
+`signedIn={undefined}` means auth state is unknown, so the banner renders nothing until it resolves.
+
+## Header, account panel and theme
+
+Every app uses the same header so switching apps feels seamless:
+
+```tsx
+// layout.tsx
+import { forgeThemeScript } from '@xforge-dev/forge-kit';
+<head><script dangerouslySetInnerHTML={{ __html: forgeThemeScript }} /></head>
+<ForgeThemeProvider onChange={…}>{children}</ForgeThemeProvider>
+
+// header
+<ForgeHeader
+  current="boss"
+  account={account}
+  nav={[{ href: '/parties', label: 'Parties', icon: Users, active: true }]}
+  actions={<ForgeSupportButton />}
+  panel={<ForgePanelSection title="Screensaver">…</ForgePanelSection>}
+/>
+```
+
+The avatar opens a side panel with the account links, the page links on mobile, Appearance
+(dark mode, color theme, "Same theme in all xForge apps") and then the app's own sections.
+Build those from `ForgePanelSection`, `ForgePanelItem` and `ForgeSwitchRow`.
+Under the username the panel shows the account's supporter badge and Discord name (from
+`ForgeAccount.supporterTier` / `discordUsername`, which `useForgeUser` reads from `profiles`), then
+the app's `accountDetails`.
+
+Themes live in localStorage (`theme-mode`, `theme-color`) and, while syncing (the default,
+opt out per app with `forge-theme-sync=false`), in the `forge-theme` cookie on
+`NEXT_PUBLIC_FORGE_COOKIE_DOMAIN`. Apps must define CSS for every `FORGE_COLOR_THEMES` name under
+`html[data-color="…"]`. Call `storeForgeTheme()` when something other than the provider changes
+the theme (an account sync or an import) so the shared copy follows.
+
+## Support button
+
+`ForgeSupportButton` is the header heart that opens the shared "show your support" dialog with
+the Buy Me a Coffee button and the supporter badge tiers (`FORGE_SPONSOR_TIERS`). Children render
+after the tiers for anything app-specific. The button image loads from `https://cdn.buymeacoffee.com`, so add that to the app's CSP
+`img-src`.
+
+## Security headers
+
+`forgeSecurityHeaders(extra, { dev })` returns the family's headers and CSP; pass app-specific
+sources in `extra`. The policy allows no scripts from other origins: every Forge subdomain shares
+the sign-in cookie, so a third-party script on one can read every user's session. For analytics,
+apps add Vercel Web Analytics (`<Analytics />` from `@vercel/analytics/next` in the root layout);
+it loads from the app's own origin, so the policy needs no extra sources.
+
+## Exports
+
+`isForgeAuthConfigured` is exported from the root and `/client` entry points.
+
+## Proxy notes
+
+Do not write cookies through the `supabase` client returned by `updateForgeSession` after it
+returns. Writes made later are not reflected in the returned `response`.
+
+## Moving off xtherebellion.com
+
+The apps moved from `*.xtherebellion.com` to `*.xforge.dev`. Each app's proxy calls
+`forgeLegacyResponse(request)` first. On an old host, a browser navigation gets a small
+page that carries the origin's localStorage and readable cookies (never the Supabase
+session) to `/__forge/handoff` on the new host, in the URL fragment; everything else
+(API calls, crawlers) gets a 308. The receiving page, answered by the same call before
+any auth redirect, imports only what the new origin doesn't have, and only when the
+referrer is that origin's old host, then goes on to the original path.
+
+```ts
+// proxy.ts
+const legacy = forgeLegacyResponse(request);
+if (legacy) return legacy;
+```

package/dist/account-url.d.ts

@@ -0,0 +1,5 @@
+export declare const ACCOUNT_ORIGIN: string;
+export type AccountPath = '/' | '/login' | '/register' | '/logout' | '/reset-password';
+export declare function accountUrl(path: AccountPath, opts?: {
+    next?: string;
+}, origin?: string): string;

package/dist/account-url.js

@@ -0,0 +1,7 @@
+export const ACCOUNT_ORIGIN = process.env.NEXT_PUBLIC_FORGE_ACCOUNT_URL || 'https://accounts.xforge.dev';
+export function accountUrl(path, opts = {}, origin = ACCOUNT_ORIGIN) {
+    const url = new URL(path, origin);
+    if (opts.next)
+        url.searchParams.set('next', opts.next);
+    return url.toString();
+}

package/dist/app-switcher.d.ts

@@ -0,0 +1,12 @@
+import { type ForgeAppId } from './apps.js';
+import type { ForgeAccount } from './use-forge-user.js';
+export type AppSwitcherProps = {
+    current?: ForgeAppId;
+    account: ForgeAccount | null;
+    syncError?: boolean;
+    /** Show the account and sign-in items; ForgeHeader turns this off because its avatar panel has them. */
+    showAccount?: boolean;
+    /** Override for tests; defaults to the live page URL. */
+    currentUrl?: string;
+};
+export declare function AppSwitcher({ current, account, syncError, showAccount, currentUrl }: AppSwitcherProps): import("react").JSX.Element;

package/dist/app-switcher.js

@@ -0,0 +1,19 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as Menu from '@radix-ui/react-dropdown-menu';
+import { Check, ChevronDown, LogIn, LogOut, UserRound } from 'lucide-react';
+import { accountUrl } from './account-url.js';
+import { FORGE_APPS } from './apps.js';
+import { ForgeLogo } from './forge-logo.js';
+import { useCurrentUrl } from './use-current-url.js';
+const item = 'flex cursor-pointer select-none items-center gap-3 rounded-sm px-2 py-2 text-sm outline-hidden focus:bg-accent focus:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50';
+export function AppSwitcher({ current, account, syncError, showAccount = true, currentUrl }) {
+    const currentApp = FORGE_APPS.find((a) => a.id === current);
+    const liveUrl = useCurrentUrl(currentApp?.url ?? accountUrl('/'));
+    const next = currentUrl ?? liveUrl;
+    return (_jsxs(Menu.Root, { children: [_jsxs(Menu.Trigger, { className: "flex items-center gap-2 rounded-md px-2 py-1 font-semibold hover:bg-accent focus-visible:outline-2 focus-visible:outline-ring", children: [_jsx(ForgeLogo, { brand: currentApp?.id ?? 'xforge', variant: "icon", className: "h-8", alt: "" }), _jsx("span", { children: currentApp?.name ?? 'xForge' }), _jsx(ChevronDown, { className: "h-4 w-4 text-muted-foreground" }), syncError && (_jsx("span", { role: "img", "aria-label": "Not synced", title: "Not synced", className: "h-2 w-2 rounded-full bg-destructive" }))] }), _jsx(Menu.Portal, { children: _jsxs(Menu.Content, { align: "start", sideOffset: 6, className: "z-50 w-72 rounded-md border bg-popover p-1 text-popover-foreground shadow-md", children: [_jsxs(Menu.Label, { className: "flex items-center gap-2 px-2 py-1.5 text-xs font-medium text-muted-foreground", children: [_jsx(ForgeLogo, { brand: "xforge", variant: "icon", className: "h-4", alt: "" }), "xForge apps"] }), FORGE_APPS.map((app) => {
+                            const isCurrent = app.id === current;
+                            const disabled = app.status === 'soon';
+                            return (_jsx(Menu.Item, { asChild: true, disabled: disabled, children: _jsxs("a", { href: disabled ? undefined : app.url, "aria-current": isCurrent ? 'page' : undefined, className: item, children: [_jsx(ForgeLogo, { brand: app.id, variant: "icon", className: "h-9 shrink-0", alt: "" }), _jsxs("span", { className: "flex-1", children: [_jsx("span", { className: "block font-medium", children: app.name }), _jsx("span", { className: "block text-xs text-muted-foreground", children: disabled ? 'Coming soon' : app.description })] }), isCurrent && _jsx(Check, { className: "h-4 w-4" })] }) }, app.id));
+                        }), showAccount && _jsx(Menu.Separator, { className: "-mx-1 my-1 h-px bg-border" }), !showAccount ? null : account ? (_jsxs(_Fragment, { children: [_jsxs("div", { className: "flex items-center gap-2 px-2 py-1.5 text-sm", children: [account.avatarUrl ? (_jsx("img", { src: account.avatarUrl, alt: "", className: "h-6 w-6 rounded-full" })) : (_jsx(UserRound, { className: "h-5 w-5" })), _jsx("span", { className: "font-medium", children: account.username })] }), _jsx(Menu.Item, { asChild: true, children: _jsxs("a", { href: accountUrl('/'), className: item, children: [_jsx(UserRound, { className: "h-4 w-4" }), " xForge account"] }) }), _jsx(Menu.Item, { asChild: true, children: _jsxs("a", { href: accountUrl('/logout', { next }), className: item, children: [_jsx(LogOut, { className: "h-4 w-4" }), " Sign out"] }) })] })) : (_jsx(Menu.Item, { asChild: true, children: _jsxs("a", { href: accountUrl('/login', { next }), className: item, children: [_jsx(LogIn, { className: "h-4 w-4" }), " Sign in / Create account"] }) }))] }) })] }));
+}

package/dist/apps.d.ts

@@ -0,0 +1,12 @@
+export type ForgeAppId = 'boss' | 'legion' | 'cards' | 'fams';
+export type ForgeApp = {
+    id: ForgeAppId;
+    name: string;
+    url: string;
+    description: string;
+    status: 'live' | 'soon';
+    /** Where "Continue without an account" lands, for apps that gate guest mode. */
+    guestPath?: string;
+};
+export declare const FORGE_APPS: readonly ForgeApp[];
+export declare function appForUrl(url: string): ForgeApp | undefined;

package/dist/apps.js

@@ -0,0 +1,41 @@
+export const FORGE_APPS = [
+    {
+        id: 'boss',
+        name: 'BossForge',
+        url: 'https://boss.xforge.dev',
+        description: 'Organize boss parties across time zones',
+        status: 'live',
+        guestPath: '/auth/guest',
+    },
+    {
+        id: 'legion',
+        name: 'LegionForge',
+        url: 'https://legion.xforge.dev',
+        description: 'Track your Legion and character progress',
+        status: 'live',
+    },
+    {
+        id: 'cards',
+        name: 'CardForge',
+        url: 'https://cards.xforge.dev',
+        description: 'Design trading cards for your characters',
+        status: 'live',
+    },
+    {
+        id: 'fams',
+        name: 'FamiliarForge',
+        url: 'https://fams.xforge.dev',
+        description: 'Track your familiar cards and badges',
+        status: 'live',
+    },
+];
+export function appForUrl(url) {
+    let origin;
+    try {
+        origin = new URL(url).origin;
+    }
+    catch {
+        return undefined;
+    }
+    return FORGE_APPS.find((app) => app.url === origin);
+}

package/dist/banner-storage.d.ts

@@ -0,0 +1,4 @@
+import type { ForgeAppId } from './apps.js';
+export declare const bannerKey: (appId: ForgeAppId) => string;
+export declare function isBannerDismissed(appId: ForgeAppId, storage?: Storage | null): boolean;
+export declare function dismissBanner(appId: ForgeAppId, storage?: Storage | null): void;

package/dist/banner-storage.js

@@ -0,0 +1,25 @@
+export const bannerKey = (appId) => `forge-guest-banner-dismissed:${appId}`;
+function defaultStorage() {
+    try {
+        return typeof window === 'undefined' ? null : window.localStorage;
+    }
+    catch {
+        return null;
+    }
+}
+export function isBannerDismissed(appId, storage = defaultStorage()) {
+    try {
+        return storage?.getItem(bannerKey(appId)) === '1';
+    }
+    catch {
+        return false;
+    }
+}
+export function dismissBanner(appId, storage = defaultStorage()) {
+    try {
+        storage?.setItem(bannerKey(appId), '1');
+    }
+    catch {
+        // Storage unavailable: the banner just comes back next visit.
+    }
+}

package/dist/brand.d.ts

@@ -0,0 +1,14 @@
+import type { ForgeAppId } from './apps.js';
+export type ForgeBrandId = ForgeAppId | 'xforge';
+export type ForgeBrand = {
+    name: string;
+    /** Square mark. */
+    icon: string;
+    /** Mark plus wordmark; `light` reads best on light backgrounds, `dark` on dark ones. */
+    logo: {
+        light: string;
+        dark: string;
+    };
+};
+export declare const FORGE_CDN = "https://cdn.xforge.dev";
+export declare const FORGE_BRANDS: Record<ForgeBrandId, ForgeBrand>;

package/dist/brand.js

@@ -0,0 +1,18 @@
+export const FORGE_CDN = 'https://cdn.xforge.dev';
+/** Bump after replacing files on the CDN so browsers and Cloudflare fetch the new art. */
+const BRAND_VERSION = '3';
+function brand(name, slug) {
+    const file = (path) => `${FORGE_CDN}/apps/${slug}/${path}?v=${BRAND_VERSION}`;
+    return {
+        name,
+        icon: file(`icons/${slug}-icon.png`),
+        logo: { light: file(`logos/${slug}-light.png`), dark: file(`logos/${slug}-dark.png`) },
+    };
+}
+export const FORGE_BRANDS = {
+    xforge: brand('xForge', 'xforge'),
+    boss: brand('BossForge', 'bossforge'),
+    legion: brand('LegionForge', 'legionforge'),
+    cards: brand('CardForge', 'cardforge'),
+    fams: brand('FamiliarForge', 'familiarforge'),
+};

package/dist/browser-client.d.ts

@@ -0,0 +1,2 @@
+import type { SupabaseClient } from '@supabase/supabase-js';
+export declare function createForgeBrowserClient(): SupabaseClient;

package/dist/browser-client.js

@@ -0,0 +1,11 @@
+import { createBrowserClient } from '@supabase/ssr';
+import { requireForgeAuthEnv } from './config.js';
+import { forgeCookieOptions } from './cookies.js';
+let client;
+export function createForgeBrowserClient() {
+    if (!client) {
+        const { url, key } = requireForgeAuthEnv();
+        client = createBrowserClient(url, key, { cookieOptions: forgeCookieOptions() });
+    }
+    return client;
+}

package/dist/client.d.ts

@@ -0,0 +1,13 @@
+export { AppSwitcher, type AppSwitcherProps } from './app-switcher.js';
+export { GuestBanner, type GuestBannerProps } from './guest-banner.js';
+export { useForgeUser, toForgeAccount, type ForgeAccount } from './use-forge-user.js';
+export { createForgeBrowserClient } from './browser-client.js';
+export { dismissBanner, isBannerDismissed, bannerKey } from './banner-storage.js';
+export { useCurrentUrl } from './use-current-url.js';
+export { isForgeAuthConfigured } from './config.js';
+export { ForgeThemeProvider, useForgeTheme, resolveTheme, storeForgeTheme, type ForgeThemeContext, type ForgeThemeProviderProps, } from './theme-provider.js';
+export { ForgeHeader, ForgeAvatar, ForgePanelSection, ForgePanelItem, ForgeSwitchRow, DiscordIcon, type ForgeHeaderProps, type ForgeNavItem, type ForgePanelItemProps, } from './forge-header.js';
+export * from './theme.js';
+export { ForgeLogo, type ForgeLogoProps } from './forge-logo.js';
+export { ForgeSupportButton, BUY_ME_A_COFFEE_URL, BUY_ME_A_COFFEE_BUTTON, FORGE_SPONSOR_TIERS, ForgeSupporterBadge, type ForgeSupporterTier, type ForgeSupportButtonProps, } from './support-button.js';
+export { ForgeIgnInput, FORGE_ACCENTED_LETTERS, FORGE_NO_AUTOFILL, type ForgeIgnInputProps, } from './ign-input.js';

package/dist/client.js

@@ -0,0 +1,14 @@
+'use client';
+export { AppSwitcher } from './app-switcher.js';
+export { GuestBanner } from './guest-banner.js';
+export { useForgeUser, toForgeAccount } from './use-forge-user.js';
+export { createForgeBrowserClient } from './browser-client.js';
+export { dismissBanner, isBannerDismissed, bannerKey } from './banner-storage.js';
+export { useCurrentUrl } from './use-current-url.js';
+export { isForgeAuthConfigured } from './config.js';
+export { ForgeThemeProvider, useForgeTheme, resolveTheme, storeForgeTheme, } from './theme-provider.js';
+export { ForgeHeader, ForgeAvatar, ForgePanelSection, ForgePanelItem, ForgeSwitchRow, DiscordIcon, } from './forge-header.js';
+export * from './theme.js';
+export { ForgeLogo } from './forge-logo.js';
+export { ForgeSupportButton, BUY_ME_A_COFFEE_URL, BUY_ME_A_COFFEE_BUTTON, FORGE_SPONSOR_TIERS, ForgeSupporterBadge, } from './support-button.js';
+export { ForgeIgnInput, FORGE_ACCENTED_LETTERS, FORGE_NO_AUTOFILL, } from './ign-input.js';

package/dist/config.d.ts

@@ -0,0 +1,8 @@
+export declare const AUTH_NOT_CONFIGURED_MESSAGE = "xForge auth is not configured: set NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY";
+/** True iff the Supabase URL and publishable key are set. */
+export declare function isForgeAuthConfigured(): boolean;
+/** Returns the Supabase credentials or throws a clear error. */
+export declare function requireForgeAuthEnv(): {
+    url: string;
+    key: string;
+};

package/dist/config.js

@@ -0,0 +1,17 @@
+export const AUTH_NOT_CONFIGURED_MESSAGE = 'xForge auth is not configured: set NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY';
+/** The Supabase publishable key (`sb_publishable_…`), referenced literally so Next inlines it. */
+function publishableKey() {
+    return process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY;
+}
+/** True iff the Supabase URL and publishable key are set. */
+export function isForgeAuthConfigured() {
+    return !!process.env.NEXT_PUBLIC_SUPABASE_URL && !!publishableKey();
+}
+/** Returns the Supabase credentials or throws a clear error. */
+export function requireForgeAuthEnv() {
+    const url = process.env.NEXT_PUBLIC_SUPABASE_URL;
+    const key = publishableKey();
+    if (!url || !key)
+        throw new Error(AUTH_NOT_CONFIGURED_MESSAGE);
+    return { url, key };
+}

package/dist/cookies.d.ts

@@ -0,0 +1,11 @@
+export type ForgeCookieOptions = {
+    domain?: string;
+    path: '/';
+    sameSite: 'lax';
+    secure: boolean;
+};
+/**
+ * Every Forge app must use identical options or the browser ends up holding
+ * two auth cookies with the same name on different scopes.
+ */
+export declare function forgeCookieOptions(domain?: string | undefined): ForgeCookieOptions;

package/dist/cookies.js

@@ -0,0 +1,9 @@
+/**
+ * Every Forge app must use identical options or the browser ends up holding
+ * two auth cookies with the same name on different scopes.
+ */
+export function forgeCookieOptions(domain = process.env.NEXT_PUBLIC_FORGE_COOKIE_DOMAIN) {
+    return domain
+        ? { domain, path: '/', sameSite: 'lax', secure: true }
+        : { path: '/', sameSite: 'lax', secure: false };
+}

package/dist/forge-header.d.ts

@@ -0,0 +1,76 @@
+import { type ComponentPropsWithRef, type ReactNode } from 'react';
+import { type LucideIcon } from 'lucide-react';
+import { type ForgeAppId } from './apps.js';
+import type { ForgeAccount } from './use-forge-user.js';
+export type ForgeNavItem = {
+    href: string;
+    label: string;
+    icon?: LucideIcon;
+    active?: boolean;
+};
+export type ForgeHeaderProps = {
+    current?: ForgeAppId;
+    account: ForgeAccount | null;
+    syncError?: boolean;
+    /** Page links: inline on desktop, in the account panel on mobile. */
+    nav?: ForgeNavItem[];
+    /** Header buttons shown left of the avatar. */
+    actions?: ReactNode;
+    /** Shown in the panel under the username, supporter badge and Discord name (e.g. time zone). */
+    accountDetails?: ReactNode;
+    /** Replaces the panel's name and details for guests. */
+    guestDetails?: ReactNode;
+    /** Extra items in the panel's account section, after the built-in ones. */
+    accountActions?: ReactNode;
+    /** App sections in the panel, after Appearance. Build them from `ForgePanelSection`. */
+    panel?: ReactNode;
+    /** Runs before navigating to sign out, e.g. to flush unsaved data. */
+    onBeforeSignOut?: () => Promise<void> | void;
+    /** Width of the header's inner row; defaults to `max-w-6xl`. */
+    containerClassName?: string;
+    /** Override for tests; defaults to the live page URL. */
+    currentUrl?: string;
+};
+/**
+ * The header every xForge app shares: app switcher, page links, app buttons,
+ * and an avatar that opens the account panel with the theme settings.
+ */
+export declare function ForgeHeader({ current, account, syncError, nav, actions, accountDetails, guestDetails, accountActions, panel, onBeforeSignOut, containerClassName, currentUrl, }: ForgeHeaderProps): import("react").JSX.Element;
+export declare function ForgeAvatar({ account, className }: {
+    account: ForgeAccount | null;
+    className?: string;
+}): import("react").JSX.Element;
+/** Discord's mark in `currentColor`; give it Discord's blurple (`text-[#5865F2]`) next to a Discord name. */
+export declare function DiscordIcon({ className }: {
+    className?: string;
+}): import("react").JSX.Element;
+/** A titled group in the account panel. */
+export declare function ForgePanelSection({ title, description, children, }: {
+    title: string;
+    description?: ReactNode;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export type ForgePanelItemProps = {
+    icon?: LucideIcon;
+    label: ReactNode;
+    description?: ReactNode;
+    /** In-app path (client navigation) or, with `external`, a full URL. */
+    href?: string;
+    external?: boolean;
+    onClick?: () => void;
+    disabled?: boolean;
+    active?: boolean;
+    tone?: 'default' | 'destructive';
+    /** Keep the panel open after clicking (default closes it), e.g. to open a dialog from it. */
+    keepOpen?: boolean;
+} & Omit<ComponentPropsWithRef<'button'>, 'children' | 'onClick' | 'disabled'>;
+/** A row in the account panel: a link or a button that closes the panel. */
+export declare function ForgePanelItem({ icon: Icon, label, description, href, external, onClick, disabled, active, tone, keepOpen, className: extraClassName, ...buttonProps }: ForgePanelItemProps): import("react").JSX.Element;
+/** A labelled on/off switch row for panel sections. */
+export declare function ForgeSwitchRow({ icon: Icon, label, description, checked, onCheckedChange, }: {
+    icon?: LucideIcon;
+    label: ReactNode;
+    description?: ReactNode;
+    checked: boolean;
+    onCheckedChange: (checked: boolean) => void;
+}): import("react").JSX.Element;

package/dist/forge-header.js

@@ -0,0 +1,75 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as Dialog from '@radix-ui/react-dialog';
+import Link from 'next/link.js';
+import { useState } from 'react';
+import { ExternalLink, LogIn, LogOut, Moon, RefreshCw, Sun, UserRound, X } from 'lucide-react';
+import { accountUrl } from './account-url.js';
+import { AppSwitcher } from './app-switcher.js';
+import { FORGE_APPS } from './apps.js';
+import { ForgeSupporterBadge } from './support-button.js';
+import { FORGE_COLOR_THEMES } from './theme.js';
+import { useForgeTheme } from './theme-provider.js';
+import { useCurrentUrl } from './use-current-url.js';
+/**
+ * The header every xForge app shares: app switcher, page links, app buttons,
+ * and an avatar that opens the account panel with the theme settings.
+ */
+export function ForgeHeader({ current, account, syncError, nav = [], actions, accountDetails, guestDetails, accountActions, panel, onBeforeSignOut, containerClassName = 'max-w-6xl', currentUrl, }) {
+    const [open, setOpen] = useState(false);
+    return (_jsx("header", { className: "sticky top-0 z-40 w-full border-b bg-background/95 backdrop-blur supports-backdrop-filter:bg-background/80", children: _jsxs("div", { className: `mx-auto flex h-14 w-full items-center gap-2 px-4 sm:gap-4 ${containerClassName}`, children: [_jsx(AppSwitcher, { current: current, account: account, showAccount: false, currentUrl: currentUrl }), _jsx("nav", { className: "hidden flex-1 items-center gap-1 sm:flex", children: nav.map(({ href, label, active }) => (_jsx(Link, { href: href, "aria-current": active ? 'page' : undefined, className: active
+                            ? 'rounded-md bg-primary px-3 py-1.5 text-sm font-medium text-primary-foreground'
+                            : 'rounded-md px-3 py-1.5 text-sm font-medium text-muted-foreground transition-colors hover:bg-accent hover:text-foreground', children: label }, href))) }), _jsx("div", { className: "flex-1 sm:hidden" }), actions && _jsx("div", { className: "flex items-center gap-2", children: actions }), _jsxs(Dialog.Root, { open: open, onOpenChange: setOpen, children: [_jsxs(Dialog.Trigger, { "aria-label": "Account and settings", className: "relative shrink-0 rounded-full focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring", children: [_jsx(ForgeAvatar, { account: account, className: "h-8 w-8" }), syncError && (_jsx("span", { role: "img", "aria-label": "Not synced", title: "Not synced", className: "absolute -right-0.5 -top-0.5 h-2.5 w-2.5 rounded-full border-2 border-background bg-destructive" }))] }), _jsxs(Dialog.Portal, { children: [_jsx(Dialog.Overlay, { className: "fixed inset-0 z-50 bg-black/60" }), _jsx(Dialog.Content, { className: "fixed inset-y-0 right-0 z-50 flex w-[88vw] max-w-sm flex-col border-l bg-background text-foreground shadow-lg outline-hidden", children: _jsx(AccountPanel, { current: current, account: account, syncError: syncError, nav: nav, accountDetails: accountDetails, guestDetails: guestDetails, accountActions: accountActions, panel: panel, onBeforeSignOut: onBeforeSignOut, currentUrl: currentUrl }) })] })] })] }) }));
+}
+function initials(name) {
+    return name.slice(0, 2).toUpperCase();
+}
+export function ForgeAvatar({ account, className = '' }) {
+    if (account?.avatarUrl) {
+        return _jsx("img", { src: account.avatarUrl, alt: "", className: `${className} rounded-full object-cover` });
+    }
+    if (account) {
+        return (_jsx("span", { className: `${className} flex items-center justify-center rounded-full bg-primary text-xs font-semibold text-primary-foreground`, children: initials(account.username) }));
+    }
+    return (_jsx("span", { className: `${className} flex items-center justify-center rounded-full bg-muted text-muted-foreground`, children: _jsx(UserRound, { className: "h-1/2 w-1/2" }) }));
+}
+function AccountPanel({ current, account, syncError, nav = [], accountDetails, guestDetails, accountActions, panel, onBeforeSignOut, currentUrl, }) {
+    const appUrl = FORGE_APPS.find((a) => a.id === current)?.url ?? accountUrl('/');
+    const liveUrl = useCurrentUrl(appUrl);
+    const next = currentUrl ?? liveUrl;
+    const signOutHref = accountUrl('/logout', { next });
+    const [signingOut, setSigningOut] = useState(false);
+    async function signOut() {
+        setSigningOut(true);
+        try {
+            await onBeforeSignOut?.();
+        }
+        finally {
+            window.location.assign(signOutHref);
+        }
+    }
+    return (_jsxs(_Fragment, { children: [_jsxs("div", { className: "flex items-start gap-3 border-b p-4", children: [_jsx(ForgeAvatar, { account: account, className: "h-12 w-12 shrink-0 text-sm" }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx(Dialog.Title, { className: "truncate font-semibold", children: account ? account.username : 'Guest' }), _jsx(Dialog.Description, { asChild: true, children: _jsx("div", { className: "text-sm text-muted-foreground", children: account ? (_jsxs(_Fragment, { children: [account.supporterTier && (_jsx("span", { className: "mt-1 block", children: _jsx(ForgeSupporterBadge, { tier: account.supporterTier }) })), account.discordUsername && (_jsxs("span", { className: "mt-1 flex items-center gap-1 text-xs text-[#5865F2]", children: [_jsx(DiscordIcon, { className: "h-3 w-3 shrink-0" }), account.discordUsername] })), accountDetails] })) : (guestDetails ?? 'Your data lives only in this browser.') }) }), account && syncError && (_jsxs("p", { className: "mt-1 flex items-center gap-1 text-xs text-destructive", children: [_jsx(RefreshCw, { className: "h-3 w-3" }), " Not synced to your account"] }))] }), _jsx(Dialog.Close, { "aria-label": "Close", className: "rounded-md p-1 text-muted-foreground hover:bg-accent hover:text-foreground focus-visible:outline-2 focus-visible:outline-ring", children: _jsx(X, { className: "h-4 w-4" }) })] }), _jsxs("div", { className: "flex-1 space-y-6 overflow-y-auto p-4", children: [_jsx(ForgePanelSection, { title: "Account", children: account ? (_jsxs(_Fragment, { children: [_jsx(ForgePanelItem, { icon: UserRound, label: "xForge account", description: "Profile, password and linked apps", href: accountUrl('/'), external: true }), accountActions, onBeforeSignOut ? (_jsx(ForgePanelItem, { icon: LogOut, label: signingOut ? 'Signing out…' : 'Sign out', onClick: signOut, disabled: signingOut, tone: "destructive" })) : (_jsx(ForgePanelItem, { icon: LogOut, label: "Sign out", href: signOutHref, external: true, tone: "destructive" }))] })) : (_jsxs(_Fragment, { children: [_jsx(ForgePanelItem, { icon: LogIn, label: "Sign in / Create account", description: "Keep your data safe and use it on any device", href: accountUrl('/login', { next }), external: true }), accountActions] })) }), nav.length > 0 && (_jsx("div", { className: "sm:hidden", children: _jsx(ForgePanelSection, { title: "Navigate", children: nav.map(({ href, label, icon, active }) => (_jsx(ForgePanelItem, { icon: icon, label: label, href: href, active: active }, href))) }) })), _jsx(AppearanceSection, {}), panel] })] }));
+}
+/** Discord's mark in `currentColor`; give it Discord's blurple (`text-[#5865F2]`) next to a Discord name. */
+export function DiscordIcon({ className }) {
+    return (_jsx("svg", { xmlns: "http://www.w3.org/2000/svg", viewBox: "0 0 640 640", className: className, fill: "currentColor", "aria-hidden": "true", children: _jsx("path", { d: "M524.5 133.8C524.3 133.5 524.1 133.2 523.7 133.1C485.6 115.6 445.3 103.1 404 96C403.6 95.9 403.2 96 402.9 96.1C402.6 96.2 402.3 96.5 402.1 96.9C396.6 106.8 391.6 117.1 387.2 127.5C342.6 120.7 297.3 120.7 252.8 127.5C248.3 117 243.3 106.8 237.7 96.9C237.5 96.6 237.2 96.3 236.9 96.1C236.6 95.9 236.2 95.9 235.8 95.9C194.5 103 154.2 115.5 116.1 133C115.8 133.1 115.5 133.4 115.3 133.7C39.1 247.5 18.2 358.6 28.4 468.2C28.4 468.5 28.5 468.7 28.6 469C28.7 469.3 28.9 469.4 29.1 469.6C73.5 502.5 123.1 527.6 175.9 543.8C176.3 543.9 176.7 543.9 177 543.8C177.3 543.7 177.7 543.4 177.9 543.1C189.2 527.7 199.3 511.3 207.9 494.3C208 494.1 208.1 493.8 208.1 493.5C208.1 493.2 208.1 493 208 492.7C207.9 492.4 207.8 492.2 207.6 492.1C207.4 492 207.2 491.8 206.9 491.7C191.1 485.6 175.7 478.3 161 469.8C160.7 469.6 160.5 469.4 160.3 469.2C160.1 469 160 468.6 160 468.3C160 468 160 467.7 160.2 467.4C160.4 467.1 160.5 466.9 160.8 466.7C163.9 464.4 167 462 169.9 459.6C170.2 459.4 170.5 459.2 170.8 459.2C171.1 459.2 171.5 459.2 171.8 459.3C268 503.2 372.2 503.2 467.3 459.3C467.6 459.2 468 459.1 468.3 459.1C468.6 459.1 469 459.3 469.2 459.5C472.1 461.9 475.2 464.4 478.3 466.7C478.5 466.9 478.7 467.1 478.9 467.4C479.1 467.7 479.1 468 479.1 468.3C479.1 468.6 479 468.9 478.8 469.2C478.6 469.5 478.4 469.7 478.2 469.8C463.5 478.4 448.2 485.7 432.3 491.6C432.1 491.7 431.8 491.8 431.6 492C431.4 492.2 431.3 492.4 431.2 492.7C431.1 493 431.1 493.2 431.1 493.5C431.1 493.8 431.2 494 431.3 494.3C440.1 511.3 450.1 527.6 461.3 543.1C461.5 543.4 461.9 543.7 462.2 543.8C462.5 543.9 463 543.9 463.3 543.8C516.2 527.6 565.9 502.5 610.4 469.6C610.6 469.4 610.8 469.2 610.9 469C611 468.8 611.1 468.5 611.1 468.2C623.4 341.4 590.6 231.3 524.2 133.7zM222.5 401.5C193.5 401.5 169.7 374.9 169.7 342.3C169.7 309.7 193.1 283.1 222.5 283.1C252.2 283.1 275.8 309.9 275.3 342.3C275.3 375 251.9 401.5 222.5 401.5zM417.9 401.5C388.9 401.5 365.1 374.9 365.1 342.3C365.1 309.7 388.5 283.1 417.9 283.1C447.6 283.1 471.2 309.9 470.7 342.3C470.7 375 447.5 401.5 417.9 401.5z" }) }));
+}
+function AppearanceSection() {
+    const { theme, setTheme, colorTheme, setColorTheme, syncTheme, setSyncTheme } = useForgeTheme();
+    return (_jsx(ForgePanelSection, { title: "Appearance", children: _jsxs("div", { className: "space-y-4 rounded-lg border p-3", children: [_jsx(ForgeSwitchRow, { icon: theme === 'dark' ? Moon : Sun, label: "Dark mode", checked: theme === 'dark', onCheckedChange: (dark) => setTheme(dark ? 'dark' : 'light') }), _jsx("div", { className: "grid grid-cols-6 gap-2", role: "radiogroup", "aria-label": "Color theme", children: FORGE_COLOR_THEMES.map((t) => (_jsx("button", { type: "button", role: "radio", "aria-checked": colorTheme === t.name, "aria-label": t.label, title: t.label, onClick: () => setColorTheme(t.name), className: `h-8 w-8 justify-self-center rounded-full ring-2 ring-offset-2 ring-offset-background transition-transform focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-ring ${colorTheme === t.name ? 'scale-110 ring-foreground' : 'ring-transparent hover:ring-foreground/40'}`, style: { background: t.color } }, t.name))) }), _jsx(ForgeSwitchRow, { label: "Same theme in all xForge apps", description: "Changing it here changes it everywhere", checked: syncTheme, onCheckedChange: setSyncTheme })] }) }));
+}
+/** A titled group in the account panel. */
+export function ForgePanelSection({ title, description, children, }) {
+    return (_jsxs("section", { className: "space-y-2", children: [_jsxs("div", { children: [_jsx("h3", { className: "text-xs font-semibold uppercase tracking-wide text-muted-foreground", children: title }), description && _jsx("p", { className: "mt-1 text-sm text-muted-foreground", children: description })] }), _jsx("div", { className: "space-y-1", children: children })] }));
+}
+/** A row in the account panel: a link or a button that closes the panel. */
+export function ForgePanelItem({ icon: Icon, label, description, href, external, onClick, disabled, active, tone = 'default', keepOpen, className: extraClassName = '', ...buttonProps }) {
+    const className = `flex w-full items-start gap-3 rounded-md px-2 py-2 text-left text-sm transition-colors hover:bg-accent focus-visible:outline-2 focus-visible:outline-ring disabled:pointer-events-none disabled:opacity-50 ${tone === 'destructive' ? 'text-destructive' : ''} ${active ? 'bg-accent font-medium' : ''} ${extraClassName}`;
+    const body = (_jsxs(_Fragment, { children: [Icon && _jsx(Icon, { className: "mt-0.5 h-4 w-4 shrink-0" }), _jsxs("span", { className: "flex-1", children: [_jsx("span", { className: "block font-medium", children: label }), description && _jsx("span", { className: "block text-xs text-muted-foreground", children: description })] }), external && href?.startsWith('http') && tone === 'default' && (_jsx(ExternalLink, { className: "mt-0.5 h-3.5 w-3.5 shrink-0 text-muted-foreground" }))] }));
+    const element = href ? (external ? (_jsx("a", { href: href, className: className, "aria-current": active ? 'page' : undefined, children: body })) : (_jsx(Link, { href: href, className: className, "aria-current": active ? 'page' : undefined, children: body }))) : (_jsx("button", { type: "button", ...buttonProps, onClick: onClick, disabled: disabled, className: className, children: body }));
+    return keepOpen ? element : _jsx(Dialog.Close, { asChild: true, children: element });
+}
+/** A labelled on/off switch row for panel sections. */
+export function ForgeSwitchRow({ icon: Icon, label, description, checked, onCheckedChange, }) {
+    return (_jsxs("label", { className: "flex cursor-pointer items-center gap-3 text-sm", children: [Icon && _jsx(Icon, { className: "h-4 w-4 shrink-0" }), _jsxs("span", { className: "flex-1", children: [_jsx("span", { className: "block font-medium", children: label }), description && _jsx("span", { className: "block text-xs text-muted-foreground", children: description })] }), _jsx("button", { type: "button", role: "switch", "aria-checked": checked, onClick: () => onCheckedChange(!checked), className: `relative inline-flex h-5 w-9 shrink-0 items-center rounded-full transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring ${checked ? 'bg-primary' : 'bg-input'}`, children: _jsx("span", { className: `inline-block h-4 w-4 rounded-full bg-background shadow transition-transform ${checked ? 'translate-x-4' : 'translate-x-0.5'}` }) })] }));
+}

package/dist/forge-logo.d.ts

@@ -0,0 +1,12 @@
+import { type ForgeBrandId } from './brand.js';
+export type ForgeLogoProps = {
+    brand: ForgeBrandId;
+    /** `logo` is the mark plus wordmark; `icon` is the square mark. */
+    variant?: 'logo' | 'icon';
+    /** Size it with height classes, e.g. `h-8`; width follows. */
+    className?: string;
+    /** Defaults to the brand name; pass `""` when a visible label already names it. */
+    alt?: string;
+};
+/** An xForge app's logo or icon, switching to the right logo for light and dark mode. */
+export declare function ForgeLogo({ brand, variant, className, alt }: ForgeLogoProps): import("react").JSX.Element;

package/dist/forge-logo.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { FORGE_BRANDS } from './brand.js';
+/** An xForge app's logo or icon, switching to the right logo for light and dark mode. */
+export function ForgeLogo({ brand, variant = 'logo', className = 'h-8', alt }) {
+    const b = FORGE_BRANDS[brand];
+    const label = alt ?? b.name;
+    if (variant === 'icon') {
+        return _jsx("img", { src: b.icon, alt: label, className: `${className} aspect-square w-auto`, draggable: false });
+    }
+    return (_jsxs(_Fragment, { children: [_jsx("img", { src: b.logo.light, alt: label, className: `${className} w-auto dark:hidden`, draggable: false }), _jsx("img", { src: b.logo.dark, alt: label, className: `${className} hidden w-auto dark:block`, draggable: false })] }));
+}

package/dist/guest-banner.d.ts

@@ -0,0 +1,10 @@
+import { type ForgeAppId } from './apps.js';
+export type GuestBannerProps = {
+    appId: ForgeAppId;
+    appName: string;
+    /** `undefined` while auth state is still loading; the banner renders nothing until known. */
+    signedIn: boolean | undefined;
+    /** Override for tests; defaults to the live page URL. */
+    currentUrl?: string;
+};
+export declare function GuestBanner({ appId, appName, signedIn, currentUrl }: GuestBannerProps): import("react").JSX.Element | null;