@figma/code-connect 1.4.8 → 1.5.0

package/dist/connect/property_combinations.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toAvailableProperties = toAvailableProperties;
+exports.enumeratePropertyCombinations = enumeratePropertyCombinations;
+exports.buildPropertyCombinationFromProps = buildPropertyCombinationFromProps;
+const figma_rest_api_1 = require("./figma_rest_api");
+// Inlined copy of `normalizePropKey` from @figma/code-connect-snippet
+// (share/code-connect-snippet/src/figmadoc_utils.ts) — importing that unpublished
+// workspace package breaks a locally built/linked CLI. MUST stay in sync so the
+// property keys we send line up with the server's `.properties`.
+const PROP_ID_PATTERN = /(#[0-9]+:[0-9]+)/g;
+function normalizePropKey(key) {
+    return key.replace(PROP_ID_PATTERN, '').replace(/\s+/g, ' ').trim();
+}
+/** The typed, normalized property vocabulary of a component. */
+function toAvailableProperties(defs) {
+    return Object.entries(defs).map(([rawName, def]) => ({
+        name: normalizePropKey(rawName),
+        type: def.type,
+        ...(def.variantOptions ? { variantOptions: def.variantOptions } : {}),
+        default: def.defaultValue,
+    }));
+}
+/**
+ * Enumerate a component's renderable property combinations from its
+ * `componentPropertyDefinitions`: the cartesian product of VARIANT axes
+ * (their `variantOptions`) and BOOLEAN axes ({false, true}).
+ * TEXT/INSTANCE_SWAP props are held at `defaultValue` in every combination.
+ * Uncapped by default; pass `maxCombinations` to bound it.
+ */
+function enumeratePropertyCombinations(defs, opts = {}) {
+    const cap = opts.maxCombinations ?? Infinity;
+    const entries = Object.entries(defs);
+    const availableProperties = toAvailableProperties(defs);
+    const axes = [];
+    const fixed = [];
+    for (const [rawName, def] of entries) {
+        const name = normalizePropKey(rawName);
+        if (def.type === figma_rest_api_1.FigmaRestApi.ComponentPropertyType.Variant) {
+            const values = def.variantOptions && def.variantOptions.length > 0
+                ? def.variantOptions
+                : [String(def.defaultValue)];
+            axes.push({ name, type: def.type, values });
+        }
+        else if (def.type === figma_rest_api_1.FigmaRestApi.ComponentPropertyType.Boolean) {
+            axes.push({ name, type: def.type, values: [false, true] });
+        }
+        else {
+            // TEXT, INSTANCE_SWAP — held at default, present in every combination.
+            fixed.push({ name, type: def.type, value: def.defaultValue });
+        }
+    }
+    const total = axes.reduce((n, axis) => n * axis.values.length, 1);
+    const count = Math.min(total, cap);
+    // Generate combinations by mixed-radix index decoding so we never materialize
+    // more than `cap` combinations, even if the full product is enormous.
+    const propertyCombinations = [];
+    for (let i = 0; i < count; i++) {
+        let rem = i;
+        const varying = [];
+        const labelParts = [];
+        for (const axis of axes) {
+            const value = axis.values[rem % axis.values.length];
+            rem = Math.floor(rem / axis.values.length);
+            varying.push({ name: axis.name, type: axis.type, value });
+            labelParts.push(`${axis.name}=${value}`);
+        }
+        propertyCombinations.push({
+            label: labelParts.length > 0 ? labelParts.join(', ') : 'default',
+            properties: [...varying, ...fixed],
+        });
+    }
+    return {
+        propertyCombinations,
+        availableProperties,
+        truncated: total > cap ? { total, cap } : null,
+    };
+}
+/**
+ * Build a single property combination from an explicit set of `name=value` pairs
+ */
+function buildPropertyCombinationFromProps(defs, pairs) {
+    // lowercase normalized name -> all defs sharing that name (usually one, but a
+    // name can be shared across types — those must stay distinct for `TYPE:` matching).
+    const defsByLower = new Map();
+    for (const [rawName, def] of Object.entries(defs)) {
+        const canonical = normalizePropKey(rawName);
+        const lower = canonical.toLowerCase();
+        const list = defsByLower.get(lower) ?? [];
+        list.push({ canonical, def });
+        defsByLower.set(lower, list);
+    }
+    const availableProperties = toAvailableProperties(defs);
+    // Seed every property (one entry per def, so same-named/different-type props
+    // both appear) at its default so the overlay is always complete.
+    const properties = Object.entries(defs).map(([rawName, def]) => ({
+        name: normalizePropKey(rawName),
+        type: def.type,
+        value: def.defaultValue,
+    }));
+    const setValue = (name, type, value) => {
+        const entry = properties.find((p) => p.name === name && p.type === type);
+        if (entry) {
+            entry.value = value;
+        }
+        else {
+            properties.push({ name, type, value });
+        }
+    };
+    const unknown = [];
+    const invalid = [];
+    const ambiguous = [];
+    const applied = [];
+    for (const { name: rawName, value, type } of pairs) {
+        const candidates = defsByLower.get(normalizePropKey(rawName).toLowerCase());
+        if (!candidates || candidates.length === 0) {
+            unknown.push(type ? `${type}:${rawName}` : rawName);
+            continue;
+        }
+        let match;
+        if (type) {
+            match = candidates.find((c) => c.def.type === type);
+            if (!match) {
+                // A type was given but no property of that type exists under this name.
+                unknown.push(`${type}:${rawName}`);
+                continue;
+            }
+        }
+        else if (candidates.length > 1) {
+            ambiguous.push({ name: candidates[0].canonical, types: candidates.map((c) => c.def.type) });
+            continue;
+        }
+        else {
+            match = candidates[0];
+        }
+        const { canonical, def } = match;
+        if (def.type === figma_rest_api_1.FigmaRestApi.ComponentPropertyType.Variant && def.variantOptions?.length) {
+            // Case-insensitive match against the real options.
+            const option = def.variantOptions.find((o) => o.toLowerCase() === value.toLowerCase());
+            if (!option) {
+                invalid.push({ name: canonical, value, options: def.variantOptions });
+                continue;
+            }
+            setValue(canonical, def.type, option);
+            applied.push({ name: canonical, type: def.type, value: option });
+            continue;
+        }
+        const coerced = def.type === figma_rest_api_1.FigmaRestApi.ComponentPropertyType.Boolean
+            ? /^(true|1|yes|on)$/i.test(value.trim())
+            : value;
+        setValue(canonical, def.type, coerced);
+        applied.push({ name: canonical, type: def.type, value: coerced });
+    }
+    // Prefix the type in the label only when a name was applied for more than one
+    // type, so the render label stays unambiguous without noise in the common case.
+    const nameCounts = new Map();
+    for (const a of applied)
+        nameCounts.set(a.name, (nameCounts.get(a.name) ?? 0) + 1);
+    const label = applied.length > 0
+        ? applied
+            .map((a) => `${(nameCounts.get(a.name) ?? 0) > 1 ? `${a.type}:` : ''}${a.name}=${a.value}`)
+            .join(', ')
+        : 'default';
+    return {
+        propertyCombination: { label, properties },
+        availableProperties,
+        unknown,
+        invalid,
+        ambiguous,
+    };
+}
+//# sourceMappingURL=property_combinations.js.map

package/dist/connect/property_combinations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"property_combinations.js","sourceRoot":"","sources":["../../src/connect/property_combinations.ts"],"names":[],"mappings":"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","sourcesContent":["import { FigmaRestApi } from './figma_rest_api'\n\n// Inlined copy of `normalizePropKey` from @figma/code-connect-snippet\n// (share/code-connect-snippet/src/figmadoc_utils.ts) — importing that unpublished\n// workspace package breaks a locally built/linked CLI. MUST stay in sync so the\n// property keys we send line up with the server's `.properties`.\nconst PROP_ID_PATTERN = /(#[0-9]+:[0-9]+)/g\nfunction normalizePropKey(key: string): string {\n  return key.replace(PROP_ID_PATTERN, '').replace(/\\s+/g, ' ').trim()\n}\n\n/**\n * A single property value to overlay a node's `.properties`. `name` is normalized\n * (no `#id` suffix) so it matches template references, e.g. `figma.boolean('Has Icon Start')`.\n */\nexport interface PropertyCombinationValue {\n  name: string\n  type: FigmaRestApi.ComponentPropertyType\n  value: string | boolean\n}\n\n/** One renderable property combination: a label plus the full set of property values to overlay. */\nexport interface PropertyCombination {\n  label: string\n  properties: PropertyCombinationValue[]\n}\n\n/** The typed vocabulary of a component's properties, attached to failed previews for repair hints. */\nexport interface AvailableProperty {\n  name: string\n  type: FigmaRestApi.ComponentPropertyType\n  variantOptions?: string[]\n  default?: string | boolean\n}\n\n/** The typed, normalized property vocabulary of a component. */\nexport function toAvailableProperties(\n  defs: Record<string, FigmaRestApi.ComponentPropertyDefinition>,\n): AvailableProperty[] {\n  return Object.entries(defs).map(([rawName, def]) => ({\n    name: normalizePropKey(rawName),\n    type: def.type,\n    ...(def.variantOptions ? { variantOptions: def.variantOptions } : {}),\n    default: def.defaultValue,\n  }))\n}\n\nexport interface EnumeratePropertyCombinationsResult {\n  propertyCombinations: PropertyCombination[]\n  availableProperties: AvailableProperty[]\n  /** Set only when an explicit `maxCombinations` cap truncated the full cartesian. */\n  truncated: { total: number; cap: number } | null\n}\n\n/**\n * Enumerate a component's renderable property combinations from its\n * `componentPropertyDefinitions`: the cartesian product of VARIANT axes\n * (their `variantOptions`) and BOOLEAN axes ({false, true}).\n * TEXT/INSTANCE_SWAP props are held at `defaultValue` in every combination.\n * Uncapped by default; pass `maxCombinations` to bound it.\n */\nexport function enumeratePropertyCombinations(\n  defs: Record<string, FigmaRestApi.ComponentPropertyDefinition>,\n  opts: { maxCombinations?: number } = {},\n): EnumeratePropertyCombinationsResult {\n  const cap = opts.maxCombinations ?? Infinity\n  const entries = Object.entries(defs)\n\n  const availableProperties = toAvailableProperties(defs)\n\n  // Axes we enumerate (VARIANT, BOOLEAN); everything else is held at its default.\n  interface Axis {\n    name: string\n    type: FigmaRestApi.ComponentPropertyType\n    values: (string | boolean)[]\n  }\n  const axes: Axis[] = []\n  const fixed: PropertyCombinationValue[] = []\n\n  for (const [rawName, def] of entries) {\n    const name = normalizePropKey(rawName)\n    if (def.type === FigmaRestApi.ComponentPropertyType.Variant) {\n      const values =\n        def.variantOptions && def.variantOptions.length > 0\n          ? def.variantOptions\n          : [String(def.defaultValue)]\n      axes.push({ name, type: def.type, values })\n    } else if (def.type === FigmaRestApi.ComponentPropertyType.Boolean) {\n      axes.push({ name, type: def.type, values: [false, true] })\n    } else {\n      // TEXT, INSTANCE_SWAP — held at default, present in every combination.\n      fixed.push({ name, type: def.type, value: def.defaultValue })\n    }\n  }\n\n  const total = axes.reduce((n, axis) => n * axis.values.length, 1)\n  const count = Math.min(total, cap)\n\n  // Generate combinations by mixed-radix index decoding so we never materialize\n  // more than `cap` combinations, even if the full product is enormous.\n  const propertyCombinations: PropertyCombination[] = []\n  for (let i = 0; i < count; i++) {\n    let rem = i\n    const varying: PropertyCombinationValue[] = []\n    const labelParts: string[] = []\n    for (const axis of axes) {\n      const value = axis.values[rem % axis.values.length]\n      rem = Math.floor(rem / axis.values.length)\n      varying.push({ name: axis.name, type: axis.type, value })\n      labelParts.push(`${axis.name}=${value}`)\n    }\n    propertyCombinations.push({\n      label: labelParts.length > 0 ? labelParts.join(', ') : 'default',\n      properties: [...varying, ...fixed],\n    })\n  }\n\n  return {\n    propertyCombinations,\n    availableProperties,\n    truncated: total > cap ? { total, cap } : null,\n  }\n}\n\nexport interface BuildPropertyCombinationResult {\n  propertyCombination: PropertyCombination\n  availableProperties: AvailableProperty[]\n  /** Supplied property names that don't exist on the component. */\n  unknown: string[]\n  /** Supplied values that aren't valid for their VARIANT property. */\n  invalid: Array<{ name: string; value: string; options: string[] }>\n  /** Supplied names that match multiple types with no `TYPE:` prefix to disambiguate. */\n  ambiguous: Array<{ name: string; types: FigmaRestApi.ComponentPropertyType[] }>\n}\n\n/**\n * Build a single property combination from an explicit set of `name=value` pairs\n */\nexport function buildPropertyCombinationFromProps(\n  defs: Record<string, FigmaRestApi.ComponentPropertyDefinition>,\n  pairs: Array<{ name: string; value: string; type?: FigmaRestApi.ComponentPropertyType }>,\n): BuildPropertyCombinationResult {\n  // lowercase normalized name -> all defs sharing that name (usually one, but a\n  // name can be shared across types — those must stay distinct for `TYPE:` matching).\n  const defsByLower = new Map<\n    string,\n    Array<{ canonical: string; def: FigmaRestApi.ComponentPropertyDefinition }>\n  >()\n  for (const [rawName, def] of Object.entries(defs)) {\n    const canonical = normalizePropKey(rawName)\n    const lower = canonical.toLowerCase()\n    const list = defsByLower.get(lower) ?? []\n    list.push({ canonical, def })\n    defsByLower.set(lower, list)\n  }\n\n  const availableProperties = toAvailableProperties(defs)\n\n  // Seed every property (one entry per def, so same-named/different-type props\n  // both appear) at its default so the overlay is always complete.\n  const properties: PropertyCombinationValue[] = Object.entries(defs).map(([rawName, def]) => ({\n    name: normalizePropKey(rawName),\n    type: def.type,\n    value: def.defaultValue,\n  }))\n  const setValue = (\n    name: string,\n    type: FigmaRestApi.ComponentPropertyType,\n    value: string | boolean,\n  ) => {\n    const entry = properties.find((p) => p.name === name && p.type === type)\n    if (entry) {\n      entry.value = value\n    } else {\n      properties.push({ name, type, value })\n    }\n  }\n\n  const unknown: string[] = []\n  const invalid: Array<{ name: string; value: string; options: string[] }> = []\n  const ambiguous: Array<{ name: string; types: FigmaRestApi.ComponentPropertyType[] }> = []\n  const applied: Array<{\n    name: string\n    type: FigmaRestApi.ComponentPropertyType\n    value: string | boolean\n  }> = []\n\n  for (const { name: rawName, value, type } of pairs) {\n    const candidates = defsByLower.get(normalizePropKey(rawName).toLowerCase())\n    if (!candidates || candidates.length === 0) {\n      unknown.push(type ? `${type}:${rawName}` : rawName)\n      continue\n    }\n\n    let match: { canonical: string; def: FigmaRestApi.ComponentPropertyDefinition } | undefined\n    if (type) {\n      match = candidates.find((c) => c.def.type === type)\n      if (!match) {\n        // A type was given but no property of that type exists under this name.\n        unknown.push(`${type}:${rawName}`)\n        continue\n      }\n    } else if (candidates.length > 1) {\n      ambiguous.push({ name: candidates[0].canonical, types: candidates.map((c) => c.def.type) })\n      continue\n    } else {\n      match = candidates[0]\n    }\n\n    const { canonical, def } = match\n\n    if (def.type === FigmaRestApi.ComponentPropertyType.Variant && def.variantOptions?.length) {\n      // Case-insensitive match against the real options.\n      const option = def.variantOptions.find((o) => o.toLowerCase() === value.toLowerCase())\n      if (!option) {\n        invalid.push({ name: canonical, value, options: def.variantOptions })\n        continue\n      }\n      setValue(canonical, def.type, option)\n      applied.push({ name: canonical, type: def.type, value: option })\n      continue\n    }\n\n    const coerced: string | boolean =\n      def.type === FigmaRestApi.ComponentPropertyType.Boolean\n        ? /^(true|1|yes|on)$/i.test(value.trim())\n        : value\n    setValue(canonical, def.type, coerced)\n    applied.push({ name: canonical, type: def.type, value: coerced })\n  }\n\n  // Prefix the type in the label only when a name was applied for more than one\n  // type, so the render label stays unambiguous without noise in the common case.\n  const nameCounts = new Map<string, number>()\n  for (const a of applied) nameCounts.set(a.name, (nameCounts.get(a.name) ?? 0) + 1)\n  const label =\n    applied.length > 0\n      ? applied\n          .map(\n            (a) => `${(nameCounts.get(a.name) ?? 0) > 1 ? `${a.type}:` : ''}${a.name}=${a.value}`,\n          )\n          .join(', ')\n      : 'default'\n  return {\n    propertyCombination: { label, properties },\n    availableProperties,\n    unknown,\n    invalid,\n    ambiguous,\n  }\n}\n"]}

