app-builder-lib 27.0.0-alpha.8 → 27.0.0-alpha.9

package/dist/util/config/legacyConfigGuard.js

@@ -0,0 +1,187 @@
+import { InvalidConfigurationError, log } from "builder-util";
+import { BREAKING_CHANGES_URL, formatLegacyOptionMessage, RESOLVED_LEGACY_CONFIG_OPTIONS } from "./legacyOptions.js";
+/**
+ * Build-time guard for configurations still written against v26.
+ *
+ * Almost every removed key is already rejected by `scheme.json` (`additionalProperties: false`), but
+ * ajv can only say "has an unknown property 'identity'" — it cannot say the option moved to
+ * `mac.sign.identity`. This pass runs *before* schema validation so the targeted message wins, and it
+ * aggregates every legacy key into a single error: a config with a dozen moved mac options should
+ * not take a dozen build attempts to fix.
+ *
+ * Nothing here rejects a value a valid v27 config can contain — every guarded path is covered by a
+ * test asserting the v27 schema rejects it too.
+ */
+const PLATFORMS_WITH_PUBLISH = ["mac", "win", "linux"];
+/** v26 `snap` options that belong under the base-named sub-key in v27, not directly on `snapcraft`. */
+const SNAPCRAFT_BASE_LEVEL_KEYS = new Set([
+    "confinement",
+    "grade",
+    "stagePackages",
+    "buildPackages",
+    "plugs",
+    "slots",
+    "after",
+    "environment",
+    "hooks",
+    "layout",
+    "appPartStage",
+    "assumes",
+    "autoStart",
+    "summary",
+    "title",
+    "compression",
+    "allowNativeWayland",
+    "useTemplateApp",
+]);
+const SNAPCRAFT_BASES = ["core18", "core20", "core22", "core24", "custom"];
+function docLink(anchor) {
+    return `  ${BREAKING_CHANGES_URL}#${anchor}`;
+}
+function isPlainObject(value) {
+    return value != null && typeof value === "object" && !Array.isArray(value);
+}
+/** Resolves `path` against `config`, returning the holding object or null when any segment is missing. */
+function resolveParent(config, path) {
+    let node = config;
+    for (const segment of path) {
+        const next = node[segment];
+        if (!isPlainObject(next)) {
+            return null;
+        }
+        node = next;
+    }
+    return node;
+}
+/** Collects the legacy keys present anywhere in the config, using the shared mapping table. */
+function collectLegacyKeys(config, errors, warnings) {
+    for (const option of RESOLVED_LEGACY_CONFIG_OPTIONS) {
+        const parent = resolveParent(config, option.parentPath);
+        if (parent == null || !(option.key in parent)) {
+            continue;
+        }
+        const message = formatLegacyOptionMessage(option);
+        if (option.severity === "error") {
+            errors.push(message);
+        }
+        else {
+            warnings.push(message);
+        }
+    }
+}
+/**
+ * `mac.sign` is a single union in v27, so a custom signer and an options bag can no longer coexist.
+ * The sibling fields are already reported by `collectLegacyKeys`; this adds the union explanation so
+ * the user knows the two forms are mutually exclusive rather than assuming a mechanical move works.
+ */
+function checkMacCustomSigner(config, errors) {
+    for (const platform of ["mac", "mas", "masDev"]) {
+        const platformConfig = config[platform];
+        if (!isPlainObject(platformConfig)) {
+            continue;
+        }
+        const sign = platformConfig.sign;
+        if (typeof sign !== "string" && typeof sign !== "function") {
+            continue;
+        }
+        const legacySiblings = RESOLVED_LEGACY_CONFIG_OPTIONS.filter(o => o.parentPath.length === 1 && o.parentPath[0] === platform && o.key in platformConfig).map(o => o.key);
+        if (legacySiblings.length === 0) {
+            continue;
+        }
+        errors.push(`\`${platform}.sign\` is a custom signing function or module path, and \`${platform}\` also sets [${legacySiblings.join(", ")}].\n` +
+            `  In v27 \`${platform}.sign\` is a single union — a custom signer cannot carry signing options alongside it.\n` +
+            `  Either keep the custom signer and read those options inside it, or drop it and use an ElectronSignOptions object.\n` +
+            docLink("macos-signing-macsign"));
+    }
+}
+/**
+ * `win.sign` is a discriminated union in v27. Without `type`, ajv reports one
+ * "unknown property" error per union branch and never mentions the missing discriminator.
+ */
+function checkWinSignDiscriminator(config, errors) {
+    const sign = config.win?.sign;
+    if (!isPlainObject(sign) || "type" in sign) {
+        return;
+    }
+    errors.push("`win.sign` is missing its `type` discriminator.\n" +
+        '  v27 types `win.sign` as a union: `type: "signtool" | "hsm" | "pkcs11" | "azure"`.\n' +
+        '  A config migrated from `win.signtoolOptions` needs `type: "signtool"`; one from `win.azureSignOptions` needs `type: "azure"`.\n' +
+        docLink("windows-signing-winsign"));
+}
+/**
+ * `snapcraft.base` is required, but because `snapcraft` is `anyOf[SnapcraftOptions, null]` the ajv
+ * output collapses to "configuration.snapcraft should be one of these: null" — which reads as an
+ * instruction to null out the config.
+ */
+function checkSnapcraftShape(config, errors) {
+    const snapcraft = config.snapcraft;
+    if (!isPlainObject(snapcraft)) {
+        return;
+    }
+    if (!("base" in snapcraft)) {
+        errors.push("`snapcraft` is missing the required `base` field.\n" +
+            `  Set it to one of ${SNAPCRAFT_BASES.map(b => `"${b}"`).join(" | ")} and nest that base's options under a matching sub-key, ` +
+            'e.g. `{ "snapcraft": { "base": "core22", "core22": { … } } }`.\n' +
+            docLink("snap-snapcraft"));
+        return;
+    }
+    const flatKeys = Object.keys(snapcraft).filter(k => SNAPCRAFT_BASE_LEVEL_KEYS.has(k));
+    if (flatKeys.length > 0) {
+        errors.push(`\`snapcraft\` sets [${flatKeys.join(", ")}] directly, but in v27 those belong under the base-named sub-key.\n` +
+            `  Move them under \`snapcraft.${snapcraft.base}\`, e.g. \`{ "snapcraft": { "base": "${snapcraft.base}", "${snapcraft.base}": { "${flatKeys[0]}": … } } }\`.\n` +
+            docLink("snap-snapcraft"));
+    }
+}
+/**
+ * `vPrefixedTagName` was removed from GitHub publish options only — GitLab still supports it, so the
+ * check has to discriminate on `provider` rather than on the key name.
+ */
+function checkPublishEntries(config, errors) {
+    const check = (value, label) => {
+        if (value == null) {
+            return;
+        }
+        for (const entry of Array.isArray(value) ? value : [value]) {
+            if (!isPlainObject(entry) || entry.provider !== "github" || !("vPrefixedTagName" in entry)) {
+                continue;
+            }
+            const suggested = entry.vPrefixedTagName === false ? '""' : '"v"';
+            errors.push(`\`${label}.vPrefixedTagName\` was removed from the GitHub publish options in v27.\n` +
+                `  Use \`tagNamePrefix: ${suggested}\` instead (it defaults to "v", so you can drop the key entirely to keep the default).\n` +
+                "  This applies to GitHub only — GitLab's `vPrefixedTagName` is unchanged.\n" +
+                "  Run `electron-builder migrate-schema` to update your configuration automatically.\n" +
+                docLink("githuboptions-gitlaboptions-vprefixedtagname"));
+        }
+    };
+    check(config.publish, "publish");
+    for (const platform of PLATFORMS_WITH_PUBLISH) {
+        check(config[platform]?.publish, `${platform}.publish`);
+    }
+}
+/**
+ * Throws a single aggregated {@link InvalidConfigurationError} naming every v26 option found, and
+ * warns about the ones that are merely discouraged. Runs before schema validation.
+ */
+export function checkLegacyConfiguration(config) {
+    const raw = config;
+    const errors = [];
+    const warnings = [];
+    collectLegacyKeys(raw, errors, warnings);
+    checkMacCustomSigner(raw, errors);
+    checkWinSignDiscriminator(raw, errors);
+    checkSnapcraftShape(raw, errors);
+    checkPublishEntries(raw, errors);
+    for (const warning of warnings) {
+        log.warn(warning);
+    }
+    if (errors.length === 0) {
+        return;
+    }
+    const header = errors.length === 1
+        ? "Your configuration uses an option that was removed in electron-builder v27:"
+        : `Your configuration uses ${errors.length} options that were removed in electron-builder v27:`;
+    const message = [header, "", ...errors.map(e => `• ${e}`), "", `Full list of breaking changes: ${BREAKING_CHANGES_URL}`].join("\n");
+    log.error(null, "invalid configuration");
+    throw new InvalidConfigurationError(message);
+}
+//# sourceMappingURL=legacyConfigGuard.js.map

