@edgespark/web 0.0.1 → 0.0.3

package/README.md

@@ -1,6 +1,6 @@
 # `@edgespark/web`
 
-Parallel rewrite of the EdgeSpark browser SDK.
+EdgeSpark browser SDK.
 
 This package is intentionally:
 
@@ -10,6 +10,13 @@ This package is intentionally:
 - zero-config
 - optimized for agent-written code
 
+Recommended browser auth path:
+
+- use `@edgespark/web` for all browser auth
+- prefer `authUI.mount()` for managed auth UI
+- use `es.auth` for custom flows
+- do not implement app auth by calling `/api/_es/auth/*` manually
+
 ## Use in this repo
 
 ```bash
@@ -73,7 +80,8 @@ Current platform note:
 
 still appear on the familiar better-auth-shaped surface, but EdgeSpark does
 not currently enable those platform capabilities. These methods fail fast with
-`UNSUPPORTED_AUTH_METHOD`.
+`UNSUPPORTED_AUTH_METHOD`. For normal browser auth flows, stay on the supported
+paths: `authUI.mount()` for managed UI and `es.auth` for supported custom flows.
 
 Use the familiar auth methods directly:
 
@@ -84,6 +92,8 @@ await es.auth.signOut();
 await es.auth.getSession();
 ```
 
+The platform-managed `/api/_es/auth/*` routes exist underneath the SDK, but normal app code should not call them directly. Treat those routes as implementation details unless you are debugging auth at the HTTP layer.
+
 ### `api`
 
 `es.api.fetch(...)` is the same-origin fetch wrapper for authenticated app requests.
@@ -154,6 +164,81 @@ In controlled mode, `authUI` stops mutating the container after `onSuccess`
 runs. If the app wants to close, replace, or reuse that container, it owns that
 teardown explicitly.
 
