@agent-native/core 0.172.4 → 0.172.8

package/dist/jobs/run-now.js

@@ -1,5 +1,5 @@
 import { AGENT_CHAT_BACKGROUND_RUN_FIELD, dispatchPathTargetsNetlifyBackgroundFunction, resolveAgentChatProcessRunDispatchPath, } from "../agent/durable-background.js";
-import { canUpdateAutomationResource, } from "../automations/service.js";
+import { canQueueAutomationRunNow, } from "../automations/service.js";
 import { isLocalDatabase } from "../db/client.js";
 import { organizationResourceOwner, resourceGetByPath, } from "../resources/store.js";
 import { fireInternalDispatch } from "../server/self-dispatch.js";
@@ -77,7 +77,7 @@ export async function queueAutomationRunNow(input) {
             statusCode: 404,
         });
     }
-    if (!(await canUpdateAutomationResource(input, resource))) {
+    if (!(await canQueueAutomationRunNow(input, resource, input.scope))) {
         throw Object.assign(new Error("Only the automation's creator or an organization admin can run it."), { statusCode: 403 });
     }
     const { body } = parseJobResource(resource.content);

package/dist/server/attribution.d.ts

@@ -35,6 +35,21 @@ export interface FirstTouchAttribution {
     /** ISO timestamp of when the visitor first landed. */
     landed_at?: string;
 }
+/**
+ * Which flow created the account, as opposed to which credential it uses.
+ *
+ * Better Auth fires its `user.create.after` hook on every `user` row insert,
+ * but only some inserts are a person signing up in a browser. Every emitted
+ * `signup` event names its origin so a campaign report can select the ones
+ * that are acquisitions instead of counting row inserts.
+ */
+export type SignupOrigin = 
+/** A person completed a signup form or magic link in a browser. */
+"browser_signup"
+/** The framework's Google OAuth callback owns this event. */
+ | "google_oauth"
+/** Federated SSO provisioning an identity into a sibling app. */
+ | "sso_jit";
 /**
  * Request-scoped browser attribution captured at the signup boundary.
  * Better Auth may create the user in a later async callback where the
@@ -103,8 +118,15 @@ export declare function signupAttributionFromCookieHeader(cookieHeader: string |
  * Capture all browser attribution needed by the server-side signup event.
  * Keep this as one boundary helper so every signup entry point carries the
  * same values into Better Auth's user-create hook.
+ *
+ * Returns `undefined` when the request carried neither cookie. A browser that
+ * ran our client script always has `an_ft`, so "no cookies at all" means no
+ * browser — a server-side backfill or provisioning call. Reporting that as
+ * `referral_source: "direct"` is the coercion that made this metric unusable:
+ * it renders "we never saw a visitor" identical to "a visitor arrived with no
+ * campaign", and only the second one is direct traffic.
  */
-export declare function signupAttributionContextFromCookieHeader(cookieHeader: string | null | undefined): SignupAttributionContext;
+export declare function signupAttributionContextFromCookieHeader(cookieHeader: string | null | undefined): SignupAttributionContext | undefined;
 /** Serialize the bounded attribution handoff for a Better Auth request. */
 export declare function encodeSignupAttributionContext(context: SignupAttributionContext): string;
 /**
@@ -112,7 +134,15 @@ export declare function encodeSignupAttributionContext(context: SignupAttributio
  * attribution, so the caller can safely fall back to the request cookie.
  */
 export declare function decodeSignupAttributionContext(value: string | null | undefined): SignupAttributionContext | undefined;
-/** Add the explicit handoff to a Better Auth request/API header set. */
-export declare function addSignupAttributionHeader(headers: HeadersInit | undefined, context: SignupAttributionContext): Headers;
+/**
+ * Stamp the explicit handoff onto a Better Auth request/API header set.
+ *
+ * This is the only writer of the handoff header, and it always writes: with a
+ * context it sets ours, without one it deletes whatever was there. The header
+ * is unsigned and outranks the request cookie when the hook reads it, so an
+ * inbound copy from the public internet is an attacker-supplied `anonymous_id`
+ * and campaign for someone else's signup row. Never merge — replace.
+ */
+export declare function addSignupAttributionHeader(headers: HeadersInit | undefined, context: SignupAttributionContext | undefined): Headers;
 /** Read the explicit handoff from Better Auth's request context headers. */
 export declare function signupAttributionContextFromHeaders(headers: Headers | null | undefined): SignupAttributionContext | undefined;

package/dist/server/attribution.js

@@ -185,11 +185,21 @@ export function signupAttributionFromCookieHeader(cookieHeader) {
  * Capture all browser attribution needed by the server-side signup event.
  * Keep this as one boundary helper so every signup entry point carries the
  * same values into Better Auth's user-create hook.
+ *
+ * Returns `undefined` when the request carried neither cookie. A browser that
+ * ran our client script always has `an_ft`, so "no cookies at all" means no
+ * browser — a server-side backfill or provisioning call. Reporting that as
+ * `referral_source: "direct"` is the coercion that made this metric unusable:
+ * it renders "we never saw a visitor" identical to "a visitor arrived with no
+ * campaign", and only the second one is direct traffic.
  */
 export function signupAttributionContextFromCookieHeader(cookieHeader) {
+    const firstTouch = readFirstTouchAttribution(cookieHeader);
     const anonymousId = readAnalyticsAnonymousId(cookieHeader);
+    if (!firstTouch && !anonymousId)
+        return undefined;
     return {
-        attribution: signupAttributionFromCookieHeader(cookieHeader),
+        attribution: deriveSignupAttribution(firstTouch),
         ...(anonymousId ? { anonymousId } : {}),
     };
 }
@@ -236,9 +246,21 @@ export function decodeSignupAttributionContext(value) {
         return undefined;
     }
 }
-/** Add the explicit handoff to a Better Auth request/API header set. */
+/**
+ * Stamp the explicit handoff onto a Better Auth request/API header set.
+ *
+ * This is the only writer of the handoff header, and it always writes: with a
+ * context it sets ours, without one it deletes whatever was there. The header
+ * is unsigned and outranks the request cookie when the hook reads it, so an
+ * inbound copy from the public internet is an attacker-supplied `anonymous_id`
+ * and campaign for someone else's signup row. Never merge — replace.
+ */
 export function addSignupAttributionHeader(headers, context) {
     const result = new Headers(headers);
+    if (!context) {
+        result.delete(SIGNUP_ATTRIBUTION_HEADER_NAME);
+        return result;
+    }
     result.set(SIGNUP_ATTRIBUTION_HEADER_NAME, encodeSignupAttributionContext(context));
     return result;
 }

package/dist/server/auth.js

@@ -61,7 +61,7 @@ import { getAppProductionUrl } from "./app-url.js";
 import { addSignupAttributionHeader, readAnalyticsAnonymousId, readFirstTouchAttribution, signupAttributionContextFromCookieHeader, signupAttributionFromCookieHeader, } from "./attribution.js";
 import { getAuthLoginMode } from "./auth-login-mode.js";
 import { injectBetaOptOutPersistence } from "./beta-opt-out-html.js";
-import { createBetterAuthSessionForEmail, ensureGoogleAuthIdentity, getAuthSecret, getBetterAuth, getBetterAuthSync, isDeployPreview, } from "./better-auth-instance.js";
+import { createBetterAuthSessionForEmail, ensureGoogleAuthIdentity, getBetterAuthUserIdForEmail, getAuthSecret, getBetterAuth, getBetterAuthSync, isDeployPreview, } from "./better-auth-instance.js";
 import { BUILDER_CONNECT_PARAM, BUILDER_RELAY_PATH, BUILDER_RELAY_STATE_PARAM, verifyBuilderConnectTokenAndGetOwner, verifyBuilderPreviewRelayStateForCallback, } from "./builder-browser.js";
 import { resolveAuthCookieNamespace } from "./cookie-namespace.js";
 import { getAllowedCorsOrigin, readCorsAllowedOrigins, } from "./cors-origins.js";
@@ -93,6 +93,13 @@ function withSignupAttributionContext(cookieHeader, fn) {
         signupAttribution,
     }, fn);
 }