package/dist/util/config/legacyConfigGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacyConfigGuard.js","sourceRoot":"","sources":["../../../src/util/config/legacyConfigGuard.ts"],"names":[],"mappings":"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","sourcesContent":["import { InvalidConfigurationError, log } from \"builder-util\"\nimport { Configuration } from \"../../configuration.js\"\nimport { BREAKING_CHANGES_URL, formatLegacyOptionMessage, RESOLVED_LEGACY_CONFIG_OPTIONS } from \"./legacyOptions.js\"\n\n/**\n * Build-time guard for configurations still written against v26.\n *\n * Almost every removed key is already rejected by `scheme.json` (`additionalProperties: false`), but\n * ajv can only say \"has an unknown property 'identity'\" — it cannot say the option moved to\n * `mac.sign.identity`. This pass runs *before* schema validation so the targeted message wins, and it\n * aggregates every legacy key into a single error: a config with a dozen moved mac options should\n * not take a dozen build attempts to fix.\n *\n * Nothing here rejects a value a valid v27 config can contain — every guarded path is covered by a\n * test asserting the v27 schema rejects it too.\n */\n\nconst PLATFORMS_WITH_PUBLISH = [\"mac\", \"win\", \"linux\"] as const\n\n/** v26 `snap` options that belong under the base-named sub-key in v27, not directly on `snapcraft`. */\nconst SNAPCRAFT_BASE_LEVEL_KEYS = new Set([\n  \"confinement\",\n  \"grade\",\n  \"stagePackages\",\n  \"buildPackages\",\n  \"plugs\",\n  \"slots\",\n  \"after\",\n  \"environment\",\n  \"hooks\",\n  \"layout\",\n  \"appPartStage\",\n  \"assumes\",\n  \"autoStart\",\n  \"summary\",\n  \"title\",\n  \"compression\",\n  \"allowNativeWayland\",\n  \"useTemplateApp\",\n])\n\nconst SNAPCRAFT_BASES = [\"core18\", \"core20\", \"core22\", \"core24\", \"custom\"]\n\nfunction docLink(anchor: string): string {\n  return `  ${BREAKING_CHANGES_URL}#${anchor}`\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, any> {\n  return value != null && typeof value === \"object\" && !Array.isArray(value)\n}\n\n/** Resolves `path` against `config`, returning the holding object or null when any segment is missing. */\nfunction resolveParent(config: Record<string, any>, path: readonly string[]): Record<string, any> | null {\n  let node: Record<string, any> = config\n  for (const segment of path) {\n    const next = node[segment]\n    if (!isPlainObject(next)) {\n      return null\n    }\n    node = next\n  }\n  return node\n}\n\n/** Collects the legacy keys present anywhere in the config, using the shared mapping table. */\nfunction collectLegacyKeys(config: Record<string, any>, errors: string[], warnings: string[]): void {\n  for (const option of RESOLVED_LEGACY_CONFIG_OPTIONS) {\n    const parent = resolveParent(config, option.parentPath)\n    if (parent == null || !(option.key in parent)) {\n      continue\n    }\n    const message = formatLegacyOptionMessage(option)\n    if (option.severity === \"error\") {\n      errors.push(message)\n    } else {\n      warnings.push(message)\n    }\n  }\n}\n\n/**\n * `mac.sign` is a single union in v27, so a custom signer and an options bag can no longer coexist.\n * The sibling fields are already reported by `collectLegacyKeys`; this adds the union explanation so\n * the user knows the two forms are mutually exclusive rather than assuming a mechanical move works.\n */\nfunction checkMacCustomSigner(config: Record<string, any>, errors: string[]): void {\n  for (const platform of [\"mac\", \"mas\", \"masDev\"] as const) {\n    const platformConfig = config[platform]\n    if (!isPlainObject(platformConfig)) {\n      continue\n    }\n    const sign = platformConfig.sign\n    if (typeof sign !== \"string\" && typeof sign !== \"function\") {\n      continue\n    }\n    const legacySiblings = RESOLVED_LEGACY_CONFIG_OPTIONS.filter(o => o.parentPath.length === 1 && o.parentPath[0] === platform && o.key in platformConfig).map(o => o.key)\n    if (legacySiblings.length === 0) {\n      continue\n    }\n    errors.push(\n      `\\`${platform}.sign\\` is a custom signing function or module path, and \\`${platform}\\` also sets [${legacySiblings.join(\", \")}].\\n` +\n        `  In v27 \\`${platform}.sign\\` is a single union — a custom signer cannot carry signing options alongside it.\\n` +\n        `  Either keep the custom signer and read those options inside it, or drop it and use an ElectronSignOptions object.\\n` +\n        docLink(\"macos-signing-macsign\")\n    )\n  }\n}\n\n/**\n * `win.sign` is a discriminated union in v27. Without `type`, ajv reports one\n * \"unknown property\" error per union branch and never mentions the missing discriminator.\n */\nfunction checkWinSignDiscriminator(config: Record<string, any>, errors: string[]): void {\n  const sign = config.win?.sign\n  if (!isPlainObject(sign) || \"type\" in sign) {\n    return\n  }\n  errors.push(\n    \"`win.sign` is missing its `type` discriminator.\\n\" +\n      '  v27 types `win.sign` as a union: `type: \"signtool\" | \"hsm\" | \"pkcs11\" | \"azure\"`.\\n' +\n      '  A config migrated from `win.signtoolOptions` needs `type: \"signtool\"`; one from `win.azureSignOptions` needs `type: \"azure\"`.\\n' +\n      docLink(\"windows-signing-winsign\")\n  )\n}\n\n/**\n * `snapcraft.base` is required, but because `snapcraft` is `anyOf[SnapcraftOptions, null]` the ajv\n * output collapses to \"configuration.snapcraft should be one of these: null\" — which reads as an\n * instruction to null out the config.\n */\nfunction checkSnapcraftShape(config: Record<string, any>, errors: string[]): void {\n  const snapcraft = config.snapcraft\n  if (!isPlainObject(snapcraft)) {\n    return\n  }\n  if (!(\"base\" in snapcraft)) {\n    errors.push(\n      \"`snapcraft` is missing the required `base` field.\\n\" +\n        `  Set it to one of ${SNAPCRAFT_BASES.map(b => `\"${b}\"`).join(\" | \")} and nest that base's options under a matching sub-key, ` +\n        'e.g. `{ \"snapcraft\": { \"base\": \"core22\", \"core22\": { … } } }`.\\n' +\n        docLink(\"snap-snapcraft\")\n    )\n    return\n  }\n  const flatKeys = Object.keys(snapcraft).filter(k => SNAPCRAFT_BASE_LEVEL_KEYS.has(k))\n  if (flatKeys.length > 0) {\n    errors.push(\n      `\\`snapcraft\\` sets [${flatKeys.join(\", \")}] directly, but in v27 those belong under the base-named sub-key.\\n` +\n        `  Move them under \\`snapcraft.${snapcraft.base}\\`, e.g. \\`{ \"snapcraft\": { \"base\": \"${snapcraft.base}\", \"${snapcraft.base}\": { \"${flatKeys[0]}\": … } } }\\`.\\n` +\n        docLink(\"snap-snapcraft\")\n    )\n  }\n}\n\n/**\n * `vPrefixedTagName` was removed from GitHub publish options only — GitLab still supports it, so the\n * check has to discriminate on `provider` rather than on the key name.\n */\nfunction checkPublishEntries(config: Record<string, any>, errors: string[]): void {\n  const check = (value: unknown, label: string) => {\n    if (value == null) {\n      return\n    }\n    for (const entry of Array.isArray(value) ? value : [value]) {\n      if (!isPlainObject(entry) || entry.provider !== \"github\" || !(\"vPrefixedTagName\" in entry)) {\n        continue\n      }\n      const suggested = entry.vPrefixedTagName === false ? '\"\"' : '\"v\"'\n      errors.push(\n        `\\`${label}.vPrefixedTagName\\` was removed from the GitHub publish options in v27.\\n` +\n          `  Use \\`tagNamePrefix: ${suggested}\\` instead (it defaults to \"v\", so you can drop the key entirely to keep the default).\\n` +\n          \"  This applies to GitHub only — GitLab's `vPrefixedTagName` is unchanged.\\n\" +\n          \"  Run `electron-builder migrate-schema` to update your configuration automatically.\\n\" +\n          docLink(\"githuboptions-gitlaboptions-vprefixedtagname\")\n      )\n    }\n  }\n  check(config.publish, \"publish\")\n  for (const platform of PLATFORMS_WITH_PUBLISH) {\n    check(config[platform]?.publish, `${platform}.publish`)\n  }\n}\n\n/**\n * Throws a single aggregated {@link InvalidConfigurationError} naming every v26 option found, and\n * warns about the ones that are merely discouraged. Runs before schema validation.\n */\nexport function checkLegacyConfiguration(config: Configuration): void {\n  const raw = config as unknown as Record<string, any>\n  const errors: string[] = []\n  const warnings: string[] = []\n\n  collectLegacyKeys(raw, errors, warnings)\n  checkMacCustomSigner(raw, errors)\n  checkWinSignDiscriminator(raw, errors)\n  checkSnapcraftShape(raw, errors)\n  checkPublishEntries(raw, errors)\n\n  for (const warning of warnings) {\n    log.warn(warning)\n  }\n\n  if (errors.length === 0) {\n    return\n  }\n\n  const header =\n    errors.length === 1\n      ? \"Your configuration uses an option that was removed in electron-builder v27:\"\n      : `Your configuration uses ${errors.length} options that were removed in electron-builder v27:`\n  const message = [header, \"\", ...errors.map(e => `• ${e}`), \"\", `Full list of breaking changes: ${BREAKING_CHANGES_URL}`].join(\"\\n\")\n  log.error(null, \"invalid configuration\")\n  throw new InvalidConfigurationError(message)\n}\n"]}