+#### Appearance
+
+Managed auth supports a small, explicit appearance contract. If `appearance` is
+omitted, the UI keeps its built-in default styling.
+
+- `theme` selects the built-in starting preset
+- `variables` override specific design tokens on top of that preset
+- `className` adds a stable root hook for app-scoped CSS
+
+```ts
+import {
+  AUTH_UI_APPEARANCE_VARIABLE,
+  AUTH_UI_THEME,
+  type AuthUIAppearance,
+} from "@edgespark/web";
+
+const appearance = {
+  theme: AUTH_UI_THEME.DARK,
+  className: "my-auth-surface",
+  variables: {
+    [AUTH_UI_APPEARANCE_VARIABLE.PRIMARY]: "#d97d4a",
+    [AUTH_UI_APPEARANCE_VARIABLE.FONT]: '"Manrope", sans-serif',
+  },
+} satisfies AuthUIAppearance;
+
+es.authUI.mount(container, {
+  redirectTo: "/dashboard",
+  appearance,
+});
+```
+
+Supported appearance fields:
+
+- `theme`: `"light"` or `"dark"` (`"light"` is the default)
+- `className`: applied to the managed auth UI root container
+- `variables`: stable CSS custom properties for light-touch theming
+
+`appearance.variables` are applied as inline CSS custom properties on the
+managed auth root, so explicit overrides win over the built-in stylesheet
+defaults without requiring consumers to manage CSS load order.
+
+When the appearance object is assigned to a variable before calling
+`authUI.mount(...)`, prefer `satisfies AuthUIAppearance` so `tsc` rejects
+unsupported theme values, unsupported token keys, and misspelled appearance
+fields during type-checking.
+
+Supported `appearance.variables` keys:
+
+| Variable | Controls | Light default |
+|----------|----------|---------------|
+| `--edgespark-auth-bg` | Page/input background, status mix base | `#ffffff` |
+| `--edgespark-auth-bg-muted` | Secondary button hover, muted status bg, modal close hover | `#f7f7f8` |
+| `--edgespark-auth-card-bg` | Card background (accepts gradient or flat color) | `linear-gradient(180deg, #ffffff, #fcfcfc)` |
+| `--edgespark-auth-border` | Input border, secondary button border, divider line | `rgba(15,23,42,0.08)` |
+| `--edgespark-auth-text` | All body text | `#111827` |
+| `--edgespark-auth-text-muted` | Subtitles, meta text, divider label, modal close icon | `#6b7280` |
+| `--edgespark-auth-divider-bg` | Divider pill background (masks the line behind the label) | inherits `--edgespark-auth-bg` |
+| `--edgespark-auth-primary` | Primary button bg, links, input focus ring + border | `#0f766e` |
+| `--edgespark-auth-primary-hover` | Primary button hover bg | `#115e59` |
+| `--edgespark-auth-primary-contrast` | Primary button text | `#ffffff` |
+| `--edgespark-auth-error` | Error status text + tinted bg | `#b91c1c` |
+| `--edgespark-auth-info` | Info status text + tinted bg | `#0f766e` |
+| `--edgespark-auth-radius-card` | Card border radius | `20px` |
+| `--edgespark-auth-radius-control` | Input border radius | `12px` |
+| `--edgespark-auth-shadow` | Card box shadow | `0 24px 60px rgba(15,23,42,0.08)` |
+| `--edgespark-auth-font` | Root font family | `"IBM Plex Sans", "Inter", ui-sans-serif, system-ui, sans-serif` |
+| `--edgespark-auth-modal-backdrop` | OAuth modal overlay background | `rgba(15,23,42,0.22)` |
+| `--edgespark-auth-modal-card-bg` | OAuth modal card background | `#ffffff` |
+| `--edgespark-auth-modal-shadow` | OAuth modal card box shadow | `0 24px 60px rgba(15,23,42,0.18)` |
+
+Only the root container hook, the theme attribute, and the documented CSS
+variables above are part of the managed auth appearance contract. Internal
+`.edgespark-auth__*` classes remain implementation details and should not be
+treated as a stable public API.
+
 ## Flows covered by the managed UI
 
 - email/password sign-in

package/auth/styles/styles.css