package/dist/connect/raw_template_bundler.d.ts

@@ -0,0 +1,13 @@
+import ts from 'typescript';
+export declare const allowedHelperExtensions: string[];
+export declare function isRelativeImportPath(moduleSpecifier: string): boolean;
+export declare function unsupportedImportError(filePath: string, importLine: string): Error;
+export declare function getRequireCallRequest(node: ts.Node): string | undefined;
+export declare function relativeRequireError(filePath: string, request: string): Error;
+/**
+ * Bundles a template and its relative helper graph into one self-contained
+ * script. Every module other than `figma` must be a relative helper inside the
+ * project directory.
+ */
+export declare function bundleTemplateWithHelpers(filePath: string, projectRoot: string): Promise<string>;
+//# sourceMappingURL=raw_template_bundler.d.ts.map

package/dist/connect/raw_template_bundler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw_template_bundler.d.ts","sourceRoot":"","sources":["../../src/connect/raw_template_bundler.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,YAAY,CAAA;AAG3B,eAAO,MAAM,uBAAuB,UAAiC,CAAA;AAErE,wBAAgB,oBAAoB,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAErE;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,KAAK,CAQlF;AA2BD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,GAAG,MAAM,GAAG,SAAS,CAWvE;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,CAQ7E;AA0ED;;;;GAIG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,CAqCjB"}

