@xfxstudio/claworld 0.2.10-beta.3 → 0.2.12

package/src/product-shell/agent-cards/storage/image-host-storage.js

@@ -0,0 +1,192 @@
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function normalizePositiveInteger(value, fallback = null) {
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized) || normalized <= 0) return fallback;
+  return Math.floor(normalized);
+}
+
+function toIsoFromEpochSeconds(value, fallback = null) {
+  const normalized = normalizePositiveInteger(value, null);
+  return normalized ? new Date(normalized * 1000).toISOString() : fallback;
+}
+
+function createImageHostStorageError({
+  code,
+  message,
+  status = 502,
+  url = null,
+  responseStatus = null,
+  responseBody = null,
+} = {}) {
+  const error = new Error(message || code || 'agent_card_image_host_failed');
+  error.code = code || 'agent_card_image_host_failed';
+  error.status = status;
+  error.responseBody = {
+    error: error.code,
+    message: error.message,
+    ...(url ? { url } : {}),
+    ...(Number.isInteger(responseStatus) ? { responseStatus } : {}),
+    ...(responseBody != null ? { responseBody } : {}),
+  };
+  return error;
+}
+
+async function parseJsonResponse(response) {
+  const text = await response.text();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+async function postJson(url, { bearerToken, body }) {
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      authorization: `Bearer ${bearerToken}`,
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify(body || {}),
+    signal: AbortSignal.timeout(10_000),
+  });
+  const payload = await parseJsonResponse(response);
+  if (!response.ok) {
+    throw createImageHostStorageError({
+      code: 'agent_card_image_host_sign_failed',
+      message: 'agent card signing request failed',
+      url,
+      responseStatus: response.status,
+      responseBody: payload,
+    });
+  }
+  return payload;
+}
+
+async function uploadPng(url, { bearerToken, pngBuffer, filename }) {
+  const form = new FormData();
+  form.append('file', new Blob([pngBuffer], { type: 'image/png' }), filename);
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      authorization: `Bearer ${bearerToken}`,
+    },
+    body: form,
+    signal: AbortSignal.timeout(10_000),
+  });
+  const payload = await parseJsonResponse(response);
+  if (!response.ok) {
+    throw createImageHostStorageError({
+      code: 'agent_card_image_host_upload_failed',
+      message: 'agent card upload request failed',
+      url,
+      responseStatus: response.status,
+      responseBody: payload,
+    });
+  }
+  return payload;
+}
+
+export function createImageHostAgentCardStorage({
+  baseUrl = null,
+  uploadUrl = null,
+  signUrl = null,
+  bearerToken = null,
+} = {}) {
+  const normalizedBaseUrl = normalizeText(baseUrl, null);
+  const normalizedUploadUrl = normalizeText(
+    uploadUrl,
+    normalizedBaseUrl ? `${normalizedBaseUrl.replace(/\/+$/, '')}/api/upload` : null,
+  );
+  const normalizedSignUrl = normalizeText(
+    signUrl,
+    normalizedBaseUrl ? `${normalizedBaseUrl.replace(/\/+$/, '')}/api/sign` : null,
+  );
+  const normalizedBearerToken = normalizeText(bearerToken, null);
+
+  if (!normalizedUploadUrl) {
+    throw new Error('agent_card_image_host_upload_url_required');
+  }
+  if (!normalizedSignUrl) {
+    throw new Error('agent_card_image_host_sign_url_required');
+  }
+  if (!normalizedBearerToken) {
+    throw new Error('agent_card_image_host_bearer_token_required');
+  }
+
+  return {
+    storageType: 'image_host',
+    describeTarget({ contentHash, templateVersion = 'v1', expiresAt = null, expiresInSeconds = null } = {}) {
+      const normalizedHash = normalizeText(contentHash, null);
+      if (!normalizedHash) throw new Error('agent_card_content_hash_required');
+      return {
+        contentHash: normalizedHash,
+        templateVersion: normalizeText(templateVersion, 'v1'),
+        expiresAt: normalizeText(expiresAt, null),
+        expiresInSeconds: normalizePositiveInteger(expiresInSeconds, null),
+        sourceFilename: `${normalizedHash}.png`,
+      };
+    },
+    async exists() {
+      return false;
+    },
+    async writePng(target, pngBuffer, { expiresInSeconds = null } = {}) {
+      const uploadPayload = await uploadPng(normalizedUploadUrl, {
+        bearerToken: normalizedBearerToken,
+        pngBuffer,
+        filename: target.sourceFilename,
+      });
+      const uploadedFilename = normalizeText(uploadPayload?.filename, null);
+      if (!uploadedFilename) {
+        throw createImageHostStorageError({
+          code: 'agent_card_image_host_invalid_upload_response',
+          message: 'agent card upload response did not include a filename',
+          url: normalizedUploadUrl,
+          responseBody: uploadPayload,
+        });
+      }
+      const ttlSeconds = normalizePositiveInteger(
+        expiresInSeconds,
+        normalizePositiveInteger(target.expiresInSeconds, null),
+      );
+      const signPayload = await postJson(normalizedSignUrl, {
+        bearerToken: normalizedBearerToken,
+        body: {
+          filename: uploadedFilename,
+          ttlSeconds,
+        },
+      });
+      const signedUrl = normalizeText(signPayload?.signedUrl, normalizeText(uploadPayload?.signedUrl, null));
+      if (!signedUrl) {
+        throw createImageHostStorageError({
+          code: 'agent_card_image_host_invalid_sign_response',
+          message: 'agent card sign response did not include a signedUrl',
+          url: normalizedSignUrl,
+          responseBody: signPayload,
+        });
+      }
+      const publicUrl = normalizeText(
+        uploadPayload?.publicUrl,
+        normalizedBaseUrl ? `${normalizedBaseUrl.replace(/\/+$/, '')}/i/${uploadedFilename}` : null,
+      );
+      return {
+        ...target,
+        filename: uploadedFilename,
+        publicUrl,
+        signedUrl,
+        imageUrl: signedUrl,
+        downloadUrl: signedUrl,
+        expiresAt: toIsoFromEpochSeconds(signPayload?.expiresAt, target.expiresAt),
+        expiresInSeconds: normalizePositiveInteger(signPayload?.ttlSeconds, ttlSeconds),
+        contentType: normalizeText(uploadPayload?.contentType, 'image/png'),
+        size: normalizePositiveInteger(uploadPayload?.size, pngBuffer.length),
+      };
+    },
+  };
+}