@@ -1,21 +1,46 @@
 [data-edgespark-auth] {
   --edgespark-auth-bg: #ffffff;
   --edgespark-auth-bg-muted: #f7f7f8;
+  --edgespark-auth-card-bg: linear-gradient(180deg, #ffffff 0%, #fcfcfc 100%);
   --edgespark-auth-border: rgba(15, 23, 42, 0.08);
   --edgespark-auth-text: #111827;
   --edgespark-auth-text-muted: #6b7280;
+  --edgespark-auth-divider-bg: var(--edgespark-auth-bg);
   --edgespark-auth-primary: #0f766e;
   --edgespark-auth-primary-hover: #115e59;
+  --edgespark-auth-primary-contrast: #ffffff;
   --edgespark-auth-error: #b91c1c;
   --edgespark-auth-info: #0f766e;
   --edgespark-auth-radius-card: 20px;
   --edgespark-auth-radius-control: 12px;
   --edgespark-auth-shadow: 0 24px 60px rgba(15, 23, 42, 0.08);
   --edgespark-auth-font: "IBM Plex Sans", "Inter", ui-sans-serif, system-ui, sans-serif;
+  --edgespark-auth-modal-backdrop: rgba(15, 23, 42, 0.22);
+  --edgespark-auth-modal-card-bg: #ffffff;
+  --edgespark-auth-modal-shadow: 0 24px 60px rgba(15, 23, 42, 0.18);
   color: var(--edgespark-auth-text);
   font-family: var(--edgespark-auth-font);
 }
 
+[data-edgespark-auth][data-edgespark-auth-theme="dark"] {
+  --edgespark-auth-bg: #14181f;
+  --edgespark-auth-bg-muted: #1d2330;
+  --edgespark-auth-card-bg: linear-gradient(180deg, #171d27 0%, #121823 100%);
+  --edgespark-auth-border: rgba(226, 232, 240, 0.12);
+  --edgespark-auth-text: #f8fafc;
+  --edgespark-auth-text-muted: #94a3b8;
+  --edgespark-auth-divider-bg: var(--edgespark-auth-bg);
+  --edgespark-auth-primary: #14b8a6;
+  --edgespark-auth-primary-hover: #0f9488;
+  --edgespark-auth-primary-contrast: #f8fafc;
+  --edgespark-auth-error: #fca5a5;
+  --edgespark-auth-info: #5eead4;
+  --edgespark-auth-shadow: 0 24px 60px rgba(2, 6, 23, 0.32);
+  --edgespark-auth-modal-backdrop: rgba(2, 6, 23, 0.56);
+  --edgespark-auth-modal-card-bg: #101722;
+  --edgespark-auth-modal-shadow: 0 24px 60px rgba(2, 6, 23, 0.48);
+}
+
 [data-edgespark-auth] *,
 [data-edgespark-auth] *::before,
 [data-edgespark-auth] *::after {
@@ -34,7 +59,7 @@
   padding: 24px;
   border: 1px solid var(--edgespark-auth-border);
   border-radius: var(--edgespark-auth-radius-card);
-  background: linear-gradient(180deg, #ffffff 0%, #fcfcfc 100%);
+  background: var(--edgespark-auth-card-bg);
   box-shadow: var(--edgespark-auth-shadow);
 }
 
@@ -118,7 +143,7 @@
 
 .edgespark-auth__button--primary {
   background: var(--edgespark-auth-primary);
-  color: #ffffff;
+  color: var(--edgespark-auth-primary-contrast);
 }
 
 .edgespark-auth__button--primary:hover:not(:disabled) {
@@ -168,7 +193,7 @@
 .edgespark-auth__divider span {
   position: relative;
   padding: 0 10px;
-  background: var(--edgespark-auth-bg);
+  background: var(--edgespark-auth-divider-bg);
 }
 
 .edgespark-auth__status {
@@ -180,12 +205,12 @@
 
 .edgespark-auth__status--error {
   color: var(--edgespark-auth-error);
-  background: color-mix(in srgb, var(--edgespark-auth-error) 10%, #ffffff);
+  background: color-mix(in srgb, var(--edgespark-auth-error) 10%, var(--edgespark-auth-bg));
 }
 
 .edgespark-auth__status--info {
   color: var(--edgespark-auth-info);
-  background: color-mix(in srgb, var(--edgespark-auth-info) 10%, #ffffff);
+  background: color-mix(in srgb, var(--edgespark-auth-info) 10%, var(--edgespark-auth-bg));
 }
 
 .edgespark-auth__status--muted {
@@ -201,7 +226,7 @@
   align-items: center;
   justify-content: center;
   padding: 24px;
-  background: rgba(15, 23, 42, 0.22);
+  background: var(--edgespark-auth-modal-backdrop);
 }
 
 .edgespark-auth__iframe-modal-card {
@@ -211,8 +236,8 @@
   width: min(520px, 100%);
   padding: 28px;
   border-radius: 24px;
-  background: #ffffff;
-  box-shadow: 0 24px 60px rgba(15, 23, 42, 0.18);
+  background: var(--edgespark-auth-modal-card-bg);
+  box-shadow: var(--edgespark-auth-modal-shadow);
 }
 
 .edgespark-auth__iframe-modal-close {
@@ -233,6 +258,16 @@
   background: var(--edgespark-auth-bg-muted);
 }
 
+.edgespark-auth__dev-banner {
+  background: #fef3c7;
+  color: #92400e;
+  padding: 0.5rem 1rem;
+  border-radius: 6px;
+  font-size: 0.8rem;
+  text-align: center;
+  margin-bottom: 0.75rem;
+}
+
 @media (max-width: 480px) {
   .edgespark-auth__card {
     padding: 18px;

package/dist/auth/local-dev.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Is the web app running in local-dev mode?
+ *
+ * Reads a `<meta name="edgespark-local-dev" content="true">` tag that
+ * the `edgespark dev` reverse proxy splices into every HTML response.
+ * The dev proxy only runs under `edgespark dev`; the meta tag is absent
+ * on deployed apps (served through the CF dispatcher, which doesn't
+ * inject).
+ *
+ * Uses a <meta> tag rather than an inline <script> so the signal works
+ * under strict CSP — `script-src 'self'` without `'unsafe-inline'`
+ * would silently drop a script-based marker. Meta tags carry no
+ * script-src constraint.
+ *
+ * No server round-trip, no build-time macro, no hostname heuristic, no
+ * framework assumptions. Survives SDK pre-bundling — the SDK reads the
+ * DOM at call time, not a value captured at build time.
+ */
+export declare function isLocalDev(): boolean;
+/**
+ * Auto-verify email in local dev. The server reads the pending verification
+ * token from D1, drives Better Auth's verify-email handler, and returns with
+ * the session cookie already set. Single round-trip — no token round-trip on
+ * the client.
+ */
+export declare function autoVerifyLocalDev(email: string): Promise<boolean>;
+/**
+ * Fetch the pending OTP for password reset in local dev.
+ * Returns the OTP string or null if not available.
+ */
+export declare function fetchOtpLocalDev(email: string): Promise<string | null>;

package/dist/auth/types.d.ts

@@ -68,7 +68,8 @@ export type EdgeSparkAuth = BetterAuthClientInstance & {
      *
      * The method remains present to preserve the familiar better-auth API shape,
      * but the facade throws `UNSUPPORTED_AUTH_METHOD` until the platform enables
-     * this capability.
+     * this capability. For browser auth, prefer supported `client.auth` methods
+     * or `authUI.mount()` instead of dropping to raw `/api/_es/auth/*` routes.
      */
     changeEmail(...args: Parameters<BetterAuthClientInstance["changeEmail"]>): ReturnType<BetterAuthClientInstance["changeEmail"]>;
     /**
@@ -76,7 +77,8 @@ export type EdgeSparkAuth = BetterAuthClientInstance & {
      *
      * The method remains present to preserve the familiar better-auth API shape,
      * but the facade throws `UNSUPPORTED_AUTH_METHOD` until the platform enables
-     * this capability.
+     * this capability. Handle account removal through your own app flow until the
+     * platform adds first-class support.
      */
     deleteUser(...args: Parameters<BetterAuthClientInstance["deleteUser"]>): ReturnType<BetterAuthClientInstance["deleteUser"]>;
 };

package/dist/auth-ui/ManagedAuthUI.d.ts

@@ -35,6 +35,7 @@ export declare class ManagedAuthUI implements MountedAuthUI {
     private readMountSession;
     private render;
     private renderLoading;
+    private renderDevModeBanner;
     private renderStatus;
     private renderCurrentView;
     private renderSignInView;
@@ -53,6 +54,12 @@ export declare class ManagedAuthUI implements MountedAuthUI {
     private resendResetCode;
     private handleResetPassword;
     private resendVerificationEmail;
+    /**
+     * Drive the local-dev auto-verify endpoint and, on success, complete the
+     * auth flow. Returns whether auto-verify completed — callers decide what
+     * to do on `false` (sign-up falls through to a retry UI; resend throws).
+     */
+    private tryDevAutoVerify;
     private sendVerificationEmail;
     private completeAuth;
     private retryAuthCompletionDataIfNeeded;

package/dist/auth-ui/appearance.d.ts

@@ -0,0 +1,64 @@
+export declare const AUTH_UI_THEME: {
+    readonly LIGHT: "light";
+    readonly DARK: "dark";
+};
+export declare const AUTH_UI_THEME_LIGHT: "light";
+export declare const AUTH_UI_THEME_DARK: "dark";
+export declare const AUTH_UI_THEMES: readonly ["light", "dark"];
+export declare const AUTH_UI_DEFAULT_THEME: "light";
+export type AuthUITheme = (typeof AUTH_UI_THEME)[keyof typeof AUTH_UI_THEME];
+export declare const AUTH_UI_APPEARANCE_VARIABLE: {
+    readonly BACKGROUND: "--edgespark-auth-bg";
+    readonly BACKGROUND_MUTED: "--edgespark-auth-bg-muted";
+    readonly CARD_BACKGROUND: "--edgespark-auth-card-bg";
+    readonly BORDER: "--edgespark-auth-border";
+    readonly TEXT: "--edgespark-auth-text";
+    readonly TEXT_MUTED: "--edgespark-auth-text-muted";
+    readonly DIVIDER_BACKGROUND: "--edgespark-auth-divider-bg";
+    readonly PRIMARY: "--edgespark-auth-primary";
+    readonly PRIMARY_HOVER: "--edgespark-auth-primary-hover";
+    readonly PRIMARY_CONTRAST: "--edgespark-auth-primary-contrast";
+    readonly ERROR: "--edgespark-auth-error";
+    readonly INFO: "--edgespark-auth-info";
+    readonly CARD_RADIUS: "--edgespark-auth-radius-card";
+    readonly CONTROL_RADIUS: "--edgespark-auth-radius-control";
+    readonly SHADOW: "--edgespark-auth-shadow";
+    readonly FONT: "--edgespark-auth-font";
+    readonly MODAL_BACKDROP: "--edgespark-auth-modal-backdrop";
+    readonly MODAL_CARD_BACKGROUND: "--edgespark-auth-modal-card-bg";
+    readonly MODAL_SHADOW: "--edgespark-auth-modal-shadow";
+};
+export type AuthUIAppearanceVariableName = (typeof AUTH_UI_APPEARANCE_VARIABLE)[keyof typeof AUTH_UI_APPEARANCE_VARIABLE];
+export declare const AUTH_UI_APPEARANCE_VARIABLE_NAMES: readonly AuthUIAppearanceVariableName[];
+export type AuthUIAppearanceVariables = Partial<Record<AuthUIAppearanceVariableName, string>>;
+export interface AuthUIAppearance {
+    /**
+     * Built-in visual preset for the managed auth UI root.
+     *
+     * Defaults to `"light"` when omitted. Variable overrides apply on top of the
+     * selected preset instead of replacing the entire theme contract.
+     */
+    theme?: AuthUITheme;
+    /**
+     * Optional class applied to the managed auth UI root container.
+     *
+     * Use this to scope additional app-level CSS around the stable root element.
+     */
+    className?: string;
+    /**
+     * Stable CSS custom properties supported by the managed auth UI.
+     *
+     * This is the supported appearance contract for light-touch theming. When a
+     * variable is omitted, the current theme preset keeps its default value.
+     */
+    variables?: AuthUIAppearanceVariables;
+}
+interface NormalizedAuthUIAppearance {
+    theme: AuthUITheme;
+    className: string;
+    variables: AuthUIAppearanceVariables;
+}
+export declare function isAuthUITheme(value: unknown): value is AuthUITheme;
+export declare function isAuthUIAppearanceVariableName(value: string): value is AuthUIAppearanceVariableName;
+export declare function normalizeAuthUIAppearance(appearance?: AuthUIAppearance): NormalizedAuthUIAppearance;
+export {};

package/dist/auth-ui/config.d.ts

@@ -27,7 +27,8 @@ export interface NormalizedAuthUIConfig {
     requireEmailVerification: boolean;
     passwordResetEmailOtpEnabled: boolean;
     oauthProviders: OAuthProviderId[];
+    isLocalDev: boolean;
 }
 export declare function loadNormalizedAuthUIConfig(): Promise<NormalizedAuthUIConfig>;
-export declare function normalizeAuthUIConfig(config: AuthConfigResponse): NormalizedAuthUIConfig;
+export declare function normalizeAuthUIConfig(config: AuthConfigResponse, isLocalDev?: boolean): NormalizedAuthUIConfig;
 export {};

package/dist/auth-ui/index.d.ts

@@ -1,2 +1,4 @@
 export { createAuthUIModule } from './mount';
+export { AUTH_UI_APPEARANCE_VARIABLE, AUTH_UI_APPEARANCE_VARIABLE_NAMES, AUTH_UI_THEME, AUTH_UI_DEFAULT_THEME, AUTH_UI_THEME_DARK, AUTH_UI_THEME_LIGHT, AUTH_UI_THEMES, } from './appearance';
+export type { AuthUIAppearance, AuthUIAppearanceVariableName, AuthUIAppearanceVariables, AuthUITheme, } from './appearance';
 export type { AuthSuccessEvent, AuthUILabelOverrides, AuthUILabels, ControlledAuthUIOptions, EdgeSparkAuthUI, MountAuthUIOptions, MountedAuthUI, RedirectAuthUIOptions, } from './types';

package/dist/auth-ui/types.d.ts

@@ -2,6 +2,7 @@ import { AuthSession, AuthUser } from '../auth/types';
 import { EdgeSparkAuthError } from '../errors';
 import { RedirectTarget } from '../redirect';
 import { DeepPartial } from '../shared/types';
+import { AuthUIAppearance } from './appearance';
 /** Sign-in or sign-up completed with an authenticated session. */
 export type AuthenticatedAuthSuccessEvent = {
     action: "sign-in";
@@ -91,6 +92,17 @@ export interface AuthUILabels {
     };
 }
 export type AuthUILabelOverrides = DeepPartial<AuthUILabels>;
+interface BaseAuthUIOptions {
+    onError?: (error: EdgeSparkAuthError) => void;
+    labels?: AuthUILabelOverrides;
+    /**
+     * Optional, constrained visual customization for the managed auth UI.
+     *
+     * This is intentionally smaller than the headless auth path. Use
+     * `client.auth` when the app needs full UI ownership.
+     */
+    appearance?: AuthUIAppearance;
+}
 /**
  * Redirect mode — use when the auth UI is a full-page login gate.
  *
@@ -99,11 +111,9 @@ export type AuthUILabelOverrides = DeepPartial<AuthUILabels>;
  *
  * `onSuccess` is optional and fires *before* the redirect (useful for analytics).
  */
-export interface RedirectAuthUIOptions {
+export interface RedirectAuthUIOptions extends BaseAuthUIOptions {
     redirectTo: RedirectTarget;
     onSuccess?: (event: AuthSuccessEvent) => void;
-    onError?: (error: EdgeSparkAuthError) => void;
-    labels?: AuthUILabelOverrides;
 }
 /**
  * Controlled mode — use when the app owns what happens after auth.
@@ -114,11 +124,9 @@ export interface RedirectAuthUIOptions {
  *
  * Use this for: modals, embedded auth widgets, SPA routing, onboarding flows.
  */
-export interface ControlledAuthUIOptions {
+export interface ControlledAuthUIOptions extends BaseAuthUIOptions {
     onSuccess: (event: AuthSuccessEvent) => void;
     redirectTo?: never;
-    onError?: (error: EdgeSparkAuthError) => void;
-    labels?: AuthUILabelOverrides;
 }
 /**
  * Two post-auth strategies — pick one:
@@ -145,3 +153,4 @@ export interface EdgeSparkAuthUI {
      */
     mount(container: HTMLElement, options: MountAuthUIOptions): MountedAuthUI;
 }
+export {};