@agent-native/core 0.103.0 → 0.104.0

package/dist/ingestion/docx.js

@@ -0,0 +1,129 @@
+export async function parseDocxDocument(data) {
+    const mammoth = await loadMammoth();
+    const buffer = Buffer.from(data);
+    const [htmlResult, textResult] = await Promise.all([
+        mammoth.convertToHtml({ buffer }),
+        mammoth.extractRawText({ buffer }),
+    ]);
+    const html = sanitizeInertDocumentHtml(htmlResult.value);
+    const text = textResult.value;
+    const sections = extractDocxSections(html);
+    const firstLine = text.split("\n").find((line) => line.trim());
+    return {
+        title: sections.find((section) => section.heading)?.heading ??
+            (firstLine && firstLine.length < 200
+                ? firstLine.trim()
+                : "Imported Document"),
+        html,
+        text,
+        sections,
+    };
+}
+export function extractDocxSections(html) {
+    html = sanitizeInertDocumentHtml(html);
+    const sections = [];
+    for (const part of html.split(/(?=<h[1-3][^>]*>)/i)) {
+        const trimmed = part.trim();
+        if (!trimmed)
+            continue;
+        const heading = trimmed.match(/^<h[1-3][^>]*>(.*?)<\/h[1-3]>/is);
+        if (heading) {
+            const sectionHtml = trimmed.slice(heading[0].length).trim();
+            sections.push({
+                heading: stripHtml(heading[1]).trim(),
+                content: sectionHtml,
+                html: sectionHtml,
+                text: stripHtml(sectionHtml),
+            });
+        }
+        else if (sections.length === 0) {
+            sections.push({
+                heading: "",
+                content: trimmed,
+                html: trimmed,
+                text: stripHtml(trimmed),
+            });
+        }
+        else {
+            const previous = sections.at(-1);
+            previous.html += `\n${trimmed}`;
+            previous.content = previous.html;
+            previous.text = stripHtml(previous.html);
+        }
+    }
+    return sections.length > 0
+        ? sections
+        : html.trim()
+            ? [{ heading: "", content: html, html, text: stripHtml(html) }]
+            : [];
+}
+const SAFE_DOCUMENT_TAGS = new Set([
+    "p",
+    "br",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "ul",
+    "ol",
+    "li",
+    "strong",
+    "b",
+    "em",
+    "i",
+    "u",
+    "s",
+    "blockquote",
+    "pre",
+    "code",
+    "table",
+    "thead",
+    "tbody",
+    "tfoot",
+    "tr",
+    "th",
+    "td",
+    "hr",
+    "sup",
+    "sub",
+]);
+export function sanitizeInertDocumentHtml(value) {
+    return value
+        .replace(/<!--[^]*?-->/g, "")
+        .replace(/<!\s*(?:doctype|entity)[^>]*>/gi, "")
+        .replace(/<\?[^>]*>/g, "")
+        .replace(/<\s*(script|style|iframe|object|embed|svg|math|template|noscript|form)\b[^>]*>[^]*?<\s*\/\s*\1\s*>/gi, "")
+        .replace(/<\s*\/?\s*([a-z][a-z0-9:-]*)\b[^>]*>/gi, (tag, rawName) => {
+        const name = rawName.toLowerCase();
+        if (!SAFE_DOCUMENT_TAGS.has(name))
+            return "";
+        const closing = /^<\s*\//.test(tag);
+        if (closing && (name === "br" || name === "hr"))
+            return "";
+        return closing ? `</${name}>` : `<${name}>`;
+    })
+        .trim();
+}
+function stripHtml(value) {
+    return value
+        .replace(/<br\s*\/?\s*>/gi, "\n")
+        .replace(/<\/p>/gi, "\n")
+        .replace(/<[^>]+>/g, "")
+        .replace(/&nbsp;/gi, " ")
+        .replace(/&amp;/gi, "&")
+        .replace(/&lt;/gi, "<")
+        .replace(/&gt;/gi, ">")
+        .trim();
+}
+async function loadMammoth() {
+    const moduleName = "mammoth";
+    try {
+        return (await import(moduleName));
+    }
+    catch {
+        throw new Error("Structured DOCX parsing requires the optional mammoth dependency.");
+    }
+}
+//# sourceMappingURL=docx.js.map

