@agent-native/core 0.141.2 → 0.141.4

package/dist/brand-kit/tokens.d.ts

@@ -0,0 +1,91 @@
+/**
+ * `@agent-native/core/brand-kit/tokens`
+ *
+ * Pure helpers for the named-token vocabulary a Brand Kit stores alongside its
+ * seven color roles. Kept on its own subpath (no `design-token-utils` re-export)
+ * so browser code can import the CSS-safety predicates without pulling the
+ * server-side extraction stack into the bundle.
+ */
+import type { BrandKitToken, BrandKitTokenType } from "./types.js";
+/**
+ * Upper bound on a single kit's stored vocabulary. Large systems legitimately
+ * define hundreds of tokens; this only stops an unbounded scrape landing in SQL.
+ */
+export declare const MAX_BRAND_KIT_TOKENS = 500;
+export declare function isSafeCssVarName(value: string): boolean;
+/**
+ * Token values are spliced raw into `:root { … }` declarations, so anything that
+ * could terminate a declaration or break out of a `<style>` element is unsafe.
+ */
+export declare function isSafeCssTokenValue(value: string): boolean;
+export declare function isColorTokenValue(value: string): boolean;
+/**
+ * Bucket a token, trusting the value's shape over the name's keywords.
+ *
+ * Name-first classification called Primer's `--text-body-size-medium: 1rem` a
+ * color because the name contains "text", which then rendered a swatch with
+ * `background: 1rem`. A dimension is never a color however the token is named.
+ */
+export declare function classifyBrandKitToken(name: string, value: string): BrandKitTokenType;
+/** Title-case display name derived from a CSS var, e.g. `--primary-color`. */
+export declare function friendlyTokenName(cssVar: string): string;
+export type BrandKitTokenRejectionReason = "malformed" | "unsafe-css-var" | "unsafe-value" | "over-limit";
+export interface BrandKitTokenRejection {
+    reason: BrandKitTokenRejectionReason;
+    /** Best-effort identifier for the offending entry, for error messages. */
+    label: string;
+}
+export interface NormalizedBrandKitTokens {
+    tokens: BrandKitToken[];
+    /**
+     * Entries that could not be stored. Callers must surface these - a kit that
+     * silently kept 4 of 40 tokens reads downstream as a 4-token design system.
+     */
+    rejected: BrandKitTokenRejection[];
+}
+/**
+ * Coerce untrusted token JSON into storable tokens, reporting every entry it
+ * could not accept. Later duplicates of a `cssVar` win, matching the overlay
+ * order importers use.
+ */
+export declare function normalizeBrandKitTokens(input: unknown): NormalizedBrandKitTokens;
+/** Human-readable summary of why tokens were refused, for thrown errors. */
+export declare function describeBrandKitTokenRejections(rejected: readonly BrandKitTokenRejection[]): string;
+/**
+ * The seven colour roles plus radius/spacing, as tokens. Derived from a kit's
+ * summary fields rather than named by the source system, so they carry no
+ * `group`.
+ */
+export declare function brandKitRoleTokens(data: {
+    colors?: object | null;
+    borders?: {
+        radius?: string;
+    } | null;
+    spacing?: object | null;
+} | null | undefined, source?: string): BrandKitToken[];
+/**
+ * Read a kit's named tokens out of a raw CSS block. A kit's `customCSS` already
+ * spells out the source system's real token names. Declaration order wins on
+ * duplicates, matching the cascade.
+ */
+export declare function parseBrandKitTokensFromCss(css: string, source?: string): BrandKitToken[];
+/**
+ * The kit's named vocabulary: its stored `tokens` when it has them, else the
+ * names its `customCSS` declares. Kits predating `tokens` still carry real names
+ * in CSS, so reading only `tokens` would report them as having none.
+ */
+export declare function resolveBrandKitTokens(data: {
+    tokens?: unknown;
+    customCSS?: unknown;
+} | null | undefined, cssSource?: string): BrandKitToken[];
+export interface BrandKitTokenGroup {
+    /** The source's own group path when it has one, else the token type. */
+    label: string;
+    type: BrandKitTokenType;
+    tokens: BrandKitToken[];
+}
+/**
+ * Group tokens for display, preserving the source's collection paths. Groups sort
+ * by token type so colors lead, then alphabetically within a type.
+ */
+export declare function groupBrandKitTokens(tokens: readonly BrandKitToken[]): BrandKitTokenGroup[];