package/dist/connect/raw_template_bundler.js

@@ -0,0 +1,178 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.allowedHelperExtensions = void 0;
+exports.isRelativeImportPath = isRelativeImportPath;
+exports.unsupportedImportError = unsupportedImportError;
+exports.getRequireCallRequest = getRequireCallRequest;
+exports.relativeRequireError = relativeRequireError;
+exports.bundleTemplateWithHelpers = bundleTemplateWithHelpers;
+const path_1 = __importDefault(require("path"));
+const typescript_1 = __importDefault(require("typescript"));
+const esbuild_wasm_1 = require("esbuild-wasm");
+exports.allowedHelperExtensions = ['.ts', '.js', '.mjs', '.cjs'];
+function isRelativeImportPath(moduleSpecifier) {
+    return moduleSpecifier.startsWith('./') || moduleSpecifier.startsWith('../');
+}
+function unsupportedImportError(filePath, importLine) {
+    return new Error(`TypeScript template files only support importing from 'figma' and relative helper files.\n` +
+        `Found in ${filePath}:\n` +
+        `  ${importLine}\n\n` +
+        `Use "const figma = require('figma')" or "import figma from 'figma'" for the Figma API.\n` +
+        `Helper imports must use relative paths (for example: "./helpers").`);
+}
+let bundlerInitialization;
+function ensureBundlerInitialized() {
+    if (bundlerInitialization) {
+        return bundlerInitialization;
+    }
+    const initialization = (0, esbuild_wasm_1.initialize)({}).catch((error) => {
+        // esbuild-wasm throws if initialize() runs twice in a process (e.g. across
+        // test files sharing a worker); the engine is already up, so treat as done.
+        if (error instanceof Error && /more than once/.test(error.message)) {
+            return;
+        }
+        bundlerInitialization = undefined;
+        throw error;
+    });
+    bundlerInitialization = initialization;
+    return initialization;
+}
+// special treatment for `require('figma')`
+const REQUIRE_ALIAS = '__figmaRequire';
+const FIGMA_RUNTIME_NAMESPACE = 'figma-runtime';
+// A `require('x')` call node's string request, else undefined.
+function getRequireCallRequest(node) {
+    if (typescript_1.default.isCallExpression(node) &&
+        typescript_1.default.isIdentifier(node.expression) &&
+        node.expression.text === 'require' &&
+        node.arguments.length === 1 &&
+        typescript_1.default.isStringLiteral(node.arguments[0])) {
+        return node.arguments[0].text;
+    }
+    return undefined;
+}
+function relativeRequireError(filePath, request) {
+    return new Error(`Helper files must be imported, not required.\n` +
+        `Found in ${filePath}:\n` +
+        `  require('${request}')\n\n` +
+        `Use "import { helper } from '${request}'" instead. Only the Figma API may ` +
+        `be required: "const figma = require('figma')".`);
+}
+// Resolves `figma` to a virtual module backed by the runtime `require`. Marking
+// it external instead would leave a top-level `import`, which the runtime can't
+// execute (the template body runs inside a function).
+function figmaRuntimePlugin() {
+    return {
+        name: FIGMA_RUNTIME_NAMESPACE,
+        setup(pluginBuild) {
+            pluginBuild.onResolve({ filter: /^figma$/ }, () => ({
+                path: 'figma',
+                namespace: FIGMA_RUNTIME_NAMESPACE,
+            }));
+            pluginBuild.onLoad({ filter: /.*/, namespace: FIGMA_RUNTIME_NAMESPACE }, () => ({
+                contents: `export default require('figma')`,
+                loader: 'js',
+            }));
+        },
+    };
+}
+const UNBUNDLED_REQUIRE_REGEX = new RegExp(`\\b${REQUIRE_ALIAS}\\(\\s*["']([^"']+)["']`, 'g');
+// Fails on any `require` left in the bundle other than `require('figma')`
+function assertNoUnbundledRequires(bundled, filePath) {
+    for (const [, request] of bundled.matchAll(UNBUNDLED_REQUIRE_REGEX)) {
+        if (request === 'figma') {
+            continue;
+        }
+        throw isRelativeImportPath(request)
+            ? relativeRequireError(filePath, request)
+            : unsupportedImportError(filePath, `require('${request}')`);
+    }
+}
+const ESBUILD_OPTIONS = {
+    bundle: true,
+    format: 'esm',
+    platform: 'neutral',
+    define: { require: REQUIRE_ALIAS },
+    banner: { js: `var ${REQUIRE_ALIAS} = require;` },
+    target: 'es2021',
+    plugins: [figmaRuntimePlugin()],
+    resolveExtensions: exports.allowedHelperExtensions,
+    metafile: true,
+    write: false,
+    logLevel: 'silent',
+    legalComments: 'none',
+    // Ignore project tsconfig for deterministic bundling across codebases.
+    tsconfigRaw: '{}',
+};
+// Maps an esbuild resolution failure to the same errors the entry validator uses.
+function mapEsbuildBundleError(error, filePath) {
+    const esbuildErrors = error?.errors;
+    if (Array.isArray(esbuildErrors)) {
+        for (const { text } of esbuildErrors) {
+            const match = /Could not resolve "([^"]+)"/.exec(text ?? '');
+            if (!match) {
+                continue;
+            }
+            const specifier = match[1];
+            if (isRelativeImportPath(specifier)) {
+                return new Error(`Could not resolve helper import "${specifier}" in ${filePath}. ` +
+                    `Ensure the helper file exists and uses one of: ${exports.allowedHelperExtensions.join(', ')}`);
+            }
+            return unsupportedImportError(filePath, `import ... from '${specifier}'`);
+        }
+    }
+    return error instanceof Error ? error : new Error(String(error));
+}
+/**
+ * Bundles a template and its relative helper graph into one self-contained
+ * script. Every module other than `figma` must be a relative helper inside the
+ * project directory.
+ */
+async function bundleTemplateWithHelpers(filePath, projectRoot) {
+    const entryPath = path_1.default.resolve(filePath);
+    await ensureBundlerInitialized();
+    let result;
+    try {
+        result = await (0, esbuild_wasm_1.build)({
+            ...ESBUILD_OPTIONS,
+            entryPoints: [entryPath],
+            absWorkingDir: projectRoot,
+        });
+    }
+    catch (error) {
+        throw mapEsbuildBundleError(error, filePath);
+    }
+    // Enforce the allowlist: no package deps, nothing outside the project root.
+    for (const inputPath of Object.keys(result.metafile?.inputs ?? {})) {
+        if (inputPath.split('/').includes('node_modules')) {
+            throw unsupportedImportError(filePath, `import ... from a package ('${inputPath}')`);
+        }
+        if (inputPath.startsWith('..') || path_1.default.isAbsolute(inputPath)) {
+            throw new Error(`Refusing to bundle helper "${inputPath}" from ${filePath}: ` +
+                `it resolves outside the project directory. Helper files must live within the project.`);
+        }
+    }
+    const bundled = result.outputFiles?.[0]?.text;
+    if (bundled === undefined) {
+        throw new Error(`Failed to bundle template ${filePath}: esbuild produced no output.`);
+    }
+    assertNoUnbundledRequires(bundled, filePath);
+    return rewriteDefaultExport(bundled, filePath);
+}
+const ESM_DEFAULT_EXPORT_REGEX = /export\s*\{\s*([A-Za-z0-9_$]+)\s+as\s+default\s*,?\s*\};?\s*$/;
+/**
+ * Turns esbuild's trailing `export { Foo as default };` into `export default Foo` for runtime purposes.
+ */
+function rewriteDefaultExport(bundled, filePath) {
+    const trimmed = bundled.trimEnd();
+    const match = ESM_DEFAULT_EXPORT_REGEX.exec(trimmed);
+    if (!match) {
+        throw new Error(`Failed to bundle template ${filePath}: no default export found. ` +
+            `Template files must end with "export default { ... }".`);
+    }
+    return `${trimmed.slice(0, match.index)}export default ${match[1]}\n`;
+}
+//# sourceMappingURL=raw_template_bundler.js.map

