@agent-native/core 0.138.0 → 0.140.0

package/corpus/templates/design/shared/authored-color-styles.ts

@@ -0,0 +1,401 @@
+/**
+ * Read the colour each property was authored with, walking the cascade. A
+ * generated design styles through classes, so `el.style` is empty and computed
+ * has already flattened `var()`. Dependency-free: bundled into the bridge.
+ */
+
+const AUTHORED_COLOR_PROPERTIES = [
+  "color",
+  "backgroundColor",
+  "borderColor",
+  "outlineColor",
+  // Not colours themselves, but the only place a shadow's colour keeps its name.
+  "boxShadow",
+  "textShadow",
+] as const;
+
+/**
+ * A shorthand holding `var()` cannot be expanded, so CSSOM serialises its
+ * longhands as "" — indistinguishable from unset.
+ */
+const SHORTHAND_FALLBACK: Record<string, string> = {
+  backgroundColor: "background",
+  borderColor: "border",
+  outlineColor: "outline",
+};
+
+/** Colours these inherit from an ancestor when no rule targets the element. */
+const INHERITED_PROPERTIES = ["color"];
+
+/**
+ * Expanding a shorthand emits these for the longhands it resets, so treating
+ * them as authored would print "initial" in the fill row.
+ */
+const RESET_KEYWORDS = new Set([
+  "initial",
+  "inherit",
+  "unset",
+  "revert",
+  "revert-layer",
+]);
+
+function isAuthoredColor(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value !== "" &&
+    !RESET_KEYWORDS.has(value.trim().toLowerCase())
+  );
+}
+
+const LINE_STYLE_KEYWORDS = new Set([
+  "none",
+  "hidden",
+  "solid",
+  "dashed",
+  "dotted",
+  "double",
+  "groove",
+  "ridge",
+  "inset",
+  "outset",
+]);
+
+const LINE_WIDTH = /^(thin|medium|thick|-?\d*\.?\d+[a-z%]*)$/i;
+
+/** Split on spaces outside parentheses, so a `var()` fallback stays intact. */
+function splitTopLevel(value: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let current = "";
+  for (const char of value) {
+    if (char === "(") depth += 1;
+    else if (char === ")") depth -= 1;
+    if (depth === 0 && /\s/.test(char)) {
+      if (current) parts.push(current);
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  if (current) parts.push(current);
+  return parts;
+}
+
+/**
+ * The colour component of a `border`/`outline` shorthand. Width and style are
+ * a closed keyword set, so whatever single value is left over is the colour —
+ * without this, `border: 1px solid var(--x)` loses its token name.
+ */
+function lineShorthandColor(value: string): string | null {
+  const rest = splitTopLevel(value).filter((part) => {
+    const lower = part.toLowerCase();
+    return !LINE_STYLE_KEYWORDS.has(lower) && !LINE_WIDTH.test(part);
+  });
+  return rest.length === 1 ? rest[0] : null;
+}
+
+/**
+ * A shorthand only stands in for the colour when it isolates one. Exported for
+ * tests: a real engine leaves the longhand empty here, which happy-dom does not
+ * reproduce, so the wiring alone cannot exercise this.
+ */
+export function shorthandColorValue(
+  shorthand: string,
+  value: string,
+): string | null {
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  if (/url\(|gradient\(/i.test(trimmed)) return null;
+  // A single `var()` may contain spaces (its fallback); anything else with a
+  // space is a layered shorthand, not a colour.
+  if (/^var\(.*\)$/.test(trimmed)) return trimmed;
+  if (shorthand === "border" || shorthand === "outline") {
+    return lineShorthandColor(trimmed);
+  }
+  return /\s/.test(trimmed) ? null : trimmed;
+}
+
+type StyleRuleLike = {
+  selectorText?: string;
+  style?: Record<string, string> & {
+    getPropertyPriority?: (property: string) => string;
+  };
+  conditionText?: string;
+  cssRules?: ArrayLike<unknown>;
+};
+
+/**
+ * Approximate CSS specificity as one comparable number. Approximate is safe:
+ * it only orders selectors that already match, and `authoredMatchesPainted`
+ * still discards a winner that is not what paints. `:is()`/`:not()` inner
+ * specificity is not counted.
+ */
+function selectorSpecificity(selector: string): number {
+  const cleaned = selector
+    .replace(/\\./g, "")
+    .replace(/\[[^\]]*\]/g, " :attr ")
+    .replace(/\(([^()]*)\)/g, " ");
+  const count = (pattern: RegExp) => (cleaned.match(pattern) ?? []).length;
+  const ids = count(/#[\w-]+/g);
+  const classes = count(/\.[\w-]+/g) + count(/:(?!:)[\w-]+/g);
+  const types = count(/(?:^|[\s>+~])[a-zA-Z][\w-]*/g) + count(/::[\w-]+/g);
+  return ids * 10000 + classes * 100 + types;
+}
+
+/** Specificity of the selector in a comma list that actually matches. */
+function matchedSpecificity(element: Element, selectorText: string): number {
+  let best = -1;
+  for (const selector of selectorText.split(",")) {
+    const trimmed = selector.trim();
+    if (!trimmed) continue;
+    try {
+      if (!element.matches(trimmed)) continue;
+    } catch {
+      continue;
+    }
+    best = Math.max(best, selectorSpecificity(trimmed));
+  }
+  return best;
+}
+
+/** Above any selector: only importance can outrank an inline declaration. */
+const INLINE_SPECIFICITY = Number.MAX_SAFE_INTEGER;
+
+interface Candidate {
+  value: string;
+  important: boolean;
+  specificity: number;
+  order: number;
+}
+
+/** Cascade order for declarations that all match: important, then specificity. */
+function beats(next: Candidate, current: Candidate | undefined): boolean {
+  if (!current) return true;
+  if (next.important !== current.important) return next.important;
+  if (next.specificity !== current.specificity) {
+    return next.specificity > current.specificity;
+  }
+  return next.order >= current.order;
+}
+
+function readRules(
+  element: Element,
+  rules: ArrayLike<unknown> | undefined,
+  out: Record<string, Candidate>,
+  counter: { order: number },
+): void {
+  if (!rules) return;
+  for (let index = 0; index < rules.length; index += 1) {
+    const rule = rules[index] as StyleRuleLike | undefined;
+    if (!rule) continue;
+
+    // Tested before `cssRules`: a style rule carries one too (CSS nesting), so
+    // treating anything with `cssRules` as a group skips every declaration.
+    const declaresOwnStyles = Boolean(rule.selectorText && rule.style);
+
+    if (!declaresOwnStyles) {
+      if (!rule.cssRules) continue;
+      // Any grouping rule, not just conditional ones: an `@layer` block holds
+      // cssRules with no conditionText, and Tailwind puts its utilities there.
+      // Layer precedence is not modelled, only membership.
+      if (rule.conditionText === undefined) {
+        readRules(element, rule.cssRules, out, counter);
+        continue;
+      }
+      // A conditional group counts only while it applies, so the walk matches
+      // what the canvas paints.
+      let applies = false;
+      try {
+        applies =
+          typeof window !== "undefined" &&
+          typeof window.matchMedia === "function"
+            ? window.matchMedia(rule.conditionText).matches
+            : false;
+      } catch {
+        applies = false;
+      }
+      if (applies) readRules(element, rule.cssRules, out, counter);
+      continue;
+    }
+
+    if (rule.cssRules?.length) {
+      readRules(element, rule.cssRules, out, counter);
+    }
+
+    if (!rule.selectorText || !rule.style) continue;
+    const specificity = matchedSpecificity(element, rule.selectorText);
+    if (specificity < 0) continue;
+    const order = counter.order++;
+    const style = rule.style;
+    const priority = (name: string) =>
+      style.getPropertyPriority?.(name) === "important";
+
+    const offer = (property: string, value: string, cssName: string) => {
+      const candidate: Candidate = {
+        value,
+        important: priority(cssName),
+        specificity,
+        order,
+      };
+      if (beats(candidate, out[property])) out[property] = candidate;
+    };
+
+    for (const property of AUTHORED_COLOR_PROPERTIES) {
+      const declared = style[property];
+      if (isAuthoredColor(declared)) {
+        offer(property, declared, cssPropertyName(property));
+        continue;
+      }
+      const shorthand = SHORTHAND_FALLBACK[property];
+      if (!shorthand) continue;
+      const shorthandValue = style[shorthand];
+      if (typeof shorthandValue !== "string") continue;
+      const colorOnly = shorthandColorValue(shorthand, shorthandValue);
+      if (colorOnly) offer(property, colorOnly, shorthand);
+    }
+  }
+}
+
+function cssPropertyName(property: string): string {
+  return property.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+}
+
+/**
+ * Whether `authored` actually resolves to the colour the element paints.
+ *
+ * Without this an ancestor's `color: var(--color-text)` gets reported for a
+ * child painted green by its own utility class — a confidently wrong token name,
+ * which is worse than showing the hex. Resolved via a probe child so var()
+ * chains and shorthands are evaluated in the element's own scope.
+ */
+export function authoredMatchesPainted(
+  element: Element,
+  property: string,
+  authored: string,
+): boolean {
+  const view = element.ownerDocument?.defaultView;
+  if (!view || typeof view.getComputedStyle !== "function") return true;
+
+  let painted = "";
+  try {
+    painted =
+      (view.getComputedStyle(element) as unknown as Record<string, string>)[
+        property
+      ] ?? "";
+  } catch {
+    return true;
+  }
+  if (!painted) return true;
+
+  const probe = element.ownerDocument!.createElement("span");
+  const name = cssPropertyName(property);
+  probe.style.setProperty("display", "none");
+  probe.style.setProperty(name, authored);
+  // An unparseable value never lands, and the probe would then just inherit the
+  // element's own colour and compare equal.
+  if (!probe.style.getPropertyValue(name)) return false;
+
+  element.appendChild(probe);
+  let resolved = "";
+  try {
+    resolved =
+      (view.getComputedStyle(probe) as unknown as Record<string, string>)[
+        property
+      ] ?? "";
+  } catch {
+    resolved = "";
+  }
+  probe.remove();
+
+  return resolved === "" || resolved === painted;
+}
+
+function collectForElement(element: Element): Record<string, string> {
+  const ranked: Record<string, Candidate> = {};
+  const counter = { order: 0 };
+
+  try {
+    const doc = element.ownerDocument;
+    // Adopted sheets are not in `styleSheets`, and a runtime CSS injector (the
+    // Tailwind CDN) puts every utility rule there.
+    const sheets = [
+      ...Array.from(doc?.styleSheets ?? []),
+      ...Array.from(
+        (doc as unknown as { adoptedStyleSheets?: ArrayLike<CSSStyleSheet> })
+          ?.adoptedStyleSheets ?? [],
+      ),
+    ];
+    for (const sheet of sheets) {
+      let rules: ArrayLike<unknown> | undefined;
+      try {
+        rules = sheet.cssRules as unknown as ArrayLike<unknown>;
+      } catch {
+        // A cross-origin sheet cannot be read; skip it.
+        continue;
+      }
+      readRules(element, rules, ranked, counter);
+    }
+  } catch (error) {
+    // Silently losing the walk downgrades every token colour to a hex.
+    console.warn(
+      "[design] could not read stylesheets for authored colours; token names will fall back to resolved values",
+      error,
+    );
+  }
+
+  // Inline outranks any selector, but a normal inline declaration still loses
+  // to an `!important` stylesheet one — so it competes rather than overwrites.
+  const inline = (element as HTMLElement).style;
+  if (inline) {
+    const order = counter.order++;
+    for (const property of AUTHORED_COLOR_PROPERTIES) {
+      const value = inline[property as never] as unknown as string;
+      if (!isAuthoredColor(value)) continue;
+      const candidate: Candidate = {
+        value,
+        important:
+          inline.getPropertyPriority?.(cssPropertyName(property)) ===
+          "important",
+        specificity: INLINE_SPECIFICITY,
+        order,
+      };
+      if (beats(candidate, ranked[property])) ranked[property] = candidate;
+    }
+  }
+
+  const out: Record<string, string> = {};
+  for (const [property, candidate] of Object.entries(ranked)) {
+    out[property] = candidate.value;
+  }
+
+  return out;
+}
+
+export function collectAuthoredColorStyles(
+  element: Element,
+): Record<string, string> {
+  const out = collectForElement(element);
+  for (const property of Object.keys(out)) {
+    if (!authoredMatchesPainted(element, property, out[property])) {
+      delete out[property];
+    }
+  }
+
+  // `color` is inherited: a heading with no rule of its own still has a token.
+  for (const property of INHERITED_PROPERTIES) {
+    if (out[property]) continue;
+    let ancestor = element.parentElement;
+    while (ancestor) {
+      const inherited = collectForElement(ancestor)[property];
+      if (inherited) {
+        if (authoredMatchesPainted(element, property, inherited)) {
+          out[property] = inherited;
+        }
+        break;
+      }
+      ancestor = ancestor.parentElement;
+    }
+  }
+
+  return out;
+}

package/corpus/templates/design/shared/resolve-tweaks.ts

@@ -11,13 +11,21 @@
  *  - the snapshot / coding-handoff actions inject so an external agent
  *    continues from the *tuned* design, not the original generated tokens.
  *
- * Keep it pure and dependency-free so the UI and the server actions produce
- * byte-identical output.
+ * Keep it pure so the UI and the server actions produce byte-identical
+ * output. The CSS-safety predicates are re-exported from core so a Brand Kit
+ * token and a tweak value can never be validated by two drifting copies.
  */
 
+import {
+  isSafeCssTokenValue,
+  isSafeCssVarName,
+} from "@agent-native/core/brand-kit/tokens";
+
 import type { TweakDefinition } from "./api.js";
 import { sourceContentHash } from "./source-workspace.js";
 
+export { isSafeCssTokenValue, isSafeCssVarName };
+
 export type TweakSelections = Record<string, string | number | boolean>;
 
 /**
@@ -49,22 +57,6 @@ export function tweakSelectionsHash(
  * emitted directly, which lets token edits persist vars that were not part of
  * the generated tweak definition list.
  */
-const CSS_CUSTOM_PROPERTY_NAME = /^--[-_a-zA-Z0-9]+$/;
-
-export function isSafeCssVarName(value: string): boolean {
-  return CSS_CUSTOM_PROPERTY_NAME.test(value);
-}
-
-export function isSafeCssTokenValue(value: string): boolean {
-  return (
-    value.length > 0 &&
-    value.length <= 300 &&
-    !/[;{}<>]/.test(value) &&
-    !/\/\*/.test(value) &&
-    !/[\u0000-\u001f\u007f]/.test(value)
-  );
-}
-
 export function resolveTweaksToCssVars(
   tweaks: TweakDefinition[],
   selections: TweakSelections,

package/corpus/templates/dispatch/app/routes/transactional-email.$appId.$id.tsx

@@ -0,0 +1,4 @@
+export {
+  default,
+  meta,
+} from "@agent-native/dispatch/routes/pages/transactional-email.$appId.$id";

package/corpus/templates/dispatch/app/routes/transactional-email.tsx

@@ -0,0 +1,4 @@
+export {
+  default,
+  meta,
+} from "@agent-native/dispatch/routes/pages/transactional-email";

package/corpus/templates/forms/server/lib/emails.ts

@@ -0,0 +1,52 @@
+/**
+ * Catalog entries for the transactional emails Forms sends.
+ *
+ * Registered from `server/plugins/transactional-emails.ts` so Dispatch can list
+ * and preview them without the app having sent anything yet.
+ */
+
+import { defineTransactionalEmail } from "@agent-native/core/email-catalog";
+
+import { renderNewResponseEmail } from "./response-email.js";
+
+export const FORMS_NEW_RESPONSE_EMAIL_ID = "forms.new-response";
+
+let registered = false;
+
+export function registerFormsEmails(): void {
+  if (registered) return;
+  registered = true;
+
+  defineTransactionalEmail({
+    id: FORMS_NEW_RESPONSE_EMAIL_ID,
+    name: "New form response",
+    trigger:
+      "A response is submitted and persisted for a form whose settings have `emailOnNewResponses` enabled. Delivery is best-effort: a send failure never rejects the submission.",
+    recipientLabel: "Form owner",
+    recipient:
+      "The form's `ownerEmail`, and only that address — the respondent is never emailed. Skipped when the form has no owner address.",
+    senderLabel: "Default sender",
+    sender:
+      "The configured default sender. This call site sets no `from`, `fromName`, `replyTo`, or `appSender`, so a reply goes to the sending mailbox rather than to the respondent.",
+    preview: () =>
+      renderNewResponseEmail({
+        formTitle: "Beta feedback",
+        fields: [
+          { id: "name", type: "text", label: "Name", required: true },
+          { id: "email", type: "email", label: "Email", required: true },
+          {
+            id: "notes",
+            type: "textarea",
+            label: "What should we fix first?",
+            required: false,
+          },
+        ],
+        data: {
+          name: "Sam Rivera",
+          email: "sam.rivera@example.com",
+          notes: "The export button is hard to find on mobile.",
+        },
+        submittedAt: "2025-03-04T17:20:00.000Z",
+      }),
+  });
+}

package/corpus/templates/forms/server/lib/response-email.ts

@@ -1,6 +1,7 @@
 import { emailStrong, renderEmail, sendEmail } from "@agent-native/core/server";
 
 import type { FormField } from "../../shared/types.js";
+import { FORMS_NEW_RESPONSE_EMAIL_ID } from "./emails.js";
 
 export interface NewResponseEmailArgs {
   to: string;
@@ -61,5 +62,6 @@ export async function sendNewResponseEmail(
   await sendEmail({
     to: args.to,
     ...renderNewResponseEmail(args),
+    templateId: FORMS_NEW_RESPONSE_EMAIL_ID,
   });
 }

package/corpus/templates/forms/server/plugins/transactional-emails.ts

@@ -0,0 +1,5 @@
+import { registerFormsEmails } from "../lib/emails.js";
+
+export default function registerTransactionalEmails(): void {
+  registerFormsEmails();
+}

package/corpus/templates/plan/actions/request-plan-access.ts

@@ -22,6 +22,8 @@ import {
 } from "../server/lib/local-identity.js";
 import { newId, nowIso, planPath, writeEvent } from "../server/plans.js";
 
+export const PLAN_ACCESS_REQUEST_EMAIL_ID = "plan.access-request";
+
 function httpError(message: string, statusCode: number): Error {
   return Object.assign(new Error(message), { statusCode });
 }
@@ -49,6 +51,28 @@ function absolutePlanUrl(planId: string, kind: "plan" | "recap"): string {
   }
 }
 
+export function renderPlanAccessRequestEmail(input: {
+  requesterName: string;
+  requesterEmail: string;
+  planTitle: string;
+  url: string;
+}) {
+  const subject = `${input.requesterName} requested access to "${input.planTitle}"`;
+  return {
+    subject,
+    ...renderEmail({
+      preheader: subject,
+      heading: "Access request",
+      paragraphs: [
+        `${emailStrong(input.requesterName)} (${emailStrong(input.requesterEmail)}) requested access to ${emailStrong(input.planTitle)}.`,
+        "Open the plan and use Share to grant access if this request should be approved.",
+      ],
+      cta: { label: "Open plan", url: input.url },
+      footer: "You received this because you own this Agent-Native Plan.",
+    }),
+  };
+}
+
 async function notifyOwner(input: {
   planId: string;
   planKind: "plan" | "recap";
@@ -62,19 +86,16 @@ async function notifyOwner(input: {
     return false;
   }
 
-  const url = absolutePlanUrl(input.planId, input.planKind);
-  const subject = `${input.requesterName} requested access to "${input.planTitle}"`;
-  const { html, text } = renderEmail({
-    preheader: subject,
-    heading: "Access request",
-    paragraphs: [
-      `${emailStrong(input.requesterName)} (${emailStrong(input.requesterEmail)}) requested access to ${emailStrong(input.planTitle)}.`,
-      "Open the plan and use Share to grant access if this request should be approved.",
-    ],
-    cta: { label: "Open plan", url },
-    footer: "You received this because you own this Agent-Native Plan.",
+  await sendEmail({
+    ...renderPlanAccessRequestEmail({
+      requesterName: input.requesterName,
+      requesterEmail: input.requesterEmail,
+      planTitle: input.planTitle,
+      url: absolutePlanUrl(input.planId, input.planKind),
+    }),
+    to: input.ownerEmail,
+    templateId: PLAN_ACCESS_REQUEST_EMAIL_ID,
   });
-  await sendEmail({ to: input.ownerEmail, subject, html, text });
   return true;
 }