package/dist/brand-kit/tokens.js

@@ -0,0 +1,279 @@
+/**
+ * `@agent-native/core/brand-kit/tokens`
+ *
+ * Pure helpers for the named-token vocabulary a Brand Kit stores alongside its
+ * seven color roles. Kept on its own subpath (no `design-token-utils` re-export)
+ * so browser code can import the CSS-safety predicates without pulling the
+ * server-side extraction stack into the bundle.
+ */
+const BRAND_KIT_TOKEN_TYPES = [
+    "color",
+    "typography",
+    "spacing",
+    "radius",
+    "shadow",
+    "other",
+];
+/**
+ * Upper bound on a single kit's stored vocabulary. Large systems legitimately
+ * define hundreds of tokens; this only stops an unbounded scrape landing in SQL.
+ */
+export const MAX_BRAND_KIT_TOKENS = 500;
+const CSS_CUSTOM_PROPERTY_NAME = /^--[-_a-zA-Z0-9]+$/;
+const COLOR_FUNCTION_OR_HEX = /^(#[0-9a-fA-F]{3,8}|rgba?\(|hsla?\(|oklch\(|color\()/i;
+const NAMED_CSS_COLORS = new Set([
+    "red",
+    "blue",
+    "green",
+    "yellow",
+    "orange",
+    "purple",
+    "pink",
+    "cyan",
+    "magenta",
+    "teal",
+    "navy",
+    "maroon",
+    "coral",
+    "salmon",
+    "gold",
+    "silver",
+    "gray",
+    "grey",
+    "indigo",
+    "violet",
+    "lime",
+    "olive",
+    "aqua",
+    "fuchsia",
+    "crimson",
+    "turquoise",
+    "ivory",
+    "beige",
+    "lavender",
+    "tan",
+    "khaki",
+    "plum",
+    "orchid",
+    "sienna",
+]);
+export function isSafeCssVarName(value) {
+    return CSS_CUSTOM_PROPERTY_NAME.test(value);
+}
+/**
+ * Token values are spliced raw into `:root { … }` declarations, so anything that
+ * could terminate a declaration or break out of a `<style>` element is unsafe.
+ */
+export function isSafeCssTokenValue(value) {
+    return (value.length > 0 &&
+        value.length <= 300 &&
+        !/[;{}<>]/.test(value) &&
+        !/\/\*/.test(value) &&
+        !/[\u0000-\u001f\u007f]/.test(value));
+}
+export function isColorTokenValue(value) {
+    const normalized = value.trim().toLowerCase();
+    return (COLOR_FUNCTION_OR_HEX.test(normalized) || NAMED_CSS_COLORS.has(normalized));
+}
+const COLOR_NAME_HINT = /color|bg|background|text|border|accent|primary|secondary|surface|muted|foreground|fill|stroke/i;
+const DIMENSION_VALUE = /^-?\d*\.?\d+(px|rem|em|ex|ch|%|vh|vw|vmin|vmax|pt|pc|cm|mm|in|s|ms|deg|fr)?$/i;
+/**
+ * Bucket a token, trusting the value's shape over the name's keywords.
+ *
+ * Name-first classification called Primer's `--text-body-size-medium: 1rem` a
+ * color because the name contains "text", which then rendered a swatch with
+ * `background: 1rem`. A dimension is never a color however the token is named.
+ */
+export function classifyBrandKitToken(name, value) {
+    const n = name.toLowerCase();
+    if (isColorTokenValue(value))
+        return "color";
+    if (/radius|rounded/i.test(n))
+        return "radius";
+    // `line-?height` and `letter` run before the spacing check so
+    // `letter-spacing` is type metrics, not layout spacing.
+    if (/font|size|leading|line-?height|letter|tracking|weight|heading|body|type/i.test(n)) {
+        return "typography";
+    }
+    if (/spacing|gap|padding|margin|space/i.test(n))
+        return "spacing";
+    if (/shadow|blur|drop/i.test(n))
+        return "shadow";
+    if (COLOR_NAME_HINT.test(n) && !DIMENSION_VALUE.test(value.trim())) {
+        return "color";
+    }
+    return "other";
+}
+/** Title-case display name derived from a CSS var, e.g. `--primary-color`. */
+export function friendlyTokenName(cssVar) {
+    return cssVar
+        .replace(/^--/, "")
+        .replace(/[-_]/g, " ")
+        .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+function readString(source, key) {
+    const value = source[key];
+    return typeof value === "string" ? value.trim() : "";
+}
+/**
+ * Coerce untrusted token JSON into storable tokens, reporting every entry it
+ * could not accept. Later duplicates of a `cssVar` win, matching the overlay
+ * order importers use.
+ */
+export function normalizeBrandKitTokens(input) {
+    if (input === undefined || input === null) {
+        return { tokens: [], rejected: [] };
+    }
+    if (!Array.isArray(input)) {
+        return { tokens: [], rejected: [{ reason: "malformed", label: "tokens" }] };
+    }
+    const byCssVar = new Map();
+    const rejected = [];
+    for (const entry of input) {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            rejected.push({ reason: "malformed", label: String(entry) });
+            continue;
+        }
+        const record = entry;
+        const cssVar = readString(record, "cssVar");
+        const value = readString(record, "value");
+        const name = readString(record, "name") || friendlyTokenName(cssVar);
+        if (!cssVar || !isSafeCssVarName(cssVar)) {
+            rejected.push({ reason: "unsafe-css-var", label: cssVar || name });
+            continue;
+        }
+        if (!isSafeCssTokenValue(value)) {
+            rejected.push({ reason: "unsafe-value", label: cssVar });
+            continue;
+        }
+        const declaredType = readString(record, "type");
+        const group = readString(record, "group");
+        const source = readString(record, "source");
+        byCssVar.set(cssVar, {
+            name,
+            cssVar,
+            value,
+            type: BRAND_KIT_TOKEN_TYPES.includes(declaredType)
+                ? declaredType
+                : classifyBrandKitToken(cssVar, value),
+            ...(group ? { group } : {}),
+            ...(source ? { source } : {}),
+        });
+    }
+    const tokens = [...byCssVar.values()];
+    if (tokens.length > MAX_BRAND_KIT_TOKENS) {
+        for (const token of tokens.slice(MAX_BRAND_KIT_TOKENS)) {
+            rejected.push({ reason: "over-limit", label: token.cssVar });
+        }
+    }
+    return { tokens: tokens.slice(0, MAX_BRAND_KIT_TOKENS), rejected };
+}
+/** Human-readable summary of why tokens were refused, for thrown errors. */
+export function describeBrandKitTokenRejections(rejected) {
+    return rejected
+        .slice(0, 10)
+        .map((entry) => `${entry.label} (${entry.reason})`)
+        .join(", ");
+}
+/** The CSS variable each colour role is published under. */
+const BRAND_KIT_COLOR_ROLE_VARS = {
+    primary: "--color-primary",
+    secondary: "--color-secondary",
+    accent: "--color-accent",
+    background: "--color-background",
+    surface: "--color-surface",
+    text: "--color-text",
+    textMuted: "--color-text-muted",
+};
+/**
+ * The seven colour roles plus radius/spacing, as tokens. Derived from a kit's
+ * summary fields rather than named by the source system, so they carry no
+ * `group`.
+ */
+export function brandKitRoleTokens(data, source = "Brand Kit") {
+    if (!data)
+        return [];
+    const out = [];
+    const push = (cssVar, value) => {
+        if (typeof value !== "string" || !value.trim())
+            return;
+        if (!isSafeCssVarName(cssVar) || !isSafeCssTokenValue(value.trim()))
+            return;
+        out.push({
+            name: friendlyTokenName(cssVar),
+            cssVar,
+            value: value.trim(),
+            type: classifyBrandKitToken(cssVar, value.trim()),
+            source,
+        });
+    };
+    const colors = (data.colors ?? {});
+    const spacing = (data.spacing ?? {});
+    for (const [role, cssVar] of Object.entries(BRAND_KIT_COLOR_ROLE_VARS)) {
+        push(cssVar, colors[role]);
+    }
+    push("--radius", data.borders?.radius);
+    push("--spacing-element-gap", spacing.elementGap);
+    push("--spacing-page-padding", spacing.pagePadding);
+    return out;
+}
+const CSS_CUSTOM_PROPERTY_DECLARATION = /(--[-_a-zA-Z0-9]+)\s*:\s*([^;{}]+)[;}]/g;
+/**
+ * Read a kit's named tokens out of a raw CSS block. A kit's `customCSS` already
+ * spells out the source system's real token names. Declaration order wins on
+ * duplicates, matching the cascade.
+ */
+export function parseBrandKitTokensFromCss(css, source) {
+    const byCssVar = new Map();
+    for (const match of css.matchAll(CSS_CUSTOM_PROPERTY_DECLARATION)) {
+        const cssVar = match[1];
+        const value = match[2].trim();
+        if (!isSafeCssVarName(cssVar) || !isSafeCssTokenValue(value))
+            continue;
+        byCssVar.set(cssVar, {
+            name: cssVar.replace(/^--/, ""),
+            cssVar,
+            value,
+            type: classifyBrandKitToken(cssVar, value),
+            ...(source ? { source } : {}),
+        });
+    }
+    return [...byCssVar.values()].slice(0, MAX_BRAND_KIT_TOKENS);
+}
+/**
+ * The kit's named vocabulary: its stored `tokens` when it has them, else the
+ * names its `customCSS` declares. Kits predating `tokens` still carry real names
+ * in CSS, so reading only `tokens` would report them as having none.
+ */
+export function resolveBrandKitTokens(data, cssSource) {
+    if (!data)
+        return [];
+    const stored = normalizeBrandKitTokens(data.tokens).tokens;
+    if (stored.length > 0)
+        return stored;
+    return typeof data.customCSS === "string"
+        ? parseBrandKitTokensFromCss(data.customCSS, cssSource)
+        : [];
+}
+/**
+ * Group tokens for display, preserving the source's collection paths. Groups sort
+ * by token type so colors lead, then alphabetically within a type.
+ */
+export function groupBrandKitTokens(tokens) {
+    const groups = new Map();
+    for (const token of tokens) {
+        const label = token.group?.trim() || token.type;
+        const key = `${token.type}::${label}`;
+        const existing = groups.get(key);
+        if (existing) {
+            existing.tokens.push(token);
+            continue;
+        }
+        groups.set(key, { label, type: token.type, tokens: [token] });
+    }
+    return [...groups.values()].sort((a, b) => {
+        const byType = BRAND_KIT_TOKEN_TYPES.indexOf(a.type) -
+            BRAND_KIT_TOKEN_TYPES.indexOf(b.type);
+        return byType !== 0 ? byType : a.label.localeCompare(b.label);
+    });
+}