package/dist/ingestion/docx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docx.js","sourceRoot":"","sources":["../../src/ingestion/docx.ts"],"names":[],"mappings":"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","sourcesContent":["export interface ParsedDocxSection {\n  heading: string;\n  content: string;\n  html: string;\n  text: string;\n}\n\nexport interface ParsedDocxDocument {\n  title: string;\n  html: string;\n  text: string;\n  sections: ParsedDocxSection[];\n}\n\nexport async function parseDocxDocument(\n  data: Uint8Array,\n): Promise<ParsedDocxDocument> {\n  const mammoth = await loadMammoth();\n  const buffer = Buffer.from(data);\n  const [htmlResult, textResult] = await Promise.all([\n    mammoth.convertToHtml({ buffer }),\n    mammoth.extractRawText({ buffer }),\n  ]);\n  const html = sanitizeInertDocumentHtml(htmlResult.value);\n  const text = textResult.value;\n  const sections = extractDocxSections(html);\n  const firstLine = text.split(\"\\n\").find((line) => line.trim());\n  return {\n    title:\n      sections.find((section) => section.heading)?.heading ??\n      (firstLine && firstLine.length < 200\n        ? firstLine.trim()\n        : \"Imported Document\"),\n    html,\n    text,\n    sections,\n  };\n}\n\nexport function extractDocxSections(html: string): ParsedDocxSection[] {\n  html = sanitizeInertDocumentHtml(html);\n  const sections: ParsedDocxSection[] = [];\n  for (const part of html.split(/(?=<h[1-3][^>]*>)/i)) {\n    const trimmed = part.trim();\n    if (!trimmed) continue;\n    const heading = trimmed.match(/^<h[1-3][^>]*>(.*?)<\\/h[1-3]>/is);\n    if (heading) {\n      const sectionHtml = trimmed.slice(heading[0].length).trim();\n      sections.push({\n        heading: stripHtml(heading[1]).trim(),\n        content: sectionHtml,\n        html: sectionHtml,\n        text: stripHtml(sectionHtml),\n      });\n    } else if (sections.length === 0) {\n      sections.push({\n        heading: \"\",\n        content: trimmed,\n        html: trimmed,\n        text: stripHtml(trimmed),\n      });\n    } else {\n      const previous = sections.at(-1)!;\n      previous.html += `\\n${trimmed}`;\n      previous.content = previous.html;\n      previous.text = stripHtml(previous.html);\n    }\n  }\n  return sections.length > 0\n    ? sections\n    : html.trim()\n      ? [{ heading: \"\", content: html, html, text: stripHtml(html) }]\n      : [];\n}\n\nconst SAFE_DOCUMENT_TAGS = new Set([\n  \"p\",\n  \"br\",\n  \"h1\",\n  \"h2\",\n  \"h3\",\n  \"h4\",\n  \"h5\",\n  \"h6\",\n  \"ul\",\n  \"ol\",\n  \"li\",\n  \"strong\",\n  \"b\",\n  \"em\",\n  \"i\",\n  \"u\",\n  \"s\",\n  \"blockquote\",\n  \"pre\",\n  \"code\",\n  \"table\",\n  \"thead\",\n  \"tbody\",\n  \"tfoot\",\n  \"tr\",\n  \"th\",\n  \"td\",\n  \"hr\",\n  \"sup\",\n  \"sub\",\n]);\n\nexport function sanitizeInertDocumentHtml(value: string): string {\n  return value\n    .replace(/<!--[^]*?-->/g, \"\")\n    .replace(/<!\\s*(?:doctype|entity)[^>]*>/gi, \"\")\n    .replace(/<\\?[^>]*>/g, \"\")\n    .replace(\n      /<\\s*(script|style|iframe|object|embed|svg|math|template|noscript|form)\\b[^>]*>[^]*?<\\s*\\/\\s*\\1\\s*>/gi,\n      \"\",\n    )\n    .replace(\n      /<\\s*\\/?\\s*([a-z][a-z0-9:-]*)\\b[^>]*>/gi,\n      (tag, rawName: string) => {\n        const name = rawName.toLowerCase();\n        if (!SAFE_DOCUMENT_TAGS.has(name)) return \"\";\n        const closing = /^<\\s*\\//.test(tag);\n        if (closing && (name === \"br\" || name === \"hr\")) return \"\";\n        return closing ? `</${name}>` : `<${name}>`;\n      },\n    )\n    .trim();\n}\n\nfunction stripHtml(value: string): string {\n  return value\n    .replace(/<br\\s*\\/?\\s*>/gi, \"\\n\")\n    .replace(/<\\/p>/gi, \"\\n\")\n    .replace(/<[^>]+>/g, \"\")\n    .replace(/&nbsp;/gi, \" \")\n    .replace(/&amp;/gi, \"&\")\n    .replace(/&lt;/gi, \"<\")\n    .replace(/&gt;/gi, \">\")\n    .trim();\n}\n\nasync function loadMammoth(): Promise<{\n  convertToHtml(input: { buffer: Buffer }): Promise<{ value: string }>;\n  extractRawText(input: { buffer: Buffer }): Promise<{ value: string }>;\n}> {\n  const moduleName = \"mammoth\";\n  try {\n    return (await import(moduleName)) as {\n      convertToHtml(input: { buffer: Buffer }): Promise<{ value: string }>;\n      extractRawText(input: { buffer: Buffer }): Promise<{ value: string }>;\n    };\n  } catch {\n    throw new Error(\n      \"Structured DOCX parsing requires the optional mammoth dependency.\",\n    );\n  }\n}\n"]}