package/dist/connect/raw_template_bundler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw_template_bundler.js","sourceRoot":"","sources":["../../src/connect/raw_template_bundler.ts"],"names":[],"mappings":"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","sourcesContent":["import path from 'path'\nimport ts from 'typescript'\nimport { build, initialize, type BuildOptions } from 'esbuild-wasm'\n\nexport const allowedHelperExtensions = ['.ts', '.js', '.mjs', '.cjs']\n\nexport function isRelativeImportPath(moduleSpecifier: string): boolean {\n  return moduleSpecifier.startsWith('./') || moduleSpecifier.startsWith('../')\n}\n\nexport function unsupportedImportError(filePath: string, importLine: string): Error {\n  return new Error(\n    `TypeScript template files only support importing from 'figma' and relative helper files.\\n` +\n      `Found in ${filePath}:\\n` +\n      `  ${importLine}\\n\\n` +\n      `Use \"const figma = require('figma')\" or \"import figma from 'figma'\" for the Figma API.\\n` +\n      `Helper imports must use relative paths (for example: \"./helpers\").`,\n  )\n}\n\nlet bundlerInitialization: Promise<void> | undefined\n\nfunction ensureBundlerInitialized(): Promise<void> {\n  if (bundlerInitialization) {\n    return bundlerInitialization\n  }\n  const initialization = initialize({}).catch((error: unknown) => {\n    // esbuild-wasm throws if initialize() runs twice in a process (e.g. across\n    // test files sharing a worker); the engine is already up, so treat as done.\n    if (error instanceof Error && /more than once/.test(error.message)) {\n      return\n    }\n    bundlerInitialization = undefined\n    throw error\n  })\n  bundlerInitialization = initialization\n  return initialization\n}\n\n// special treatment for `require('figma')`\nconst REQUIRE_ALIAS = '__figmaRequire'\n\nconst FIGMA_RUNTIME_NAMESPACE = 'figma-runtime'\n\n// A `require('x')` call node's string request, else undefined.\nexport function getRequireCallRequest(node: ts.Node): string | undefined {\n  if (\n    ts.isCallExpression(node) &&\n    ts.isIdentifier(node.expression) &&\n    node.expression.text === 'require' &&\n    node.arguments.length === 1 &&\n    ts.isStringLiteral(node.arguments[0])\n  ) {\n    return node.arguments[0].text\n  }\n  return undefined\n}\n\nexport function relativeRequireError(filePath: string, request: string): Error {\n  return new Error(\n    `Helper files must be imported, not required.\\n` +\n      `Found in ${filePath}:\\n` +\n      `  require('${request}')\\n\\n` +\n      `Use \"import { helper } from '${request}'\" instead. Only the Figma API may ` +\n      `be required: \"const figma = require('figma')\".`,\n  )\n}\n\n// Resolves `figma` to a virtual module backed by the runtime `require`. Marking\n// it external instead would leave a top-level `import`, which the runtime can't\n// execute (the template body runs inside a function).\nfunction figmaRuntimePlugin(): NonNullable<BuildOptions['plugins']>[number] {\n  return {\n    name: FIGMA_RUNTIME_NAMESPACE,\n    setup(pluginBuild) {\n      pluginBuild.onResolve({ filter: /^figma$/ }, () => ({\n        path: 'figma',\n        namespace: FIGMA_RUNTIME_NAMESPACE,\n      }))\n      pluginBuild.onLoad({ filter: /.*/, namespace: FIGMA_RUNTIME_NAMESPACE }, () => ({\n        contents: `export default require('figma')`,\n        loader: 'js',\n      }))\n    },\n  }\n}\n\nconst UNBUNDLED_REQUIRE_REGEX = new RegExp(`\\\\b${REQUIRE_ALIAS}\\\\(\\\\s*[\"']([^\"']+)[\"']`, 'g')\n\n// Fails on any `require` left in the bundle other than `require('figma')`\nfunction assertNoUnbundledRequires(bundled: string, filePath: string): void {\n  for (const [, request] of bundled.matchAll(UNBUNDLED_REQUIRE_REGEX)) {\n    if (request === 'figma') {\n      continue\n    }\n    throw isRelativeImportPath(request)\n      ? relativeRequireError(filePath, request)\n      : unsupportedImportError(filePath, `require('${request}')`)\n  }\n}\n\nconst ESBUILD_OPTIONS: BuildOptions = {\n  bundle: true,\n  format: 'esm',\n  platform: 'neutral',\n  define: { require: REQUIRE_ALIAS },\n  banner: { js: `var ${REQUIRE_ALIAS} = require;` },\n  target: 'es2021',\n  plugins: [figmaRuntimePlugin()],\n  resolveExtensions: allowedHelperExtensions,\n  metafile: true,\n  write: false,\n  logLevel: 'silent',\n  legalComments: 'none',\n  // Ignore project tsconfig for deterministic bundling across codebases.\n  tsconfigRaw: '{}',\n}\n\n// Maps an esbuild resolution failure to the same errors the entry validator uses.\nfunction mapEsbuildBundleError(error: unknown, filePath: string): Error {\n  const esbuildErrors = (error as { errors?: Array<{ text?: string }> })?.errors\n  if (Array.isArray(esbuildErrors)) {\n    for (const { text } of esbuildErrors) {\n      const match = /Could not resolve \"([^\"]+)\"/.exec(text ?? '')\n      if (!match) {\n        continue\n      }\n      const specifier = match[1]\n      if (isRelativeImportPath(specifier)) {\n        return new Error(\n          `Could not resolve helper import \"${specifier}\" in ${filePath}. ` +\n            `Ensure the helper file exists and uses one of: ${allowedHelperExtensions.join(', ')}`,\n        )\n      }\n      return unsupportedImportError(filePath, `import ... from '${specifier}'`)\n    }\n  }\n  return error instanceof Error ? error : new Error(String(error))\n}\n\n/**\n * Bundles a template and its relative helper graph into one self-contained\n * script. Every module other than `figma` must be a relative helper inside the\n * project directory.\n */\nexport async function bundleTemplateWithHelpers(\n  filePath: string,\n  projectRoot: string,\n): Promise<string> {\n  const entryPath = path.resolve(filePath)\n\n  await ensureBundlerInitialized()\n\n  let result\n  try {\n    result = await build({\n      ...ESBUILD_OPTIONS,\n      entryPoints: [entryPath],\n      absWorkingDir: projectRoot,\n    })\n  } catch (error) {\n    throw mapEsbuildBundleError(error, filePath)\n  }\n\n  // Enforce the allowlist: no package deps, nothing outside the project root.\n  for (const inputPath of Object.keys(result.metafile?.inputs ?? {})) {\n    if (inputPath.split('/').includes('node_modules')) {\n      throw unsupportedImportError(filePath, `import ... from a package ('${inputPath}')`)\n    }\n    if (inputPath.startsWith('..') || path.isAbsolute(inputPath)) {\n      throw new Error(\n        `Refusing to bundle helper \"${inputPath}\" from ${filePath}: ` +\n          `it resolves outside the project directory. Helper files must live within the project.`,\n      )\n    }\n  }\n\n  const bundled = result.outputFiles?.[0]?.text\n  if (bundled === undefined) {\n    throw new Error(`Failed to bundle template ${filePath}: esbuild produced no output.`)\n  }\n\n  assertNoUnbundledRequires(bundled, filePath)\n\n  return rewriteDefaultExport(bundled, filePath)\n}\n\nconst ESM_DEFAULT_EXPORT_REGEX = /export\\s*\\{\\s*([A-Za-z0-9_$]+)\\s+as\\s+default\\s*,?\\s*\\};?\\s*$/\n\n/**\n * Turns esbuild's trailing `export { Foo as default };` into `export default Foo` for runtime purposes.\n */\nfunction rewriteDefaultExport(bundled: string, filePath: string): string {\n  const trimmed = bundled.trimEnd()\n  const match = ESM_DEFAULT_EXPORT_REGEX.exec(trimmed)\n  if (!match) {\n    throw new Error(\n      `Failed to bundle template ${filePath}: no default export found. ` +\n        `Template files must end with \"export default { ... }\".`,\n    )\n  }\n  return `${trimmed.slice(0, match.index)}export default ${match[1]}\\n`\n}\n"]}

package/dist/connect/raw_templates.d.ts

@@ -24,5 +24,5 @@ export interface BatchOverrides {
     batchData: Record<string, any>;
     batchFilePath: string;
 }
-export declare function parseRawFile(filePath: string, label: string | undefined, config?: CodeConnectConfig, dir?: string, batchOverrides?: BatchOverrides): CodeConnectJSON;
+export declare function parseRawFile(filePath: string, label: string | undefined, config?: CodeConnectConfig, dir?: string, batchOverrides?: BatchOverrides): Promise<CodeConnectJSON>;
 //# sourceMappingURL=raw_templates.d.ts.map

package/dist/connect/raw_templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"raw_templates.d.ts","sourceRoot":"","sources":["../../src/connect/raw_templates.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAI7C;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAatD;AAsFD,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC9B,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,MAAM,CAAC,EAAE,iBAAiB,EAC1B,GAAG,CAAC,EAAE,MAAM,EACZ,cAAc,CAAC,EAAE,cAAc,GAC9B,eAAe,CAgGjB"}
+{"version":3,"file":"raw_templates.d.ts","sourceRoot":"","sources":["../../src/connect/raw_templates.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAY7C;;;;;;GAMG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAatD;AA2JD,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC9B,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,MAAM,CAAC,EAAE,iBAAiB,EAC1B,GAAG,CAAC,EAAE,MAAM,EACZ,cAAc,CAAC,EAAE,cAAc,GAC9B,OAAO,CAAC,eAAe,CAAC,CA+G1B"}

package/dist/connect/raw_templates.js

@@ -7,9 +7,11 @@ exports.CodePropertiesError = void 0;
 exports.isRawTemplate = isRawTemplate;
 exports.parseRawFile = parseRawFile;
 const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
 const typescript_1 = __importDefault(require("typescript"));
 const label_language_mapping_1 = require("./label_language_mapping");
 const helpers_1 = require("./helpers");
+const raw_template_bundler_1 = require("./raw_template_bundler");
 /**
  * Thrown when a raw template file has no `// url=` directive but contains the
  * string `codeProperties`. These files (e.g. Make's code component property
@@ -46,26 +48,75 @@ function isRawTemplate(content) {
 }
 // Convert ESM import of 'figma' to require syntax. Supports: import figma from 'figma'
 const figmaImportRegex = /^import\s+figma\s+from\s+['"]figma['"]\s*;?\s*$/m;
+// Matches the backend's max template size; we fail here rather than let the
+// server reject the publish request.
+const MAX_TEMPLATE_SIZE_MB = 1;
+function assertTemplateWithinSizeLimit(filePath, template) {
+    const sizeMb = Buffer.byteLength(template, 'utf-8') / (1024 * 1024);
+    if (sizeMb > MAX_TEMPLATE_SIZE_MB) {
+        throw new Error(`Template "${filePath}" is ${sizeMb.toFixed(2)}mb, which exceeds the ` +
+            `${MAX_TEMPLATE_SIZE_MB}mb maximum template size. ` +
+            `Reduce the template size, for example by removing unneeded helper imports.`);
+    }
+}
+// Parserless entry templates may be authored in TypeScript or JavaScript.
+function isRawTemplateSourceFile(filePath) {
+    return raw_template_bundler_1.allowedHelperExtensions.some((ext) => filePath.endsWith(ext));
+}
 /**
- * Throws if the file imports from anything other than 'figma'. Type-only imports
- * (`import type`) are erased by the TS compiler and are fine; the `figma` default
- * import is the one supported module (no bundling in Phase 1). This runs BEFORE
- * the `codeProperties` skip guard so an unsupported import is always a hard error,
- * even in a file that would otherwise be skipped.
+ * Validates a template entry's imports: only the default `figma` import,
+ * type-only imports and relative helper imports are allowed. Returns whether
+ * the entry imports helpers, so the caller knows whether to bundle.
  */
-function assertOnlyFigmaImports(filePath, fileContent) {
-    // Ignore the supported `import figma from 'figma'` form before scanning.
-    const withoutFigmaImport = fileContent.replace(figmaImportRegex, '');
-    const importRegex = /^import\s+(?!type\s)/m;
-    if (importRegex.test(withoutFigmaImport)) {
-        const match = withoutFigmaImport.match(/^(import\s+.+)$/m);
-        const importLine = match ? match[1] : 'import ...';
-        throw new Error(`TypeScript template files only support importing from 'figma'.\n` +
-            `Found in ${filePath}:\n` +
-            `  ${importLine}\n\n` +
-            `Use "const figma = require('figma')" or "import figma from 'figma'" to access the Figma API.\n` +
-            `Other module imports will be supported in a future version.`);
+function validateTypeScriptTemplateImports(filePath, fileContent) {
+    const sourceFile = typescript_1.default.createSourceFile(filePath, fileContent, typescript_1.default.ScriptTarget.Latest, true);
+    let hasRelativeHelperImports = false;
+    for (const statement of sourceFile.statements) {
+        if (typescript_1.default.isImportDeclaration(statement)) {
+            if (statement.importClause?.isTypeOnly) {
+                continue;
+            }
+            const moduleSpecifierText = typescript_1.default.isStringLiteral(statement.moduleSpecifier)
+                ? statement.moduleSpecifier.text
+                : '';
+            const importLine = statement.getText(sourceFile).split('\n')[0]?.trim() ?? 'import ...';
+            if (moduleSpecifierText === 'figma') {
+                const hasDefaultImport = !!statement.importClause?.name;
+                const hasNamedOrNamespaceImport = !!statement.importClause?.namedBindings;
+                if (!hasDefaultImport || hasNamedOrNamespaceImport) {
+                    throw (0, raw_template_bundler_1.unsupportedImportError)(filePath, importLine);
+                }
+                continue;
+            }
+            if ((0, raw_template_bundler_1.isRelativeImportPath)(moduleSpecifierText)) {
+                hasRelativeHelperImports = true;
+                continue;
+            }
+            throw (0, raw_template_bundler_1.unsupportedImportError)(filePath, importLine);
+        }
+        // Re-exports aren't supported: the runtime only reads the default export.
+        if (typescript_1.default.isExportDeclaration(statement) && statement.moduleSpecifier && !statement.isTypeOnly) {
+            const exportLine = statement.getText(sourceFile).split('\n')[0]?.trim() ?? 'export ...';
+            throw new Error(`Template files do not support re-exports ('export ... from ...').\n` +
+                `Found in ${filePath}:\n` +
+                `  ${exportLine}\n\n` +
+                `Import the helper instead (for example: import { helper } from './helpers').`);
+        }
     }
+    // `require` is for the Figma API only: a pure ESM graph is what lets the
+    // bundler emit a flat, tree-shaken template. Walking the AST (not the raw
+    // text) keeps a `require(...)` inside an emitted snippet from matching.
+    const visitRequire = (node) => {
+        const request = (0, raw_template_bundler_1.getRequireCallRequest)(node);
+        if (request && request !== 'figma') {
+            throw (0, raw_template_bundler_1.isRelativeImportPath)(request)
+                ? (0, raw_template_bundler_1.relativeRequireError)(filePath, request)
+                : (0, raw_template_bundler_1.unsupportedImportError)(filePath, `require('${request}')`);
+        }
+        typescript_1.default.forEachChild(node, visitRequire);
+    };
+    visitRequire(sourceFile);
+    return { hasRelativeHelperImports };
 }
 function transpileTypeScriptTemplate(filePath, fileContent) {
     if (figmaImportRegex.test(fileContent)) {
@@ -115,17 +166,17 @@ function extractMetadataFields(fileContent) {
     }
     return { fields, templateStartLine };
 }
-function parseRawFile(filePath, label, config, dir, batchOverrides) {
+async function parseRawFile(filePath, label, config, dir, batchOverrides) {
     let fileContent = fs_1.default.readFileSync(filePath, 'utf-8');
+    let shouldBundleTypeScriptTemplate = false;
     // Extract metadata fields BEFORE transpilation to avoid losing comments
     // that appear before type-only imports (which TypeScript erases)
     const { fields, templateStartLine } = extractMetadataFields(fileContent);
     const figmaUrl = batchOverrides?.url || fields.url;
-    // An unsupported (non-figma) import is always a hard error, even in a file that
-    // would otherwise be skipped as a `codeProperties` file below. Checked first so
-    // an import mistake is never silently swallowed by the skip guard.
-    if (filePath.endsWith('.ts')) {
-        assertOnlyFigmaImports(filePath, fileContent);
+    // Validate imports first, before the `codeProperties` skip guard below, so an
+    // unsupported import is always a hard error rather than silently swallowed.
+    if (isRawTemplateSourceFile(filePath)) {
+        shouldBundleTypeScriptTemplate = validateTypeScriptTemplateImports(filePath, fileContent).hasRelativeHelperImports;
     }
     // A file with no // url= directive that contains the string `codeProperties`
     // is not Code Connect (e.g. Make's code component property definitions). Skip
@@ -134,7 +185,14 @@ function parseRawFile(filePath, label, config, dir, batchOverrides) {
     if (!figmaUrl && fileContent.includes('codeProperties')) {
         throw new CodePropertiesError(`Skipping ${filePath}: file has no // url= directive and contains "codeProperties", so it is not treated as a Code Connect file.`);
     }
-    if (filePath.endsWith('.ts')) {
+    // Bundle when helpers are present; otherwise transpile TS and emit JS verbatim.
+    // Bundling takes some extra time.
+    if (shouldBundleTypeScriptTemplate) {
+        // Confining resolution to the project dir
+        const projectRoot = dir ? path_1.default.resolve(dir) : path_1.default.dirname(path_1.default.resolve(filePath));
+        fileContent = await (0, raw_template_bundler_1.bundleTemplateWithHelpers)(filePath, projectRoot);
+    }
+    else if (filePath.endsWith('.ts')) {
         fileContent = transpileTypeScriptTemplate(filePath, fileContent);
     }
     // For batch templates, metadata comes from the batch entry instead of comments
@@ -169,6 +227,9 @@ function parseRawFile(filePath, label, config, dir, batchOverrides) {
     if (batchOverrides) {
         template = `globalThis['__FIGMA_BATCH'] = ${JSON.stringify(batchOverrides.batchData)}\n${template}`;
     }
+    // Check the final template (incl. any bundled helpers and batch data) against
+    // the backend's size cap so an oversized template fails here, not on upload.
+    assertTemplateWithinSizeLimit(filePath, template);
     // Apply documentUrlSubstitutions if provided
     if (config?.documentUrlSubstitutions) {
         figmaNodeUrl = (0, helpers_1.applyDocumentUrlSubstitutions)(figmaNodeUrl, config.documentUrlSubstitutions);