package/dist/brand-kit/types.d.ts

@@ -23,6 +23,25 @@ export interface BrandKitColors {
     text: string;
     textMuted: string;
 }
+/** Semantic category a {@link BrandKitToken} belongs to. */
+export type BrandKitTokenType = "color" | "typography" | "spacing" | "radius" | "shadow" | "other";
+/**
+ * One token under the name its source design system uses. The seven
+ * {@link BrandKitColors} roles are a summary view, not a substitute: collapsing
+ * `interactive-01` into `secondary` discards the only name the design team has.
+ */
+export interface BrandKitToken {
+    name: string;
+    /** e.g. `--cds-interactive-01`. */
+    cssVar: string;
+    /** Resolved value, e.g. a hex color or `0.5rem`. */
+    value: string;
+    type: BrandKitTokenType;
+    /** Collection path as the source organises it, e.g. `Colors/Interactive`. */
+    group?: string;
+    /** e.g. `Carbon v11` or `globals.css`. */
+    source?: string;
+}
 /** Brand typography system. */
 export interface BrandKitTypography {
     headingFont: string;
@@ -76,6 +95,12 @@ export interface BrandKitData {
     spacing: BrandKitSpacing;
     borders: BrandKitBorders;
     logos: BrandKitLogo[];
+    /**
+     * The source system's full named vocabulary. Optional because kits predating
+     * it store only the role summary - absent means "never extracted", not "the
+     * system has none".
+     */
+    tokens?: BrandKitToken[];
     imageStyle?: BrandKitImageStyle;
     customCSS?: string;
     notes?: string;

package/dist/client/AssistantChat.js

@@ -1440,16 +1440,16 @@ const AssistantChatInner = forwardRef(function AssistantChatInner({ emptyStateTe
     const agentEngineConfigured = useAgentEngineConfigured(providerStatusChecksEnabled, { tabId, threadId });
     const modelCatalogMissing = modelCatalogConfirmsMissing(availableModels, modelListLoading);
     // The model picker has already resolved the same provider status shown in
-    // its setup choices. Use that settled signal to surface setup before a slow
-    // readiness request can accept a doomed submit; a later canonical configured
-    // response always wins over a stale catalog.
+    // its setup choices. Keep the signal available for the authoritative missing
+    // state, but do not surface setup while the readiness request is unresolved.
     const missingApiKey = agentEngineConfigured.state !== "configured" &&
         (agentEngineConfigured.missing || modelCatalogMissing);
-    // Unknown and unavailable are setup-required for this surface. Letting a
-    // submit through while the status route is still unreachable creates a run
-    // that can sit on "Thinking" forever when no provider is configured.
+    // Unknown and unavailable mean we do not know yet. Only an authoritative
+    // missing response may replace the composer with the setup card; otherwise
+    // connected users briefly see a false "Connect AI" state on first mount.
     const engineSetupRequired = providerStatusChecksEnabled &&
-        (agentEngineConfigured.state !== "configured" || missingApiKey);
+        agentEngineConfigured.state === "missing" &&
+        missingApiKey;
     const isComposerDisabled = composerDisabled;
     const [missingKeySetupOpen, setMissingKeySetupOpen] = useState(false);
     const requestMissingKeySetup = useCallback(() => {

package/dist/client/onboarding/FirstRunOnboarding.js

@@ -10,6 +10,7 @@ import { formatMcpServerError, useCreateMcpServer, useMcpServers, } from "../res
 import { useBuilderConnectFlow } from "../settings/useBuilderStatus.js";
 import { cn } from "../utils.js";
 import { shouldSkipFirstRunIntegrations } from "./first-run-enabled.js";
+import { listFirstRunOnboardingExtensions } from "./first-run-registry.js";
 import { useOnboarding } from "./use-onboarding.js";
 import { useOnboardingPreviewMode } from "./use-preview-mode.js";
 const BUILDER_MORE_SERVICES = [
@@ -26,10 +27,12 @@ export function FirstRunOnboarding({ skipIntegrations = shouldSkipFirstRunIntegr
     const previewMode = useOnboardingPreviewMode();
     const { firstRun, loading, error, profile, completeFirstRun } = useOnboarding({ preview: previewMode });
     const [screen, setScreen] = useState("intro");
+    const [extensionIndex, setExtensionIndex] = useState(0);
     const [integrationQuery, setIntegrationQuery] = useState("");
     const [integrationDialogId, setIntegrationDialogId] = useState(null);
     const [connectingIntegrationId, setConnectingIntegrationId] = useState(null);
     const [connectError, setConnectError] = useState(null);
+    const extensions = useMemo(() => listFirstRunOnboardingExtensions(), []);
     const mcpCatalog = useMemo(() => getDefaultMcpIntegrations(), []);
     const mcpServersQuery = useMcpServers();
     const createMcpServer = useCreateMcpServer();
@@ -86,8 +89,13 @@ export function FirstRunOnboarding({ skipIntegrations = shouldSkipFirstRunIntegr
         }));
         await completeFirstRun();
     };
-    const handleFinish = async () => {
-        await completeFirstRun();
+    const handleFinish = () => {
+        if (extensions.length === 0) {
+            void completeFirstRun();
+            return;
+        }
+        setExtensionIndex(0);
+        setScreen("extension");
     };
     const returnUrl = typeof window === "undefined"
         ? "/"
@@ -137,6 +145,22 @@ export function FirstRunOnboarding({ skipIntegrations = shouldSkipFirstRunIntegr
         }
         setIntegrationDialogId(integration.id);
     };
+    if (screen === "extension") {
+        const extension = extensions[extensionIndex];
+        if (!extension) {
+            void completeFirstRun();
+            return null;
+        }
+        const Extension = extension.component;
+        const advanceExtension = () => {
+            if (extensionIndex < extensions.length - 1) {
+                setExtensionIndex((current) => current + 1);
+                return;
+            }
+            void completeFirstRun();
+        };
+        return (_jsx(Extension, { onComplete: advanceExtension, onSkip: () => void completeFirstRun() }));
+    }
     if (screen === "intro") {
         return (_jsx(OnboardingShell, { profile: profile, screen: "intro", children: _jsxs("div", { className: "mx-auto flex w-full max-w-lg flex-col items-center text-center", children: [_jsxs("h1", { className: "text-3xl font-semibold tracking-[-0.05em] sm:text-4xl", children: ["Free forever.", _jsx("br", {}), _jsx("span", { className: "text-primary", children: "Open source for life." })] }), _jsxs("div", { className: "mt-7 grid w-full gap-2 text-left sm:grid-cols-3", children: [_jsxs("div", { className: "rounded-lg border border-border bg-card px-3 py-3", children: [_jsx("p", { className: "text-xs font-medium", children: "Fully customizable" }), _jsx("p", { className: "mt-1 text-[11px] leading-4 text-muted-foreground", children: "Change the UI, code, and behavior." })] }), _jsxs("div", { className: "rounded-lg border border-border bg-card px-3 py-3", children: [_jsx("p", { className: "text-xs font-medium", children: "Bring your own keys" }), _jsx("p", { className: "mt-1 text-[11px] leading-4 text-muted-foreground", children: "Use your own providers and accounts." })] }), _jsxs("div", { className: "rounded-lg border border-border bg-card px-3 py-3", children: [_jsx("p", { className: "text-xs font-medium", children: "Build your own" }), _jsx("p", { className: "mt-1 text-[11px] leading-4 text-muted-foreground", children: "Mix and match toolkit pieces in your own apps." })] })] }), _jsxs("button", { type: "button", className: cn(primaryButtonClass, "mt-6"), onClick: () => setScreen("choice"), children: ["Continue", _jsx(IconArrowRight, { size: 15 })] }), _jsxs("a", { href: "https://github.com/builderio/agent-native", target: "_blank", rel: "noreferrer", className: "mt-3 inline-flex items-center gap-1.5 text-xs text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", children: [_jsx(IconBrandGithub, { size: 14 }), _jsx("span", { children: "View source" }), _jsx(IconExternalLink, { size: 13 })] })] }) }));
     }

package/dist/client/onboarding/first-run-registry.d.ts

@@ -0,0 +1,25 @@
+import type { ComponentType } from "react";
+/**
+ * Props passed to an app-specific first-run onboarding step.
+ *
+ * Register one component per screen when an app needs a continuous, full-screen
+ * flow after the shared connection and agent-introduction screens.
+ */
+export interface FirstRunOnboardingExtensionProps {
+    /** Finish this step and open the next registered step, if any. */
+    onComplete: () => void;
+    /** Abort first-run onboarding without opening another app-specific step. */
+    onSkip: () => void;
+}
+/** A full-screen app step that follows the framework's connection setup. */
+export interface FirstRunOnboardingExtension {
+    id: string;
+    component: ComponentType<FirstRunOnboardingExtensionProps>;
+}
+/**
+ * Register the app-owned part of first-run onboarding. Registration is
+ * replaceable by id so Vite reloads do not stack duplicate screens.
+ */
+export declare function registerFirstRunOnboardingExtension(extension: FirstRunOnboardingExtension): void;
+/** Return app-specific first-run screens in registration order. */
+export declare function listFirstRunOnboardingExtensions(): readonly FirstRunOnboardingExtension[];

package/dist/client/onboarding/first-run-registry.js

@@ -0,0 +1,18 @@
+let extensions = [];
+/**
+ * Register the app-owned part of first-run onboarding. Registration is
+ * replaceable by id so Vite reloads do not stack duplicate screens.
+ */
+export function registerFirstRunOnboardingExtension(extension) {
+    if (!extension.id.trim()) {
+        throw new Error("registerFirstRunOnboardingExtension: extension.id is required");
+    }
+    extensions = [
+        ...extensions.filter((current) => current.id !== extension.id),
+        extension,
+    ];
+}
+/** Return app-specific first-run screens in registration order. */
+export function listFirstRunOnboardingExtensions() {
+    return extensions;
+}

package/dist/client/onboarding/index.d.ts

@@ -9,5 +9,7 @@ export { OnboardingPanel } from "./OnboardingPanel.js";
 export { OnboardingBanner } from "./OnboardingBanner.js";
 export { SetupButton } from "./SetupButton.js";
 export { FirstRunOnboarding } from "./FirstRunOnboarding.js";
+export { listFirstRunOnboardingExtensions, registerFirstRunOnboardingExtension, } from "./first-run-registry.js";
+export type { FirstRunOnboardingExtension, FirstRunOnboardingExtensionProps, } from "./first-run-registry.js";
 export type { OnboardingStep, OnboardingMethod, OnboardingMethodBadge, OnboardingFormField, OnboardingStepStatus, OnboardingCapability, OnboardingAppProfile, } from "../../onboarding/types.js";
 export { registerOnboardingStep, listOnboardingSteps, } from "../../onboarding/registry.js";

package/dist/client/onboarding/index.js

@@ -9,4 +9,5 @@ export { OnboardingPanel } from "./OnboardingPanel.js";
 export { OnboardingBanner } from "./OnboardingBanner.js";
 export { SetupButton } from "./SetupButton.js";
 export { FirstRunOnboarding } from "./FirstRunOnboarding.js";
+export { listFirstRunOnboardingExtensions, registerFirstRunOnboardingExtension, } from "./first-run-registry.js";
 export { registerOnboardingStep, listOnboardingSteps, } from "../../onboarding/registry.js";

package/dist/collab/awareness.d.ts

@@ -62,11 +62,11 @@ export declare const postAwareness: import("h3").EventHandlerWithFetch<import("h
     error: string;
     states?: undefined;
 } | {
-    error?: undefined;
     states: {
         clientId: number;
         state: string;
     }[];
+    error?: undefined;
 }>>;
 /**
  * GET /_agent-native/collab/:docId/users
@@ -77,9 +77,9 @@ export declare const getActiveUsers: import("h3").EventHandlerWithFetch<import("
     error: string;
     users?: undefined;
 } | {
-    error?: undefined;
     users: {
         clientId: number;
         lastSeen: number;
     }[];
+    error?: undefined;
 }>>;

package/dist/collab/routes.d.ts

@@ -26,8 +26,8 @@ export declare const getCollabState: import("h3").EventHandlerWithFetch<import("
  * Body: { update: string (base64), requestSource?: string }
  */
 export declare const postCollabUpdate: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/collab/struct-routes.d.ts

@@ -13,8 +13,8 @@
  * Body: { json: any, fieldName?: string, type?: "map"|"array", requestSource?: string }
  */
 export declare const postCollabJson: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/db/index.d.ts

@@ -21,7 +21,7 @@ export declare function createDb(config: DbConfig): Promise<(import("drizzle-orm
 })>;
 export type DrizzleDb = Awaited<ReturnType<typeof createDb>>;
 export { createGetDb } from "./create-get-db.js";
-export { runMigrations, type MigrationEntry, type MigrationSql, } from "./migrations.js";
+export { deferMigration, MIGRATION_DEFERRED, runMigrations, type MigrationEntry, type MigrationRunResult, type MigrationSql, } from "./migrations.js";
 export { getDbExec, createDbExec, getDatabaseUrl, getDialect, isLocalDatabase, isPostgres, intType, closeDbExec, type DbExec, type DbExecConfig, type DbExecQuery, type DbExecStatement, type Dialect, } from "./client.js";
 export { table, text, integer, now } from "./schema.js";
 export { ensureAdditiveColumns, type EnsureAdditiveColumnsOptions, type EnsureAdditiveColumnsResult, type EnsureAdditiveColumnsLogger, } from "./ensure-additive-columns.js";

package/dist/db/index.js

@@ -20,7 +20,7 @@ export async function createDb(config) {
     throw new Error(`Unsupported driver: ${config.driver}`);
 }
 export { createGetDb } from "./create-get-db.js";
-export { runMigrations, } from "./migrations.js";
+export { deferMigration, MIGRATION_DEFERRED, runMigrations, } from "./migrations.js";
 export { getDbExec, createDbExec, getDatabaseUrl, getDialect, isLocalDatabase, isPostgres, intType, closeDbExec, } from "./client.js";
 export { table, text, integer, now } from "./schema.js";
 export { ensureAdditiveColumns, } from "./ensure-additive-columns.js";

package/dist/db/migrations.d.ts

@@ -53,6 +53,14 @@ export type MigrationSql = string | {
     postgres?: string;
     sqlite?: string;
 };
+/**
+ * A run-only migration can defer its work without recording itself as applied.
+ * This is for serialized backfills where another instance owns the advisory
+ * lock; throwing would turn an expected loser into a startup retry storm.
+ */
+export declare const MIGRATION_DEFERRED: unique symbol;
+export declare function deferMigration(): typeof MIGRATION_DEFERRED;
+export type MigrationRunResult = void | typeof MIGRATION_DEFERRED;
 export interface MigrationEntry {
     version: number;
     sql: MigrationSql;
@@ -68,11 +76,13 @@ export interface MigrationEntry {
      * JS step for a backfill SQL cannot express — e.g. a repair whose value comes
      * from application-level parsing of a stored blob. Runs BEFORE this entry's
      * SQL and before the bookkeeping row is written, so a throw leaves the
-     * migration unrecorded and it retries on the next boot. Pass `sql: {}` for a
-     * run-only entry. Give run-only entries a `name`: the legacy version gate
+     * migration unrecorded and it retries on the next boot. Return
+     * `deferMigration()` when another instance owns a serialized backfill; the
+     * entry stays pending without logging a startup failure. Pass `sql: {}` for
+     * a run-only entry. Give run-only entries a `name`: the legacy version gate
      * would otherwise mark them applied via any later migration's MAX advance.
      */
-    run?: () => Promise<void>;
+    run?: () => Promise<MigrationRunResult>;
 }
 /**
  * Runs a list of migrations against the configured database, gated by a