package/dist/util/config/legacyOptions.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Single source of truth for the v26 → v27 configuration migration.
+ *
+ * Two consumers read this table and must never drift apart:
+ *  - `checkLegacyConfiguration` (this package) — the build-time guard that tells a user who upgraded
+ *    without reading the migration guide exactly which key moved where.
+ *  - `electron-builder migrate-schema` (the `electron-builder` package) — the opt-in rewriter.
+ *
+ * The migrator lives in a package that depends on this one, so the table has to live here for both
+ * to share it. Keeping the field lists in one place is not cosmetic: `gatekeeperAssess` was moved
+ * into `mac.sign` by the migrator while the schema rejected it there, producing configs that failed
+ * validation on the next build.
+ */
+/** macOS signing fields that moved from the platform root into the `sign` (ElectronSignOptions) bag. */
+export declare const MAC_SIGN_FIELDS: readonly ["identity", "entitlements", "entitlementsInherit", "entitlementsLoginHelper", "provisioningProfile", "type", "binaries", "requirements", "hardenedRuntime", "strictVerify", "preAutoEntitlements", "timestamp", "additionalArguments"];
+/**
+ * macOS signing fields that were removed outright rather than moved under `sign`.
+ * `@electron/osx-sign` 2.x dropped the `spctl --assess` step, so there is no `sign.gatekeeperAssess`
+ * to migrate to — `ElectronSignOptions` omits it and the schema rejects it.
+ */
+export declare const MAC_SIGN_REMOVED_FIELDS: readonly ["gatekeeperAssess"];
+/** Universal-build fields that moved from the platform root into the `universal` bag. */
+export declare const MAC_UNIVERSAL_FIELDS: readonly ["mergeASARs", "singleArchFiles", "x64ArchFiles"];
+/**
+ * Azure Trusted Signing typed fields in v27 (everything else is an extra key → `additionalMetadata`).
+ * `type` is included so it is not mistakenly moved to `additionalMetadata` if already present.
+ */
+export declare const AZURE_KNOWN_FIELDS: Set<string>;
+/** `electronDownload` fields with no equivalent in the v27 `ElectronGetOptions` (@electron/get v5) shape. */
+export declare const ELECTRON_DOWNLOAD_DROPPED: readonly ["cache", "customDir", "customFilename", "strictSSL", "platform", "arch", "version", "force"];
+/** Platform keys that accept the macOS signing/universal options. */
+export declare const MAC_PLATFORM_KEYS: readonly ["mac", "mas", "masDev"];
+/** Every platform key that accepted the shared per-platform options in v26. */
+export declare const ALL_PLATFORM_KEYS: readonly ["mac", "mas", "masDev", "win", "linux"];
+export declare const BREAKING_CHANGES_URL = "https://www.electron.build/docs/migration/v27-breaking-changes";
+export interface LegacyConfigOption {
+    /** The removed key itself. */
+    readonly key: string;
+    /** Path to the object holding `key`. Empty = the configuration root. */
+    readonly parent?: readonly string[];
+    /**
+     * When set, `parent` is ignored and one entry is generated per platform key:
+     * `"mac"` → mac/mas/masDev, `"all"` → those plus win/linux.
+     */
+    readonly scope?: "mac" | "all";
+    /** The v27 form, or `null` when the option was removed with no replacement. */
+    readonly replacement: string | null;
+    /** True when `electron-builder migrate-schema` rewrites this automatically. */
+    readonly autoMigrated: boolean;
+    readonly severity: "error" | "warn";
+    /** Extra sentence appended to the message — inverted polarity, lost behaviour, etc. */
+    readonly detail?: string;
+    /** Anchor within the breaking-changes page. */
+    readonly anchor: string;
+}
+export declare const LEGACY_CONFIG_OPTIONS: readonly LegacyConfigOption[];
+/** A `LegacyConfigOption` with its `scope` expanded to a concrete parent path. */
+export interface ResolvedLegacyConfigOption extends LegacyConfigOption {
+    /** Concrete path of the object holding `key`. */
+    readonly parentPath: readonly string[];
+    /** Dot-joined `parentPath` + `key`, as it appears in a user's config. */
+    readonly fullPath: string;
+}
+/** `LEGACY_CONFIG_OPTIONS` with every `scope` expanded into concrete paths. */
+export declare const RESOLVED_LEGACY_CONFIG_OPTIONS: readonly ResolvedLegacyConfigOption[];
+/**
+ * Renders the user-facing message for a single legacy option.
+ *
+ * A scoped option's `replacement` is relative to its platform key (`sign.identity`), so it is
+ * prefixed with the resolved parent to read as the user wrote it (`mac.sign.identity`).
+ */
+export declare function formatLegacyOptionMessage(option: ResolvedLegacyConfigOption): string;
+//# sourceMappingURL=legacyOptions.d.ts.map