package/src/product-shell/agent-cards/storage/local-public-storage.js

@@ -0,0 +1,74 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function normalizePublicPath(filePath = '') {
+  return String(filePath).split(path.sep).join('/');
+}
+
+function parseExpiryEpochSeconds(value) {
+  const parsed = Number.parseInt(String(value || '').trim(), 10);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+}
+
+export function extractAgentCardExpiryEpochSeconds(relativeOrPublicPath = '') {
+  const normalizedPath = normalizePublicPath(String(relativeOrPublicPath || '')).replace(/^\/+/, '');
+  const parts = normalizedPath.split('/').filter(Boolean);
+  if (parts[0] !== 'ephemeral') return null;
+  return parseExpiryEpochSeconds(parts[1]);
+}
+
+export function createLocalPublicAgentCardStorage({
+  publicDir,
+  publicBasePath = '/public/agent-cards',
+} = {}) {
+  const normalizedPublicDir = normalizeText(publicDir, null);
+  if (!normalizedPublicDir) {
+    throw new Error('agent_card_public_dir_required');
+  }
+
+  return {
+    describeTarget({ contentHash, templateVersion = 'v1', expiresAt = null } = {}) {
+      const normalizedHash = normalizeText(contentHash, null);
+      if (!normalizedHash) throw new Error('agent_card_content_hash_required');
+      const expiresAtEpochSeconds = expiresAt ? parseExpiryEpochSeconds(Math.floor(Date.parse(expiresAt) / 1000)) : null;
+      const relativePath = expiresAtEpochSeconds
+        ? path.join(
+            'ephemeral',
+            String(expiresAtEpochSeconds),
+            normalizeText(templateVersion, 'v1'),
+            normalizedHash.slice(0, 2),
+            normalizedHash.slice(2, 4),
+            `${normalizedHash}.png`,
+          )
+        : path.join(
+            normalizeText(templateVersion, 'v1'),
+            normalizedHash.slice(0, 2),
+            normalizedHash.slice(2, 4),
+            `${normalizedHash}.png`,
+          );
+      return {
+        contentHash: normalizedHash,
+        expiresAt: expiresAtEpochSeconds ? new Date(expiresAtEpochSeconds * 1000).toISOString() : null,
+        expiresAtEpochSeconds,
+        isEphemeral: Boolean(expiresAtEpochSeconds),
+        relativePath,
+        absolutePath: path.join(normalizedPublicDir, relativePath),
+        publicPath: `${normalizeText(publicBasePath, '/public/agent-cards')}/${normalizePublicPath(relativePath)}`,
+      };
+    },
+    async exists(target) {
+      return await fs.pathExists(target.absolutePath);
+    },
+    async writePng(target, pngBuffer) {
+      await fs.ensureDir(path.dirname(target.absolutePath));
+      await fs.writeFile(target.absolutePath, pngBuffer);
+      return target;
+    },
+  };
+}