package/dist/ingestion/figma-node-to-html.d.ts

@@ -0,0 +1,304 @@
+/**
+ * Figma node JSON -> HTML mapper.
+ *
+ * Input is the `document` subtree returned by
+ * `GET /v1/files/:fileKey/nodes?ids=...&geometry=paths` (or the file's root
+ * `document` node). Output is a self-contained HTML fragment using absolute
+ * positioning + inline styles, matching Figma's own canvas model 1:1 rather
+ * than reconstructing a semantic/Tailwind layout — the goal is pixel fidelity
+ * for an imported snapshot, not idiomatic hand-authored markup.
+ *
+ * This module is pure and synchronous: it never calls the network. The
+ * caller (an action) is responsible for:
+ *   1. Fetching the node JSON from the Figma REST API.
+ *   2. Calling `collectFallbackNodeIds` / `collectImageFillRefs` to find out
+ *      which nodes need a rendered PNG fallback and which image fills need
+ *      resolved URLs.
+ *   3. Fetching those via `/v1/images/:fileKey` (fallback renders) and
+ *      `/v1/files/:fileKey/images` (fill ref -> URL map).
+ *   4. Calling `mapFigmaNodeToHtml` with the resulting maps.
+ *
+ * ## Pixel-perfect property coverage
+ *
+ * | Property                                   | Fidelity      | Notes |
+ * | ------------------------------------------- | ------------- | ----- |
+ * | Position/size (absoluteBoundingBox)         | exact         | frame-relative |
+ * | Auto-layout (flex*)                         | exact         | Figma auto-layout IS flexbox |
+ * | Text font/size/weight/case/decoration/align | exact         | |
+ * | Line-height (px vs percent-of-font-size)    | exact         | resolved to px |
+ * | Letter-spacing                              | exact         | already px in REST API |
+ * | Solid fills                                 | exact         | |
+ * | Gradient fills (angle/position)              | exact (linear)/approximated (radial/angular/diamond) | derived from gradientHandlePositions, not a default angle |
+ * | Multiple fills (layering)                    | exact         | reversed to match CSS background-image stacking |
+ * | Image fills (scale modes)                    | exact (FILL/FIT/TILE/STRETCH-axis-aligned) / approximated (skewed imageTransform) | |
+ * | Strokes (uniform, align)                     | exact         | CENTER via outline+negative offset, INSIDE via inset box-shadow, OUTSIDE via outline |
+ * | Strokes (per-side weights)                   | approximated  | CSS has no per-side outline; falls back to per-side `border` (inside-only) |
+ * | Corner radii (uniform + per-corner)          | exact         | |
+ * | Effects: drop/inner shadow                   | exact         | |
+ * | Effects: layer/background blur               | approximated  | Figma <-> CSS blur radius scale is not publicly specified as 1:1 |
+ * | Opacity                                      | exact         | |
+ * | Blend modes (CSS-supported)                   | exact         | |
+ * | Blend modes (Figma-only: LINEAR_BURN/DODGE/LIGHTER/DARKER) | approximated | mapped to closest CSS equivalent |
+ * | clipsContent                                  | exact        | overflow: hidden |
+ * | Rotation                                      | approximated | pivots about the bounding-box center (see below) |
+ * | Vector networks / boolean ops / unsupported types | image fallback | never approximated structurally |
+ *
+ * ### Rotation caveat
+ * The REST API docs describe `rotation` as being in degrees, but the field
+ * is empirically returned in RADIANS (verified against known authored
+ * rotations via the Plugin API); this mapper converts it to degrees before
+ * use. `absoluteBoundingBox` is the *already-rotated* axis-aligned bounding
+ * box —
+ * Figma does not expose the pre-rotation box directly. We reconstruct the
+ * unrotated box by treating the AABB's center as invariant under rotation
+ * (true for a shape rotated about its own center) and rotate the CSS element
+ * about `transform-origin: center` by `-rotation` degrees (Figma's rotation
+ * is clockwise-negative relative to CSS's clockwise-positive convention).
+ * This is exact when Figma pivots rotation about the shape's center and only
+ * approximated if Figma's internal pivot differs (rare in practice; visually
+ * indistinguishable in the overwhelming majority of designs). A fully exact
+ * alternative would consume `relativeTransform` as a CSS `matrix()` directly,
+ * which is a documented follow-up if a specific design surfaces a visible
+ * mismatch.
+ */
+export interface FigmaColor {
+    r: number;
+    g: number;
+    b: number;
+    a?: number;
+}
+export interface FigmaColorStop {
+    position: number;
+    color: FigmaColor;
+}
+export interface FigmaImageFilter {
+    exposure?: number;
+    contrast?: number;
+    saturation?: number;
+    temperature?: number;
+    tint?: number;
+    highlights?: number;
+    shadows?: number;
+}
+export interface FigmaPaint {
+    type: "SOLID" | "GRADIENT_LINEAR" | "GRADIENT_RADIAL" | "GRADIENT_ANGULAR" | "GRADIENT_DIAMOND" | "IMAGE" | "EMOJI" | "VIDEO";
+    visible?: boolean;
+    opacity?: number;
+    color?: FigmaColor;
+    gradientHandlePositions?: Array<{
+        x: number;
+        y: number;
+    }>;
+    gradientStops?: FigmaColorStop[];
+    imageRef?: string;
+    scaleMode?: "FILL" | "FIT" | "TILE" | "STRETCH";
+    imageTransform?: [[number, number, number], [number, number, number]];
+    filters?: FigmaImageFilter;
+    blendMode?: string;
+}
+export interface FigmaEffect {
+    type: "DROP_SHADOW" | "INNER_SHADOW" | "LAYER_BLUR" | "BACKGROUND_BLUR";
+    visible?: boolean;
+    radius?: number;
+    spread?: number;
+    color?: FigmaColor;
+    offset?: {
+        x: number;
+        y: number;
+    };
+    blendMode?: string;
+}
+export interface FigmaTypeStyle {
+    fontFamily?: string;
+    fontPostScriptName?: string;
+    fontWeight?: number;
+    fontSize?: number;
+    italic?: boolean;
+    letterSpacing?: number;
+    lineHeightPx?: number;
+    lineHeightPercent?: number;
+    lineHeightPercentFontSize?: number;
+    lineHeightUnit?: "PIXELS" | "FONT_SIZE_%" | "INTRINSIC_%";
+    textCase?: "ORIGINAL" | "UPPER" | "LOWER" | "TITLE";
+    textDecoration?: "NONE" | "UNDERLINE" | "STRIKETHROUGH";
+    textAlignHorizontal?: "LEFT" | "RIGHT" | "CENTER" | "JUSTIFIED";
+    textAlignVertical?: "TOP" | "CENTER" | "BOTTOM";
+    textAutoResize?: "NONE" | "WIDTH_AND_HEIGHT" | "HEIGHT" | "TRUNCATE";
+    paragraphSpacing?: number;
+    paragraphIndent?: number;
+    listSpacing?: number;
+    hangingPunctuation?: boolean;
+    hangingList?: boolean;
+    opentypeFlags?: Record<string, number>;
+    hyperlink?: unknown;
+    fills?: FigmaPaint[];
+}
+export interface FigmaIndividualStrokeWeights {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+}
+export interface FigmaBoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface FigmaNode {
+    id: string;
+    name?: string;
+    type: string;
+    visible?: boolean;
+    opacity?: number;
+    blendMode?: string;
+    rotation?: number;
+    absoluteBoundingBox?: FigmaBoundingBox;
+    relativeTransform?: [[number, number, number], [number, number, number]];
+    /**
+     * The node's actual visual extent, INCLUDING stroke/effect overflow --
+     * e.g. an OUTSIDE-aligned stroke or a drop shadow makes this larger than
+     * `absoluteBoundingBox` (the purely geometric fill bounds). Figma's own
+     * `/v1/images` renders for a node are cropped to this box, not to
+     * `absoluteBoundingBox` -- sizing an image-fallback `<img>` using the
+     * geometric box instead squishes/crops the rendered PNG to the wrong
+     * aspect ratio whenever a fallback node has stroke/effect overflow.
+     */
+    absoluteRenderBounds?: FigmaBoundingBox;
+    size?: {
+        x: number;
+        y: number;
+    };
+    clipsContent?: boolean;
+    isMask?: boolean;
+    maskType?: "ALPHA" | "VECTOR" | "LUMINANCE";
+    arcData?: {
+        startingAngle?: number;
+        endingAngle?: number;
+        innerRadius?: number;
+    };
+    characters?: string;
+    style?: FigmaTypeStyle;
+    characterStyleOverrides?: number[];
+    styleOverrideTable?: Record<string, FigmaTypeStyle>;
+    lineTypes?: string[];
+    lineIndentations?: number[];
+    fills?: FigmaPaint[];
+    strokes?: FigmaPaint[];
+    strokeWeight?: number;
+    strokeAlign?: "INSIDE" | "OUTSIDE" | "CENTER";
+    individualStrokeWeights?: FigmaIndividualStrokeWeights;
+    strokeDashes?: number[];
+    cornerRadius?: number;
+    rectangleCornerRadii?: [number, number, number, number];
+    effects?: FigmaEffect[];
+    layoutMode?: "NONE" | "HORIZONTAL" | "VERTICAL" | "GRID";
+    layoutPositioning?: "AUTO" | "ABSOLUTE";
+    primaryAxisAlignItems?: "MIN" | "CENTER" | "MAX" | "SPACE_BETWEEN";
+    counterAxisAlignItems?: "MIN" | "CENTER" | "MAX" | "BASELINE";
+    layoutSizingHorizontal?: "FIXED" | "HUG" | "FILL";
+    layoutSizingVertical?: "FIXED" | "HUG" | "FILL";
+    layoutWrap?: "NO_WRAP" | "WRAP";
+    itemSpacing?: number;
+    counterAxisSpacing?: number;
+    paddingLeft?: number;
+    paddingRight?: number;
+    paddingTop?: number;
+    paddingBottom?: number;
+    minWidth?: number | null;
+    maxWidth?: number | null;
+    minHeight?: number | null;
+    maxHeight?: number | null;
+    componentId?: string;
+    componentProperties?: Record<string, unknown>;
+    boundVariables?: Record<string, unknown>;
+    interactions?: unknown[];
+    children?: FigmaNode[];
+}
+export type FidelityLevel = "exact" | "approximated" | "image-fallback";
+export interface FidelityEntry {
+    nodeId: string;
+    nodeName: string;
+    nodeType: string;
+    level: FidelityLevel;
+    notes: string[];
+}
+export interface FidelityReport {
+    entries: FidelityEntry[];
+    summary: {
+        exact: number;
+        approximated: number;
+        imageFallback: number;
+    };
+}
+export interface MapFigmaNodeOptions {
+    /** imageRef hash -> resolved public URL, from `/v1/files/:key/images`. */
+    imageFillUrls?: Record<string, string>;
+    /** nodeId -> rendered PNG URL, from `/v1/images/:key` for fallback subtrees. */
+    fallbackImageUrls?: Record<string, string>;
+    /** Node ids that should be rendered as an image regardless of type. */
+    forceImageFallbackNodeIds?: Set<string>;
+}
+export interface MapFigmaNodeResult {
+    html: string;
+    fidelity: FidelityReport;
+}
+/**
+ * Derive a CSS `linear-gradient()` angle (degrees) from Figma's normalized
+ * `gradientHandlePositions`. Handle positions are normalized independently in
+ * x and y (0..1 relative to the node's bounding box), so the angle must be
+ * computed in actual pixel space using the node's real width/height —
+ * otherwise a non-square box silently distorts the angle.
+ *
+ * Verified against Figma's documented identity handles
+ * (start=(0,0.5), end=(1,0.5), width=(1,0), i.e. a plain left-to-right
+ * gradient) which must resolve to CSS `90deg` ("to right"):
+ *   dx = 1*w, dy = 0  -> atan2(0, dx) = 0deg -> +90 = 90deg. Matches.
+ * And a top-to-bottom gradient (start=(0.5,0), end=(0.5,1)) must resolve to
+ * CSS `180deg` ("to bottom"):
+ *   dx = 0, dy = 1*h -> atan2(dy, 0) = 90deg -> +90 = 180deg. Matches.
+ */
+export declare function gradientAngleDegrees(paint: FigmaPaint, box: {
+    width: number;
+    height: number;
+}): number | null;
+/** Fail clearly before recursive rendering can overflow or lock the worker. */
+export declare function assertFigmaNodeTreeComplexity(node: FigmaNode): void;
+/**
+ * Walk a node tree and return the ids of every subtree that will render as a
+ * PNG image fallback (vector networks, boolean ops, and any node type this
+ * mapper does not model structurally). Call this before fetching node data
+ * so the caller can request rendered images for exactly these ids via
+ * `GET /v1/images/:fileKey?ids=...&scale=2`.
+ */
+export declare function collectFallbackNodeIds(node: FigmaNode, options?: MapFigmaNodeOptions): string[];
+/**
+ * Walk a node tree and return every distinct `imageRef` used by IMAGE fills
+ * (on fills or strokes) so the caller can resolve them to URLs via
+ * `GET /v1/files/:fileKey/images` before mapping.
+ */
+export declare function collectImageFillRefs(node: FigmaNode, options?: MapFigmaNodeOptions): string[];
+export interface FigmaFontUsage {
+    family: string;
+    weight: number;
+    italic: boolean;
+}
+/**
+ * Walk a node tree and return every distinct (font family, weight, italic)
+ * combination used by TEXT nodes -- including per-run character style
+ * overrides -- so the caller can request the actual web font (e.g. from
+ * Google Fonts) before the imported HTML is saved. Without this, an imported
+ * screen's CSS correctly names the intended font-family, but the browser has
+ * no way to load it and silently falls back to a generic sans-serif with
+ * different glyph advance widths -- individually invisible per character but
+ * compounding into a growing horizontal drift across any wrapped or
+ * multi-word line, worst on text-dense imports.
+ */
+export declare function collectFontUsage(node: FigmaNode): FigmaFontUsage[];
+/**
+ * Map a Figma node (and its subtree) to an HTML fragment plus a fidelity
+ * report describing which properties were exact, approximated, or rendered
+ * as an image fallback.
+ */
+export declare function mapFigmaNodeToHtml(node: FigmaNode, options?: MapFigmaNodeOptions): MapFigmaNodeResult;
+//# sourceMappingURL=figma-node-to-html.d.ts.map

package/dist/ingestion/figma-node-to-html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma-node-to-html.d.ts","sourceRoot":"","sources":["../../src/ingestion/figma-node-to-html.ts"],"names":[],"mappings":"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"}