@agent-native/core 0.139.0 → 0.140.0

package/dist/brand-kit/tokens.js

@@ -0,0 +1,280 @@
+/**
+ * `@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);
+    });
+}
+//# sourceMappingURL=tokens.js.map

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/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,10 +77,10 @@ export declare const getActiveUsers: import("h3").EventHandlerWithFetch<import("
     error: string;
     users?: undefined;
 } | {
+    error?: undefined;
     users: {
         clientId: number;
         lastSeen: number;
     }[];
-    error?: undefined;
 }>>;
 //# sourceMappingURL=awareness.d.ts.map

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/file-upload/actions/upload-image.d.ts

@@ -17,12 +17,12 @@ declare const _default: import("../../action.js").ActionDefinition<{
     id?: undefined;
     provider?: undefined;
 } | {
+    error?: undefined;
     configured?: undefined;
     connectPath?: undefined;
     url: string;
     id: string;
     provider: string;
-    error?: undefined;
 }>;
 export default _default;
 //# sourceMappingURL=upload-image.d.ts.map

package/dist/notifications/routes.d.ts

@@ -11,14 +11,14 @@
  *   DELETE /_agent-native/notifications/:id         — delete
  */
 export declare function createNotificationsHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<"" | import("./types.js").Notification[] | {
+    error?: undefined;
     count: number;
     updated?: undefined;
-    error?: undefined;
     ok?: undefined;
 } | {
+    error?: undefined;
     count?: undefined;
     updated: number;
-    error?: undefined;
     ok?: undefined;
 } | {
     count?: undefined;
@@ -26,9 +26,9 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
     error: string;
     ok?: undefined;
 } | {
+    error?: undefined;
     count?: undefined;
     updated?: undefined;
     ok: boolean;
-    error?: undefined;
 }>>;
 //# sourceMappingURL=routes.d.ts.map

package/dist/progress/routes.d.ts

@@ -15,7 +15,7 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>>;
 //# sourceMappingURL=routes.d.ts.map

package/dist/provider-api/actions/custom-provider-registration.d.ts

@@ -75,10 +75,8 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
         user: "user";
     }>>;
 }, z.core.$strip>>, {
-    deleted?: undefined;
     id?: undefined;
-    provider?: undefined;
-    found?: undefined;
+    deleted?: undefined;
     providers: {
         id: string;
         label: string;
@@ -89,14 +87,16 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
         updatedAt: number;
     }[];
     count: number;
+    provider?: undefined;
+    found?: undefined;
     registered?: undefined;
     label?: undefined;
     message?: undefined;
 } | {
-    deleted?: undefined;
-    count?: undefined;
     id?: undefined;
+    deleted?: undefined;
     providers?: undefined;
+    count?: undefined;
     found: boolean;
     provider: import("../custom-registry.js").CustomProviderConfig;
     registered?: undefined;
@@ -104,19 +104,19 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     message?: undefined;
 } | {
     deleted?: undefined;
+    providers?: undefined;
     count?: undefined;
     provider?: undefined;
-    providers?: undefined;
     found: boolean;
     id: string;
     registered?: undefined;
     label?: undefined;
     message?: undefined;
 } | {
+    providers?: undefined;
     count?: undefined;
     provider?: undefined;
     found?: undefined;
-    providers?: undefined;
     deleted: boolean;
     id: string;
     registered?: undefined;
@@ -124,10 +124,10 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     message?: undefined;
 } | {
     deleted?: undefined;
+    providers?: undefined;
     count?: undefined;
     provider?: undefined;
     found?: undefined;
-    providers?: undefined;
     registered: boolean;
     id: string;
     label: string;

package/dist/provider-api/actions/provider-api.d.ts

@@ -311,10 +311,9 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
         notes?: string | undefined;
         scope?: "org" | "user" | undefined;
     }, {
-        message?: undefined;
         id?: undefined;
+        provider?: undefined;
         deleted?: undefined;
-        found?: undefined;
         providers: {
             id: string;
             label: string;
@@ -325,45 +324,46 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
             updatedAt: number;
         }[];
         count: number;
-        provider?: undefined;
+        found?: undefined;
         registered?: undefined;
         label?: undefined;
-    } | {
         message?: undefined;
+    } | {
         id?: undefined;
-        deleted?: undefined;
         count?: undefined;
+        deleted?: undefined;
         providers?: undefined;
         found: boolean;
         provider: import("../custom-registry.js").CustomProviderConfig;
         registered?: undefined;
         label?: undefined;
-    } | {
         message?: undefined;
-        deleted?: undefined;
+    } | {
         count?: undefined;
-        providers?: undefined;
         provider?: undefined;
+        deleted?: undefined;
+        providers?: undefined;
         found: boolean;
         id: string;
         registered?: undefined;
         label?: undefined;
-    } | {
         message?: undefined;
-        found?: undefined;
+    } | {
         count?: undefined;
-        providers?: undefined;
         provider?: undefined;
+        providers?: undefined;
+        found?: undefined;
         deleted: boolean;
         id: string;
         registered?: undefined;
         label?: undefined;
+        message?: undefined;
     } | {
-        deleted?: undefined;
-        found?: undefined;
         count?: undefined;
-        providers?: undefined;
         provider?: undefined;
+        deleted?: undefined;
+        providers?: undefined;
+        found?: undefined;
         registered: boolean;
         id: string;
         label: string;

package/dist/provider-api/corpus-jobs.d.ts

@@ -73,7 +73,6 @@ export declare function createProviderCorpusJobAction(options: CreateProviderCor
     offset?: unknown;
     limit?: unknown;
 }, {
-    deleted?: undefined;
     jobs: {
         id: string;
         name: string;
@@ -84,6 +83,7 @@ export declare function createProviderCorpusJobAction(options: CreateProviderCor
         updatedAt: string;
     }[];
     total: number;
+    deleted?: undefined;
     jobId?: undefined;
 } | {
     jobs?: undefined;
@@ -91,9 +91,9 @@ export declare function createProviderCorpusJobAction(options: CreateProviderCor
     deleted: boolean;
     jobId: string;
 } | {
-    deleted?: undefined;
     jobs?: undefined;
     total?: undefined;
+    deleted?: undefined;
     jobId?: undefined;
     hits: Record<string, unknown>[];
     offset: number;

package/dist/resources/handlers.d.ts

@@ -48,8 +48,8 @@ export declare function handleUpdateResource(event: any): Promise<import("./stor
 }>;
 /** DELETE /_agent-native/resources/:id — delete a resource */
 export declare function handleDeleteResource(event: any): Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/server/agent-engine-api-key-route.d.ts

@@ -27,11 +27,11 @@ export declare function resolveAgentEngineApiKeyWriteTarget(event: H3Event, scop
 export declare function createAgentEngineApiKeyHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: any;
 } | {
+    error?: undefined;
     ok: boolean;
     key: string;
     baseUrlKey?: string;
     scope: AgentEngineApiKeyScope;
-    error?: undefined;
 }>>;
 export {};
 //# sourceMappingURL=agent-engine-api-key-route.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.139.0",
+  "version": "0.140.0",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -85,6 +85,7 @@
     "./automation": "./dist/automation/index.js",
     "./brand-kit": "./dist/brand-kit/index.js",
     "./brand-kit/fig": "./dist/brand-kit/fig/index.js",
+    "./brand-kit/tokens": "./dist/brand-kit/tokens.js",
     "./data-widgets": "./dist/data-widgets/index.js",
     "./action": {
       "types": "./dist/action.d.ts",