package/src/product-shell/agent-cards/svg-renderer.js

@@ -0,0 +1,325 @@
+import { Resvg } from '@resvg/resvg-js';
+import QRCode from 'qrcode';
+
+function normalizeText(value, fallback = null) {
+  if (value == null) return fallback;
+  const normalized = String(value).trim();
+  return normalized || fallback;
+}
+
+function escapeXml(value) {
+  return String(value || '')
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;');
+}
+
+function truncateText(value, maxLength, fallback = '') {
+  const normalized = normalizeText(value, fallback) || fallback;
+  if (normalized.length <= maxLength) return normalized;
+  return `${normalized.slice(0, Math.max(1, maxLength - 1)).trimEnd()}…`;
+}
+
+function buildCtaMarkup(lines = []) {
+  return lines
+    .map((line, index) => {
+      const dy = index === 0 ? '0' : '48';
+      return `<tspan x="96" dy="${dy}">${escapeXml(truncateText(line, 84, ''))}</tspan>`;
+    })
+    .join('');
+}
+
+function buildSubtitleMarkup(text) {
+  const normalized = truncateText(text, 180, 'Agent-to-agent worlds on OpenClaw.');
+  const words = normalized.split(/\s+/g).filter(Boolean);
+  const lines = [];
+  let currentLine = '';
+
+  for (const word of words) {
+    const nextLine = currentLine ? `${currentLine} ${word}` : word;
+    if (nextLine.length > 42 && currentLine) {
+      lines.push(currentLine);
+      currentLine = word;
+      continue;
+    }
+    currentLine = nextLine;
+  }
+
+  if (currentLine) lines.push(currentLine);
+
+  return lines.slice(0, 3).map((line, index) => {
+    const dy = index === 0 ? '0' : '46';
+    return `<tspan x="96" dy="${dy}">${escapeXml(line)}</tspan>`;
+  }).join('');
+}
+
+async function buildQrDataUrl(targetUrl) {
+  return await QRCode.toDataURL(targetUrl, {
+    errorCorrectionLevel: 'M',
+    margin: 1,
+    width: 220,
+    color: {
+      dark: '#10203a',
+      light: '#0000',
+    },
+  });
+}
+
+function applyTemplate(source, replacements) {
+  return Object.entries(replacements).reduce(
+    (result, [token, value]) => result.replaceAll(`{{${token}}}`, value),
+    source,
+  );
+}
+
+function splitGraphemes(value) {
+  const normalized = String(value || '');
+  if (!normalized) return [];
+  if (typeof Intl?.Segmenter === 'function') {
+    const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' });
+    return Array.from(segmenter.segment(normalized), ({ segment }) => segment);
+  }
+  return Array.from(normalized);
+}
+
+function isFullWidthCodePoint(codePoint) {
+  return (
+    (codePoint >= 0x1100 && codePoint <= 0x115f) ||
+    (codePoint >= 0x2329 && codePoint <= 0x232a) ||
+    (codePoint >= 0x2e80 && codePoint <= 0xa4cf) ||
+    (codePoint >= 0xac00 && codePoint <= 0xd7a3) ||
+    (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+    (codePoint >= 0xfe10 && codePoint <= 0xfe19) ||
+    (codePoint >= 0xfe30 && codePoint <= 0xfe6f) ||
+    (codePoint >= 0xff01 && codePoint <= 0xff60) ||
+    (codePoint >= 0xffe0 && codePoint <= 0xffe6) ||
+    (codePoint >= 0x1f300 && codePoint <= 0x1fbff)
+  );
+}
+
+function estimateGlyphWidthUnits(grapheme) {
+  if (!grapheme) return 0;
+  if (/^\s$/u.test(grapheme)) return 0.32;
+  if (/^[.,:;!|`'"’“”‘]$/u.test(grapheme)) return 0.28;
+  if (/^[()\[\]{}]$/u.test(grapheme)) return 0.36;
+  if (/^[-_=+\\/<>]$/u.test(grapheme)) return 0.48;
+  if (/^[#@%&*]$/u.test(grapheme)) return 0.72;
+  if (/^[0-9]$/u.test(grapheme)) return 0.56;
+  if (/^[A-Z]$/u.test(grapheme)) return /[MW]/u.test(grapheme) ? 0.9 : 0.68;
+  if (/^[a-z]$/u.test(grapheme)) return /[mw]/u.test(grapheme) ? 0.78 : 0.56;
+
+  const codePoint = grapheme.codePointAt(0);
+  if (codePoint == null) return 0.6;
+  if (isFullWidthCodePoint(codePoint)) return 1;
+  return 0.62;
+}
+
+export function estimateTextWidth(text, fontSize, { letterSpacing = 0 } = {}) {
+  if (!text || !fontSize) return 0;
+  const graphemes = splitGraphemes(text);
+  const glyphUnits = graphemes.reduce((total, grapheme) => total + estimateGlyphWidthUnits(grapheme), 0);
+  const spacingWidth = Math.max(0, graphemes.length - 1) * letterSpacing;
+  return (glyphUnits * fontSize) + spacingWidth;
+}
+
+function parseNumericAttribute(value, fallback = null) {
+  if (value == null) return fallback;
+  const parsed = Number.parseFloat(String(value));
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+function parseLetterSpacing(value, fontSize) {
+  if (!value) return 0;
+  const normalized = String(value).trim();
+  if (!normalized || normalized === 'normal') return 0;
+  if (normalized.endsWith('em')) return parseNumericAttribute(normalized.slice(0, -2), 0) * fontSize;
+  if (normalized.endsWith('px')) return parseNumericAttribute(normalized.slice(0, -2), 0);
+  return parseNumericAttribute(normalized, 0);
+}
+
+function formatFontSize(value) {
+  const rounded = Math.round(value * 10) / 10;
+  return Number.isInteger(rounded) ? String(rounded) : String(rounded);
+}
+
+function shrinkTextToFitSingleLine(value, {
+  maxWidth,
+  maxFontSize,
+  minFontSize,
+  letterSpacing = 0,
+} = {}) {
+  const text = String(value || '');
+  if (!text) {
+    return {
+      text,
+      fontSize: formatFontSize(maxFontSize || minFontSize || 16),
+    };
+  }
+
+  const widthAtMax = estimateTextWidth(text, maxFontSize, { letterSpacing });
+  if (!maxWidth || !maxFontSize || widthAtMax <= maxWidth) {
+    return {
+      text,
+      fontSize: formatFontSize(maxFontSize || minFontSize || 16),
+    };
+  }
+
+  const scaledFontSize = Math.max(
+    minFontSize || maxFontSize,
+    Math.min(maxFontSize, (maxFontSize * maxWidth) / Math.max(widthAtMax, 1)),
+  );
+
+  if (scaledFontSize > (minFontSize || maxFontSize)) {
+    return {
+      text,
+      fontSize: formatFontSize(scaledFontSize),
+    };
+  }
+
+  if (estimateTextWidth(text, minFontSize, { letterSpacing }) <= maxWidth) {
+    return {
+      text,
+      fontSize: formatFontSize(minFontSize),
+    };
+  }
+
+  const graphemes = splitGraphemes(text);
+  let keptLength = graphemes.length;
+  while (keptLength > 1) {
+    const candidate = `${graphemes.slice(0, keptLength).join('').trimEnd()}…`;
+    if (estimateTextWidth(candidate, minFontSize, { letterSpacing }) <= maxWidth) {
+      return {
+        text: candidate,
+        fontSize: formatFontSize(minFontSize),
+      };
+    }
+    keptLength -= 1;
+  }
+
+  return {
+    text: '…',
+    fontSize: formatFontSize(minFontSize || maxFontSize || 16),
+  };
+}
+
+function parseTextTagAttributes(attributeSource) {
+  const attributes = {};
+  const pattern = /([:@\w.-]+)\s*=\s*(['"])(.*?)\2/gs;
+  for (const match of attributeSource.matchAll(pattern)) {
+    attributes[match[1]] = match[3];
+  }
+  return attributes;
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function setSvgAttribute(attributeSource, name, value) {
+  const replacement = `${name}="${value}"`;
+  const escapedName = escapeRegExp(name);
+  const pattern = new RegExp(`(^|\\s)(${escapedName}\\s*=\\s*)(['"]).*?\\3`, 's');
+  if (pattern.test(attributeSource)) {
+    return attributeSource.replace(pattern, (match, prefix) => `${prefix}${replacement}`);
+  }
+  return `${attributeSource} ${replacement}`;
+}
+
+function resolveSlotTextValue({ field, token, spec }) {
+  const fieldValue = field ? spec?.[field] : undefined;
+  if (fieldValue != null && fieldValue !== '') return String(fieldValue);
+
+  switch (token) {
+    case 'DISPLAY_NAME':
+      return spec?.displayName ?? 'Claworld Agent';
+    case 'PUBLIC_HANDLE':
+      return spec?.publicHandle ?? 'agent#0000';
+    case 'TITLE':
+      return spec?.title ?? 'Claworld Agent Card';
+    case 'BADGE_TEXT':
+      return spec?.badgeText ?? 'Preview';
+    case 'FOOTER_LABEL':
+      return spec?.footerLabel ?? 'claworld.love';
+    case 'AVATAR_INITIALS':
+      return spec?.avatarInitials ?? 'C';
+    default:
+      return null;
+  }
+}
+
+export function applyAdaptiveTextSlots(source, { spec } = {}) {
+  if (!source || !spec) return source;
+
+  return source.replace(/<text\b(?<attributes>[^>]*)>(?<content>[\s\S]*?)<\/text>/g, (fullMatch, rawAttributes, rawContent) => {
+    const attributes = parseTextTagAttributes(rawAttributes);
+    const token = attributes['data-token'];
+    const field = attributes['data-field'];
+    if (!token && !field) return fullMatch;
+
+    const resolvedValue = resolveSlotTextValue({ field, token, spec });
+    if (resolvedValue == null) return fullMatch;
+
+    const trimWhitespace = attributes['data-trim-whitespace'] === 'true';
+    const normalizedValue = trimWhitespace ? normalizeText(resolvedValue, '') || '' : String(resolvedValue);
+    const layout = attributes['data-layout'];
+    const overflow = attributes['data-overflow'];
+
+    let nextText = normalizedValue;
+    let nextAttributes = rawAttributes;
+
+    if (layout === 'single-line' && overflow === 'shrink-font-only') {
+      const maxWidth = parseNumericAttribute(attributes['data-max-width']);
+      const maxFontSize = parseNumericAttribute(attributes['data-max-font-size'], parseNumericAttribute(attributes['font-size'], 16));
+      const minFontSize = parseNumericAttribute(attributes['data-min-font-size'], maxFontSize);
+      const letterSpacing = parseLetterSpacing(attributes['letter-spacing'], maxFontSize);
+      const fitted = shrinkTextToFitSingleLine(normalizedValue, {
+        maxWidth,
+        maxFontSize,
+        minFontSize,
+        letterSpacing,
+      });
+      nextText = fitted.text;
+      nextAttributes = setSvgAttribute(nextAttributes, 'font-size', fitted.fontSize);
+    }
+
+    return `<text${nextAttributes}>${escapeXml(nextText)}</text>`;
+  });
+}
+
+export function createAgentCardSvgRenderer() {
+  return {
+    async renderCard({ template, spec } = {}) {
+      if (!template?.source) throw new Error('agent_card_template_source_missing');
+      if (!spec || typeof spec !== 'object') throw new Error('agent_card_spec_missing');
+
+      const qrDataUrl = await buildQrDataUrl(spec.qrTargetUrl);
+      const svg = applyTemplate(applyAdaptiveTextSlots(template.source, { spec }), {
+        DISPLAY_NAME: escapeXml(truncateText(spec.displayName, 40, 'Claworld Agent')),
+        PUBLIC_HANDLE: escapeXml(truncateText(spec.publicHandle, 48, 'agent#0000')),
+        TITLE: escapeXml(truncateText(spec.title, 56, 'Claworld Agent Card')),
+        SUBTITLE_LINES: buildSubtitleMarkup(spec.subtitle),
+        CTA_LINES: buildCtaMarkup(spec.ctaLines),
+        FOOTER_LABEL: escapeXml(truncateText(spec.footerLabel, 80, 'claworld.love')),
+        BADGE_TEXT: escapeXml(truncateText(spec.badgeText, 24, 'Preview')),
+        AVATAR_INITIALS: escapeXml(truncateText(spec.avatarInitials, 2, 'C')),
+        QR_DATA_URL: escapeXml(qrDataUrl),
+      });
+
+      const resvg = new Resvg(svg, {
+        fitTo: {
+          mode: 'width',
+          value: template.width || 1200,
+        },
+        font: {
+          loadSystemFonts: true,
+          defaultFontFamily: 'Arial',
+        },
+      });
+
+      const image = resvg.render();
+      return image.asPng();
+    },
+  };
+}