+/**
+ * Replace the internal attribution handoff on a request bound for Better
+ * Auth. Call this on every such request, including the ones with no
+ * attribution to add — the header is unsigned and outranks the request cookie
+ * inside the user-create hook, so an inbound copy is a stranger writing the
+ * `anonymous_id` and campaign of somebody else's signup.
+ */
 function requestWithSignupAttribution(request, signupAttribution) {
     return new Request(request, {
         headers: addSignupAttributionHeader(request.headers, signupAttribution),
@@ -3357,10 +3364,20 @@ async function mountBetterAuthRoutes(app, options) {
                     mobile,
                     trackSignup: {
                         authProvider: "google",
-                        authUserId: typeof user.id === "string" ? user.id : undefined,
+                        // The signup event joins to `referrer_user` in the virality
+                        // panels, which is always a Better Auth id — the Google profile
+                        // id that used to go here joined to nothing. Only looked up when
+                        // the event will actually be emitted.
+                        authUserId: isNewGoogleUser
+                            ? await getBetterAuthUserIdForEmail(email)
+                            : undefined,
                         name: typeof user.name === "string" ? user.name : undefined,
                         attribution: signupAttribution,
                         signupAnonymousId,
+                        // `ensureGoogleAuthIdentity` above already wrote the canonical
+                        // row, so this callback is the only thing that still knows
+                        // whether the person is new.
+                        isNewUser: isNewGoogleUser,
                     },
                 });
                 logGoogleOAuthDebug(event, "callback-session-created", {
@@ -3859,9 +3876,7 @@ async function mountBetterAuthRoutes(app, options) {
                 // validation error.
             }
         }
-        if (signupAttribution) {
-            requestForAuth = requestWithSignupAttribution(requestForAuth, signupAttribution);
-        }
+        requestForAuth = requestWithSignupAttribution(requestForAuth, signupAttribution);
         let response;
         try {
             response = await (isEmailSignup

package/dist/server/better-auth-instance.d.ts

@@ -6,12 +6,62 @@
  * implementation detail behind those interfaces.
  */
 import { type BetterAuthOptions } from "better-auth";
+import { type SignupOrigin } from "./attribution.js";
 export { getAuthLoginMode, resolveAuthLoginMode, resolveAuthLoginModeFromReadiness, type AuthLoginMode, } from "./auth-login-mode.js";
 export declare function hasBetterAuthUserEmail(email: string): Promise<boolean>;
+/**
+ * The canonical Better Auth user id for an email, or `undefined` when there
+ * is no row (or the adapter is unavailable).
+ *
+ * Signup events must carry this id, not the identity provider's subject id:
+ * the virality panels self-join `auth_user_id` against `referrer_user`, and
+ * `referrer_user` is always a Better Auth id, so a Google profile id in that
+ * column silently joins to nothing.
+ */
+export declare function getBetterAuthUserIdForEmail(email: string): Promise<string | undefined>;
+/**
+ * The endpoint context Better Auth (1.6.x) hands to `user.create.after`. It is
+ * `null` for any row created through `internalAdapter` outside an endpoint —
+ * see `emitSignupEventForCreatedUser`.
+ */
+export interface BetterAuthUserCreateContext {
+    headers?: Headers | null;
+    request?: {
+        headers?: Headers | null;
+        url?: string;
+    } | null;
+}
+/**
+ * Emit the `signup` event for a freshly created Better Auth `user` row — but
+ * only when that row is an actual person signing up.
+ *
+ * Better Auth runs its create hook on every `user` insert. Only inserts made
+ * through one of its HTTP endpoints carry the originating request; everything
+ * that reaches the row through `internalAdapter` directly gets a null context,
+ * because `getCurrentAuthContext()` throws outside an endpoint. Two production
+ * paths do exactly that, and neither is an acquisition:
+ *
+ *   - `ensureCanonicalUserForLegacySession` backfills a canonical row for
+ *     someone who signed up long ago, on an ordinary authenticated request.
+ *   - `ensureGoogleAuthIdentity` provisions the canonical row during the Google
+ *     callback, whose own attributed event `createOAuthSession` emits.
+ *
+ * Emitting for those is what broke campaign reporting: they arrived with no
+ * browser context and were recorded as `referral_source: "direct"`, so ~94% of
+ * `better-auth` signups were unattributable rows that were never signups, and
+ * one person provisioned across sibling apps counted as a dozen. A row insert
+ * is not an acquisition, so a context-free insert emits nothing at all.
+ */
+export declare function emitSignupEventForCreatedUser(user: {
+    id?: string;
+    email?: string;
+    name?: string | null;
+}, context?: BetterAuthUserCreateContext | null): Promise<void>;
 /** Return whether the canonical user has a verified Google account link. */
 export declare function hasGoogleAuthIdentity(email: string): Promise<boolean | undefined>;
-export declare function trackSignupEvent({ authProvider, authUserId, email, name, attribution, anonymousId, }: {
+export declare function trackSignupEvent({ authProvider, origin, authUserId, email, name, attribution, anonymousId, }: {
     authProvider: string;
+    origin: SignupOrigin;
     authUserId?: string;
     email: string;
     name?: string | null;
@@ -20,7 +70,9 @@ export declare function trackSignupEvent({ authProvider, authUserId, email, name
      * cookie (see `server/attribution.ts`). Snake_case keys such as
      * `referral_source`, `referrer_user`, and the UTM passthrough are merged
      * into the `signup` event so we can measure where new users came from.
-     * `undefined` values are dropped; a missing object is a clean no-op.
+     * `undefined` values are dropped; a missing object is a clean no-op — and
+     * it must stay a no-op rather than defaulting to `direct`, so a signup we
+     * could not attribute stays visibly different from an unattributed visit.
      */
     attribution?: Record<string, string | undefined>;
     anonymousId?: string;

package/dist/server/better-auth-instance.js

@@ -56,6 +56,95 @@ export async function hasBetterAuthUserEmail(email) {
         .catch(() => null);
     return !!existing?.user?.email;
 }
+/**
+ * The canonical Better Auth user id for an email, or `undefined` when there
+ * is no row (or the adapter is unavailable).
+ *
+ * Signup events must carry this id, not the identity provider's subject id:
+ * the virality panels self-join `auth_user_id` against `referrer_user`, and
+ * `referrer_user` is always a Better Auth id, so a Google profile id in that
+ * column silently joins to nothing.
+ */
+export async function getBetterAuthUserIdForEmail(email) {
+    const adapter = await getBetterAuthInternalAdapter();
+    if (!adapter)
+        return undefined;
+    try {
+        const existing = await adapter.findUserByEmail(email.trim().toLowerCase(), {
+            includeAccounts: false,
+        });
+        return existing?.user?.id || undefined;
+    }
+    catch (error) {
+        // coercion-ok: this is analytics enrichment on the sign-in path. Failing
+        // the sign-in over it would be worse, and the only consequence is one
+        // event missing `auth_user_id` — never a wrong id. Logged, not swallowed.
+        console.error("[auth] failed to resolve the canonical user id for a signup event", error);
+        return undefined;
+    }
+}
+/**
+ * Emit the `signup` event for a freshly created Better Auth `user` row — but
+ * only when that row is an actual person signing up.
+ *
+ * Better Auth runs its create hook on every `user` insert. Only inserts made
+ * through one of its HTTP endpoints carry the originating request; everything
+ * that reaches the row through `internalAdapter` directly gets a null context,
+ * because `getCurrentAuthContext()` throws outside an endpoint. Two production
+ * paths do exactly that, and neither is an acquisition:
+ *
+ *   - `ensureCanonicalUserForLegacySession` backfills a canonical row for
+ *     someone who signed up long ago, on an ordinary authenticated request.
+ *   - `ensureGoogleAuthIdentity` provisions the canonical row during the Google
+ *     callback, whose own attributed event `createOAuthSession` emits.
+ *
+ * Emitting for those is what broke campaign reporting: they arrived with no
+ * browser context and were recorded as `referral_source: "direct"`, so ~94% of
+ * `better-auth` signups were unattributable rows that were never signups, and
+ * one person provisioned across sibling apps counted as a dozen. A row insert
+ * is not an acquisition, so a context-free insert emits nothing at all.
+ */
+export async function emitSignupEventForCreatedUser(user, context) {
+    const email = user?.email;
+    if (!email)
+        return;
+    const requestHeaders = context?.headers ?? context?.request?.headers ?? null;
+    if (!requestHeaders)
+        return;
+    const scoped = hasContinuationLocalRequestContext()
+        ? getRequestContext()
+        : undefined;
+    let attribution;
+    let anonymousId;
+    try {
+        const browser = 
+        // The signed magic-link token is the only source that survives the link
+        // being opened in a different browser than the one that requested it.
+        (context?.request?.url?.includes("newUserCallbackURL")
+            ? readMagicLinkSignupAttribution(context.request.url, getAuthSecret())
+            : undefined) ??
+            scoped?.signupAttribution ??
+            signupAttributionContextFromHeaders(requestHeaders) ??
+            signupAttributionContextFromCookieHeader(requestHeaders.get("cookie"));
+        attribution = browser?.attribution;
+        anonymousId = browser?.anonymousId;
+    }
+    catch (err) {
+        // Analytics must never block signup, but a parse failure is not "this
+        // visitor came direct" — leave both unset so the event shows the gap
+        // instead of inventing a source for it.
+        console.error("[auth] failed to derive signup attribution", err);
+    }
+    await trackSignupEvent({
+        authProvider: "better-auth",
+        origin: scoped?.signupOrigin ?? "browser_signup",
+        authUserId: user.id,
+        email,
+        name: user.name,
+        attribution,
+        anonymousId,
+    });
+}
 /** Return whether the canonical user has a verified Google account link. */
 export async function hasGoogleAuthIdentity(email) {
     const adapter = await getBetterAuthInternalAdapter();
@@ -67,7 +156,7 @@ export async function hasGoogleAuthIdentity(email) {
     return (existing?.accounts.some((account) => account.providerId === "google") ??
         false);
 }
-export async function trackSignupEvent({ authProvider, authUserId, email, name, attribution, anonymousId, }) {
+export async function trackSignupEvent({ authProvider, origin, authUserId, email, name, attribution, anonymousId, }) {
     identify(email, {
         email,
         name: name ?? undefined,
@@ -84,6 +173,7 @@ export async function trackSignupEvent({ authProvider, authUserId, email, name,
     track("signup", {
         ...resolveSignupTrackingProperties(),
         auth_provider: authProvider,
+        signup_origin: origin,
         ...(authUserId ? { auth_user_id: authUserId } : {}),
         ...cleanAttribution,
     }, { userId: email, ...(anonymousId ? { anonymousId } : {}) });
@@ -1064,54 +1154,12 @@ async function createBetterAuthInstance(config) {
                     // signups the callback request's headers), which is where the
                     // browser's `an_ft` first-touch cookie rides in.
                     context) => {
-                        // When a newly-created user's email has pending org invitations
-                        // (common when someone is invited *before* they've signed up),
-                        // auto-accept them so the user lands in the org on their very
-                        // first page load instead of a blank-slate workspace.
                         const email = user?.email;
                         if (!email)
                             return;
-                        // Derive first-touch referral attribution from the request's
-                        // cookie header. Never let attribution parsing throw or block
-                        // signup — on any error fall back to `direct`.
-                        let attribution;
-                        let anonymousId;
-                        try {
-                            const cookieHeader = context?.headers?.get("cookie") ??
-                                context?.request?.headers?.get("cookie") ??
-                                null;
-                            const scopedSignupAttribution = hasContinuationLocalRequestContext()
-                                ? getRequestContext()?.signupAttribution
-                                : undefined;
-                            const requestSignupAttribution = signupAttributionContextFromCookieHeader(cookieHeader);
-                            const headerSignupAttribution = signupAttributionContextFromHeaders(context?.headers) ??
-                                signupAttributionContextFromHeaders(context?.request?.headers);
-                            const magicLinkAttribution = context?.request?.url?.includes("newUserCallbackURL")
-                                ? readMagicLinkSignupAttribution(context.request.url, getAuthSecret())
-                                : undefined;
-                            attribution =
-                                magicLinkAttribution?.attribution ??
-                                    scopedSignupAttribution?.attribution ??
-                                    headerSignupAttribution?.attribution ??
-                                    requestSignupAttribution.attribution;
-                            anonymousId =
-                                magicLinkAttribution?.anonymousId ??
-                                    scopedSignupAttribution?.anonymousId ??
-                                    headerSignupAttribution?.anonymousId ??
-                                    requestSignupAttribution.anonymousId;
-                        }
-                        catch (err) {
-                            console.error("[auth] failed to derive signup attribution", err);
-                            attribution = undefined;
-                        }
-                        await trackSignupEvent({
-                            authProvider: "better-auth",
-                            authUserId: user.id,
-                            email,
-                            name: user.name,
-                            attribution,
-                            anonymousId,
-                        });
+                        await emitSignupEventForCreatedUser(user, context);
+                        // Invitations and domain auto-join are about the row existing, not
+                        // about how it got here, so they run for backfills too.
                         try {
                             await acceptPendingInvitationsForEmail(email);
                         }

package/dist/server/google-oauth.d.ts

@@ -192,6 +192,15 @@ export declare function createOAuthSession(event: H3Event, email: string, opts:
         name?: string | null;
         attribution?: Record<string, string | undefined>;
         signupAnonymousId?: string;
+        /**
+         * Whether this callback created the account, decided by the caller at
+         * the moment it created it. Callers that provision the canonical user
+         * before getting here MUST pass this: the `hasBetterAuthUserEmail`
+         * probe below then reads the row they just wrote and concludes the
+         * person is an existing user, which silently deleted the only
+         * attributed signup event Google sign-in produces.
+         */
+        isNewUser?: boolean;
     };
 }): Promise<OAuthSessionResult>;
 /**

package/dist/server/google-oauth.js

@@ -562,11 +562,12 @@ export async function createOAuthSession(event, email, opts) {
     let shouldTrackSignup = false;
     if (!opts.hasProductionSession || needsDeepLink) {
         if (opts.trackSignup && !opts.hasProductionSession) {
-            const [hasLegacySession, hasBetterAuthUser] = await Promise.all([
-                hasLegacySessionForEmail(email).catch(() => true),
-                hasBetterAuthUserEmail(email).catch(() => true),
-            ]);
-            shouldTrackSignup = !hasLegacySession && !hasBetterAuthUser;
+            shouldTrackSignup =
+                opts.trackSignup.isNewUser ??
+                    (await Promise.all([
+                        hasLegacySessionForEmail(email).catch(() => true),
+                        hasBetterAuthUserEmail(email).catch(() => true),
+                    ]).then(([hasLegacySession, hasUser]) => !hasLegacySession && !hasUser));
         }
         sessionToken = crypto.randomBytes(32).toString("hex");
         await addSession(sessionToken, email);
@@ -578,6 +579,7 @@ export async function createOAuthSession(event, email, opts) {
                 readAnalyticsAnonymousId(getHeader(event, "cookie") ?? null);
             await trackSignupEvent({
                 authProvider: opts.trackSignup.authProvider,
+                origin: "google_oauth",
                 authUserId: opts.trackSignup.authUserId,
                 email,
                 name: opts.trackSignup.name,

package/dist/server/identity-sso.js

@@ -474,6 +474,10 @@ export async function handleIdentitySso(event, subpath) {
                 ? runWithRequestContext({
                     ...(getRequestContext() ?? {}),
                     signupAttribution,
+                    // This person already signed up somewhere; we are provisioning
+                    // them into this app. Counting it as an acquisition is how one
+                    // human became a dozen "signups" across sibling apps.
+                    signupOrigin: "sso_jit",
                 }, linkIdentity)
                 : linkIdentity());
         }

package/dist/server/request-context.d.ts

@@ -115,6 +115,12 @@ export interface RequestContext {
      * async user-create hook. Analytics-only; never used for authorization.
      */
     signupAttribution?: SignupAttributionContext;
+    /**
+     * Which flow is creating a user row on this request. Set by callers that
+     * provision an identity rather than acquire a new person, so the signup
+     * event they trigger says so instead of impersonating a browser signup.
+     */
+    signupOrigin?: import("./attribution.js").SignupOrigin;
     /** Canonical client surface for analytics attribution. */
     clientPlatform?: import("../shared/analytics-platform.js").AnalyticsClientPlatform;
     /**

package/dist/tracking/providers.js

@@ -324,6 +324,9 @@ function createWebhookProvider(url, authHeader) {
                 event: event.name,
                 properties: event.properties,
                 userId: event.userId,
+                // Without this a webhook consumer cannot join a signup back to the
+                // anonymous pageviews that preceded it — the whole point of the id.
+                anonymousId: event.anonymousId,
                 sessionId: event.sessionId,
                 timestamp: event.timestamp,
             }), extra);

package/dist/vite/client.js

@@ -1680,6 +1680,10 @@ function virtualModuleIdFromRuntimeUrl(runtimeUrl) {
 }
 async function loadMountedEmbedRuntimeModule(server, runtimeUrl) {
     const virtualId = virtualModuleIdFromRuntimeUrl(runtimeUrl);
+    // transform import to encode virtual modules in vite as these imports don't work in the browser
+    const result = await server.transformRequest(virtualId ?? runtimeUrl);
+    if (typeof result?.code === "string")
+        return result.code;
     if (virtualId) {
         const loaded = await server.pluginContainer?.load?.(virtualId);
         if (typeof loaded === "string")
@@ -1687,8 +1691,7 @@ async function loadMountedEmbedRuntimeModule(server, runtimeUrl) {
         if (loaded && typeof loaded.code === "string")
             return loaded.code;
     }
-    const result = await server.transformRequest(runtimeUrl);
-    return result?.code ?? null;
+    return null;
 }
 function serveMountedEmbedRuntimeModule(server, req, res, base) {
     if (req.method !== "GET" && req.method !== "HEAD")

package/docs/content/docs-components.mdx

@@ -197,6 +197,7 @@ Each card is a `###` heading (optionally linked) followed by the description. Ca
 | `plug`       | integrations, connected tools           |
 | `network`    | cross-app or distributed communication  |
 | `terminal`   | CLI, scripts, terminal-driven workflows |
+| `calendar`   | scheduling, dates, time-based features  |
 
 The grid defaults to 3 columns. Set `columns` (1-4) on the opening tag to override it, e.g. `<Cards columns={2}>`. Below 640px the grid always collapses to a single column regardless of `columns`.
 
@@ -337,7 +338,25 @@ Define one action. The agent calls it as a tool, the UI calls it through a React
 </Comparison>
 ```
 
-Add more `###` sections to get 3 or 4 columns (max 4). The red/green label accent only applies to headings that exactly match `Before`, `Old`, `Without` (red) or `After`, `New`, `With` (green).
+Add more `###` sections to get 3 or 4 columns (max 4). The red/green label accent applies automatically to headings that exactly match `Before`, `Old`, `Without` (red) or `After`, `New`, `With` (green).
+
+For any other pairing, an explicit `:color:` prefix sets a column's accent directly, the same shortcode idiom `Cards` uses for `:icon:`:
+
+```mdx
+<Comparison>
+
+### :blue: You ask
+
+"Am I free Thursday afternoon?"
+
+### :green: What happens
+
+The agent answers in chat. Nothing on screen changes.
+
+</Comparison>
+```
+
+`color` accepts `blue`, `green`, `red`, or `yellow`, matching `Badge`'s color naming. Each routes through a real theme token (the site's brand blue, or the same semantic red/yellow/green used elsewhere) rather than a raw color, so it stays correct in both themes. An explicit `color` always wins over the Before/After heuristic.
 
 ---