package/dist/util/config/legacyOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacyOptions.d.ts","sourceRoot":"","sources":["../../../src/util/config/legacyOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,wGAAwG;AACxG,eAAO,MAAM,eAAe,kPAclB,CAAA;AAEV;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,+BAAgC,CAAA;AAEpE,yFAAyF;AACzF,eAAO,MAAM,oBAAoB,4DAA6D,CAAA;AAE9F;;;GAGG;AACH,eAAO,MAAM,kBAAkB,aAU7B,CAAA;AAEF,6GAA6G;AAC7G,eAAO,MAAM,yBAAyB,wGAAyG,CAAA;AAE/I,qEAAqE;AACrE,eAAO,MAAM,iBAAiB,mCAAoC,CAAA;AAElE,+EAA+E;AAC/E,eAAO,MAAM,iBAAiB,mDAAoD,CAAA;AAElF,eAAO,MAAM,oBAAoB,mEAAmE,CAAA;AAEpG,MAAM,WAAW,kBAAkB;IACjC,8BAA8B;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,KAAK,CAAA;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAA;IACnC,uFAAuF;IACvF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAQD,eAAO,MAAM,qBAAqB,EAAE,SAAS,kBAAkB,EAuR9D,CAAA;AAED,kFAAkF;AAClF,MAAM,WAAW,0BAA2B,SAAQ,kBAAkB;IACpE,iDAAiD;IACjD,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;IACtC,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAcD,+EAA+E;AAC/E,eAAO,MAAM,8BAA8B,EAAE,SAAS,0BAA0B,EAAmC,CAAA;AAEnH;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,0BAA0B,GAAG,MAAM,CAmBpF"}