@guideshot/core 0.1.0

package/dist/index.js

@@ -0,0 +1,1474 @@
+// src/index.ts
+import {
+  SCHEMA_VERSION as SCHEMA_VERSION2,
+  PublicManifestSchema as PublicManifestSchema2,
+  RecipeSchema as RecipeSchema2
+} from "@guideshot/schema";
+
+// src/canonical.ts
+import { createHash } from "crypto";
+
+// src/diagnostics.ts
+var DIAGNOSTIC_CODES = [
+  "RECIPE_SCHEMA_INVALID",
+  "EXTENSION_NOT_REGISTERED",
+  "VARIABLE_UNRESOLVED",
+  "SERVER_NOT_READY",
+  "ORIGIN_NOT_ALLOWED",
+  "SCENARIO_FAILED",
+  "NAVIGATION_FAILED",
+  "TARGET_NOT_FOUND",
+  "TARGET_NOT_UNIQUE",
+  "TARGET_NOT_VISIBLE",
+  "EXPECTATION_FAILED",
+  "LAYOUT_UNSTABLE",
+  "ANNOTATION_LAYOUT_FAILED",
+  "PRIVACY_POLICY_FAILED",
+  "CAPTURE_FAILED",
+  "COMPOSITION_FAILED",
+  "OUTPUT_COLLISION",
+  "MANIFEST_INVALID",
+  "OUTPUT_STALE"
+];
+var GuideShotError = class extends Error {
+  name = "GuideShotError";
+  code;
+  hint;
+  recipeId;
+  jobKey;
+  location;
+  details;
+  constructor(code, message, options = {}) {
+    super(
+      message,
+      options.cause === void 0 ? void 0 : { cause: options.cause }
+    );
+    this.code = code;
+    this.hint = options.hint;
+    this.recipeId = options.recipeId;
+    this.jobKey = options.jobKey;
+    this.location = options.location;
+    this.details = options.details;
+  }
+  toDiagnostic() {
+    return {
+      code: this.code,
+      severity: "error",
+      message: this.message,
+      ...this.hint === void 0 ? {} : { hint: this.hint },
+      ...this.recipeId === void 0 ? {} : { recipeId: this.recipeId },
+      ...this.jobKey === void 0 ? {} : { jobKey: this.jobKey },
+      ...this.location === void 0 ? {} : { location: this.location },
+      ...this.details === void 0 ? {} : { details: this.details }
+    };
+  }
+};
+function isGuideShotError(error) {
+  return error instanceof GuideShotError;
+}
+function diagnosticFromUnknown(error, fallbackCode) {
+  if (isGuideShotError(error)) {
+    return error.toDiagnostic();
+  }
+  return {
+    code: fallbackCode,
+    severity: "error",
+    message: error instanceof Error ? error.message : String(error)
+  };
+}
+
+// src/canonical.ts
+function canonicalSerialize(value) {
+  return serialize(value, /* @__PURE__ */ new Set());
+}
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+function hashCanonical(value) {
+  return sha256(canonicalSerialize(value));
+}
+function createCaptureHash(intent) {
+  return hashCanonical({ kind: "capture", version: 1, intent });
+}
+function createCompositionHash(intent) {
+  return hashCanonical({ kind: "composition", version: 1, intent });
+}
+function serialize(value, ancestors) {
+  if (value === null || typeof value === "boolean" || typeof value === "string") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw invalidCanonicalValue("non-finite number");
+    }
+    return JSON.stringify(Object.is(value, -0) ? 0 : value);
+  }
+  if (Array.isArray(value)) {
+    guardCycle(value, ancestors);
+    const result = `[${value.map((entry) => serialize(entry, ancestors)).join(",")}]`;
+    ancestors.delete(value);
+    return result;
+  }
+  if (isPlainObject(value)) {
+    guardCycle(value, ancestors);
+    const entries = Object.entries(value).filter(([, entry]) => entry !== void 0).sort(([left], [right]) => compareStrings(left, right)).map(
+      ([key, entry]) => `${JSON.stringify(key)}:${serialize(entry, ancestors)}`
+    );
+    ancestors.delete(value);
+    return `{${entries.join(",")}}`;
+  }
+  throw invalidCanonicalValue(
+    value === void 0 ? "undefined array/root value" : typeof value
+  );
+}
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function guardCycle(value, ancestors) {
+  if (ancestors.has(value)) {
+    throw invalidCanonicalValue("cyclic object");
+  }
+  ancestors.add(value);
+}
+function invalidCanonicalValue(kind) {
+  return new GuideShotError(
+    "RECIPE_SCHEMA_INVALID",
+    `Cannot canonically serialize ${kind}.`
+  );
+}
+function compareStrings(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+// src/contracts.ts
+function defineConfig(config) {
+  return config;
+}
+function defineDimension(definition) {
+  return definition;
+}
+function defineScenario(definition) {
+  return definition;
+}
+
+// src/discovery.ts
+import { readFile } from "fs/promises";
+import path from "path";
+import fg from "fast-glob";
+
+// src/validation.ts
+import Ajv2020Import from "ajv/dist/2020.js";
+import addFormatsImport from "ajv-formats";
+import {
+  PublicManifestSchema,
+  RecipeSchema
+} from "@guideshot/schema";
+import {
+  parse as parseJsonc,
+  printParseErrorCode
+} from "jsonc-parser";
+var Ajv2020 = Ajv2020Import.default;
+var addFormats = addFormatsImport.default;
+var ajv = addFormats(
+  new Ajv2020({
+    allErrors: true,
+    allowUnionTypes: true,
+    strict: true
+  })
+);
+var recipeValidator = ajv.compile(RecipeSchema);
+var manifestValidator = ajv.compile(PublicManifestSchema);
+var extensionValidators = /* @__PURE__ */ new WeakMap();
+function parseRecipe(source, options = {}) {
+  const errors = [];
+  const format = options.format ?? inferFormat(options.file);
+  const value = parseJsonc(source, errors, {
+    allowEmptyContent: false,
+    allowTrailingComma: format === "jsonc",
+    disallowComments: format === "json"
+  });
+  if (errors.length > 0) {
+    const first = errors[0];
+    if (first === void 0) {
+      throw new GuideShotError(
+        "RECIPE_SCHEMA_INVALID",
+        "Recipe is not valid JSON."
+      );
+    }
+    const position = positionAt(source, first.offset);
+    throw new GuideShotError(
+      "RECIPE_SCHEMA_INVALID",
+      `Recipe contains invalid ${format.toUpperCase()}: ${printParseErrorCode(first.error)}.`,
+      {
+        location: compactLocation({
+          ...options.file === void 0 ? {} : { file: options.file },
+          line: position.line,
+          column: position.column
+        })
+      }
+    );
+  }
+  return validateRecipe(value, options.file);
+}
+function validateRecipe(value, file) {
+  if (!recipeValidator(value)) {
+    throw schemaError("Recipe", recipeValidator.errors, file);
+  }
+  return value;
+}
+function validateManifest(value, file) {
+  if (!manifestValidator(value)) {
+    throw new GuideShotError(
+      "MANIFEST_INVALID",
+      formatValidationMessage("Manifest", manifestValidator.errors),
+      {
+        ...file === void 0 ? {} : { location: { file } },
+        details: validationDetails(manifestValidator.errors)
+      }
+    );
+  }
+  return value;
+}
+function validateConfig(config) {
+  if (config.recipes.length === 0) {
+    throw new GuideShotError(
+      "RECIPE_SCHEMA_INVALID",
+      "Configuration must include at least one recipe pattern."
+    );
+  }
+  if (Object.keys(config.profiles).length === 0) {
+    throw new GuideShotError(
+      "EXTENSION_NOT_REGISTERED",
+      "Configuration must register at least one capture profile."
+    );
+  }
+  for (const [name, profile] of Object.entries(config.profiles)) {
+    if (!Number.isInteger(profile.viewport.width) || profile.viewport.width <= 0 || !Number.isInteger(profile.viewport.height) || profile.viewport.height <= 0) {
+      throw new GuideShotError(
+        "RECIPE_SCHEMA_INVALID",
+        `Profile "${name}" has an invalid viewport.`
+      );
+    }
+    if (profile.pixelRatio !== void 0 && (!Number.isFinite(profile.pixelRatio) || profile.pixelRatio <= 0)) {
+      throw new GuideShotError(
+        "RECIPE_SCHEMA_INVALID",
+        `Profile "${name}" has an invalid pixel ratio.`
+      );
+    }
+  }
+}
+function validateRecipeSemantics(source, config) {
+  const { recipe } = source;
+  const profile = recipe.profile ?? defaultProfileName(config);
+  if (config.profiles[profile] === void 0) {
+    throw new GuideShotError(
+      "EXTENSION_NOT_REGISTERED",
+      `Recipe "${recipe.id}" references unknown profile "${profile}".`,
+      recipeOptions(source, { profile })
+    );
+  }
+  validateScenario(recipe, source, config);
+  validateMatrix(recipe, source, config);
+  validateAnnotationIds(recipe, source);
+}
+function defaultProfileName(config) {
+  const names = Object.keys(config.profiles).sort(compareStrings2);
+  const name = names[0];
+  if (name === void 0) {
+    throw new GuideShotError(
+      "EXTENSION_NOT_REGISTERED",
+      "No capture profile is registered."
+    );
+  }
+  return name;
+}
+function validateScenario(recipe, source, config) {
+  if (recipe.scenario === void 0) {
+    return;
+  }
+  const scenario = config.scenarios?.[recipe.scenario.use];
+  if (scenario === void 0) {
+    throw new GuideShotError(
+      "EXTENSION_NOT_REGISTERED",
+      `Recipe "${recipe.id}" references unknown scenario "${recipe.scenario.use}".`,
+      recipeOptions(source, { scenario: recipe.scenario.use })
+    );
+  }
+  const validator = extensionValidator(scenario.schema);
+  const input = recipe.scenario.with ?? {};
+  if (!validator(input)) {
+    throw new GuideShotError(
+      "RECIPE_SCHEMA_INVALID",
+      formatValidationMessage(
+        `Scenario "${recipe.scenario.use}" parameters`,
+        validator.errors
+      ),
+      {
+        ...recipeOptions(source),
+        details: validationDetails(validator.errors)
+      }
+    );
+  }
+}
+function extensionValidator(schema) {
+  const existing = extensionValidators.get(schema);
+  if (existing !== void 0) {
+    return existing;
+  }
+  const validator = ajv.compile(schema);
+  extensionValidators.set(schema, validator);
+  return validator;
+}
+function validateMatrix(recipe, source, config) {
+  for (const [name, values] of Object.entries(
+    recipe.matrix?.dimensions ?? {}
+  )) {
+    const definition = config.dimensions?.[name];
+    if (definition === void 0) {
+      throw new GuideShotError(
+        "EXTENSION_NOT_REGISTERED",
+        `Recipe "${recipe.id}" references unknown dimension "${name}".`,
+        recipeOptions(source, { dimension: name })
+      );
+    }
+    for (const value of values) {
+      if (!definition.values.some((candidate) => Object.is(candidate, value))) {
+        throw new GuideShotError(
+          "RECIPE_SCHEMA_INVALID",
+          `Dimension "${name}" does not allow value "${String(value)}".`,
+          recipeOptions(source, { dimension: name })
+        );
+      }
+    }
+  }
+}
+function validateAnnotationIds(recipe, source) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const annotation of recipe.annotations ?? []) {
+    if (ids.has(annotation.id)) {
+      throw new GuideShotError(
+        "RECIPE_SCHEMA_INVALID",
+        `Recipe "${recipe.id}" contains duplicate annotation id "${annotation.id}".`,
+        recipeOptions(source, { annotationId: annotation.id })
+      );
+    }
+    ids.add(annotation.id);
+  }
+}
+function schemaError(subject, errors, file) {
+  return new GuideShotError(
+    "RECIPE_SCHEMA_INVALID",
+    formatValidationMessage(subject, errors),
+    {
+      ...file === void 0 ? {} : { location: { file } },
+      details: validationDetails(errors)
+    }
+  );
+}
+function formatValidationMessage(subject, errors) {
+  const first = errors?.[0];
+  if (first === void 0) {
+    return `${subject} does not match its schema.`;
+  }
+  const path4 = first.instancePath === "" ? "/" : first.instancePath;
+  return `${subject} is invalid at ${path4}: ${first.message ?? first.keyword}.`;
+}
+function validationDetails(errors) {
+  return {
+    errors: (errors ?? []).map((error) => ({
+      path: error.instancePath,
+      keyword: error.keyword,
+      message: error.message ?? ""
+    }))
+  };
+}
+function recipeOptions(source, details) {
+  return {
+    recipeId: source.recipe.id,
+    location: { file: source.file },
+    ...details === void 0 ? {} : { details }
+  };
+}
+function inferFormat(file) {
+  return file?.toLowerCase().endsWith(".jsonc") === true ? "jsonc" : "json";
+}
+function positionAt(source, offset) {
+  const prefix = source.slice(0, offset);
+  const lines = prefix.split(/\r?\n/);
+  return {
+    line: lines.length,
+    column: (lines.at(-1)?.length ?? 0) + 1
+  };
+}
+function compactLocation(location) {
+  return location.file === void 0 ? { line: location.line, column: location.column } : { file: location.file, line: location.line, column: location.column };
+}
+function compareStrings2(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+// src/discovery.ts
+async function discoverRecipes(config, projectRoot) {
+  const root = path.resolve(projectRoot);
+  const files = await fg([...config.recipes], {
+    absolute: true,
+    cwd: root,
+    followSymbolicLinks: false,
+    onlyFiles: true,
+    unique: true
+  });
+  files.sort(compareStrings3);
+  if (files.length === 0) {
+    throw new GuideShotError(
+      "RECIPE_SCHEMA_INVALID",
+      "No recipe files matched the configured discovery patterns."
+    );
+  }
+  const sources = await Promise.all(
+    files.map(async (file) => {
+      assertInsideProject(root, file);
+      const text = await readFile(file, "utf8");
+      return {
+        file,
+        recipe: parseRecipe(text, {
+          file,
+          format: file.toLowerCase().endsWith(".jsonc") ? "jsonc" : "json"
+        })
+      };
+    })
+  );
+  assertUniqueRecipeIds(sources);
+  return sources;
+}
+function assertUniqueRecipeIds(sources) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const source of sources) {
+    const previous = seen.get(source.recipe.id);
+    if (previous !== void 0) {
+      throw new GuideShotError(
+        "OUTPUT_COLLISION",
+        `Recipe id "${source.recipe.id}" is declared more than once.`,
+        {
+          recipeId: source.recipe.id,
+          location: { file: source.file },
+          details: { previousFile: previous }
+        }
+      );
+    }
+    seen.set(source.recipe.id, source.file);
+  }
+}
+function assertInsideProject(root, file) {
+  const relative = path.relative(root, file);
+  if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new GuideShotError(
+      "RECIPE_SCHEMA_INVALID",
+      "Recipe discovery may not read outside the project root.",
+      { location: { file } }
+    );
+  }
+}
+function compareStrings3(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+// src/interpolate.ts
+var REFERENCE = /\$\{([^}]+)\}/g;
+var FULL_REFERENCE = /^\$\{([^}]+)\}$/;
+var SAFE_SEGMENT = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+var FORBIDDEN_SEGMENTS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+function interpolate(value, context) {
+  return interpolateValue(value, context);
+}
+function interpolateString(value, context) {
+  const full = FULL_REFERENCE.exec(value);
+  if (full !== null) {
+    return resolveReference(requiredGroup(full, 1), context);
+  }
+  REFERENCE.lastIndex = 0;
+  const interpolated = value.replace(
+    REFERENCE,
+    (_match, rawReference) => {
+      const resolved = resolveReference(rawReference, context);
+      if (typeof resolved === "object" || resolved === null || Array.isArray(resolved)) {
+        throw unresolved(
+          rawReference,
+          "Embedded references must resolve to a string, number, or boolean."
+        );
+      }
+      return String(resolved);
+    }
+  );
+  if (interpolated.includes("${")) {
+    throw unresolved(value, "Reference syntax is incomplete.");
+  }
+  return interpolated;
+}
+function interpolateValue(value, context) {
+  if (typeof value === "string") {
+    return interpolateString(value, context);
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => interpolateValue(entry, context));
+  }
+  if (isPlainObject2(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [
+        key,
+        interpolateValue(entry, context)
+      ])
+    );
+  }
+  return value;
+}
+function resolveReference(reference, context) {
+  const segments = reference.split(".");
+  const root = segments.shift();
+  if (root !== "scenario" && root !== "variant" || segments.length === 0 || segments.some(
+    (segment) => !SAFE_SEGMENT.test(segment) || FORBIDDEN_SEGMENTS.has(segment)
+  )) {
+    throw unresolved(
+      reference,
+      "References must use ${scenario.name} or ${variant.name} lookups."
+    );
+  }
+  let current = root === "scenario" ? context.scenario : context.variant;
+  for (const segment of segments) {
+    if (!isPlainObject2(current) || !Object.hasOwn(current, segment)) {
+      throw unresolved(reference, `No value exists for "${reference}".`);
+    }
+    current = current[segment];
+  }
+  if (!isJsonValue(current)) {
+    throw unresolved(
+      reference,
+      `The value for "${reference}" is not JSON data.`
+    );
+  }
+  return current;
+}
+function unresolved(reference, message) {
+  return new GuideShotError("VARIABLE_UNRESOLVED", message, {
+    details: { reference }
+  });
+}
+function isJsonValue(value) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return true;
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value);
+  }
+  if (Array.isArray(value)) {
+    return value.every(isJsonValue);
+  }
+  return isPlainObject2(value) && Object.values(value).every(isJsonValue);
+}
+function isPlainObject2(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function requiredGroup(match, index) {
+  const value = match[index];
+  if (value === void 0) {
+    throw new GuideShotError(
+      "VARIABLE_UNRESOLVED",
+      "Reference syntax is incomplete."
+    );
+  }
+  return value;
+}
+
+// src/manifest.ts
+import path3 from "path";
+import {
+  SCHEMA_VERSION
+} from "@guideshot/schema";
+
+// src/safety.ts
+import path2 from "path";
+var HTTP_PROTOCOLS = /* @__PURE__ */ new Set(["http:", "https:"]);
+function assertAllowedOrigin(value, allowedOrigins = []) {
+  const url = toUrl(value);
+  if (!HTTP_PROTOCOLS.has(url.protocol)) {
+    throw originError(url, "Only HTTP and HTTPS origins are supported.");
+  }
+  if (url.username !== "" || url.password !== "") {
+    throw originError(url, "Credentials are not allowed in the server URL.");
+  }
+  const allowed = new Set(allowedOrigins.map(normalizeAllowedOrigin));
+  if (!isLoopbackHostname(url.hostname) && !allowed.has(url.origin)) {
+    throw originError(
+      url,
+      `Origin "${url.origin}" is not loopback and is not explicitly allowed.`
+    );
+  }
+  return url;
+}
+function resolvePageUrl(baseUrl, pagePath) {
+  const base = toUrl(baseUrl);
+  const resolved = new URL(pagePath, base);
+  if (resolved.origin !== base.origin || !HTTP_PROTOCOLS.has(resolved.protocol)) {
+    throw originError(
+      resolved,
+      `Page path "${pagePath}" resolves outside the configured origin.`
+    );
+  }
+  if (resolved.username !== "" || resolved.password !== "") {
+    throw originError(resolved, "Credentials are not allowed in page URLs.");
+  }
+  return resolved;
+}
+function resolveSafeProjectPaths(projectRoot, outputDir, cacheDir) {
+  const root = path2.resolve(projectRoot);
+  const output = resolveDescendant(root, outputDir, "output");
+  const cache = resolveDescendant(root, cacheDir, "cache");
+  if (output === cache || isInside(output, cache) || isInside(cache, output)) {
+    throw new GuideShotError(
+      "OUTPUT_COLLISION",
+      "Output and cache directories must not overlap."
+    );
+  }
+  return { outputDir: output, cacheDir: cache };
+}
+function resolveArtifactPath(outputDir, relativePath) {
+  if (path2.isAbsolute(relativePath) || relativePath.includes("\0")) {
+    throw unsafeOutputPath(relativePath);
+  }
+  const root = path2.resolve(outputDir);
+  const resolved = path2.resolve(root, relativePath);
+  if (!isInside(root, resolved)) {
+    throw unsafeOutputPath(relativePath);
+  }
+  return resolved;
+}
+function sanitizeFileSegment(value) {
+  const sanitized = value.normalize("NFKD").replace(/[^A-Za-z0-9._-]+/g, "-").replace(/-{2,}/g, "-").replace(/^[-.]+|[-.]+$/g, "");
+  if (sanitized === "") {
+    throw new GuideShotError(
+      "OUTPUT_COLLISION",
+      `Value "${value}" cannot be represented safely in an output filename.`
+    );
+  }
+  return sanitized;
+}
+function resolveDescendant(root, candidate, label) {
+  if (candidate.includes("\0")) {
+    throw unsafeOutputPath(candidate);
+  }
+  const resolved = path2.resolve(root, candidate);
+  if (resolved === root || !isInside(root, resolved)) {
+    throw new GuideShotError(
+      "OUTPUT_COLLISION",
+      `Configured ${label} directory must be below the project root.`,
+      { details: { directory: candidate } }
+    );
+  }
+  return resolved;
+}
+function isInside(parent, child) {
+  const relative = path2.relative(parent, child);
+  return relative !== "" && relative !== ".." && !relative.startsWith(`..${path2.sep}`) && !path2.isAbsolute(relative);
+}
+function isLoopbackHostname(hostname) {
+  const normalized = hostname.replace(/^\[|\]$/g, "").toLowerCase();
+  if (normalized === "localhost" || normalized === "::1") {
+    return true;
+  }
+  const match = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(normalized);
+  if (match === null) {
+    return false;
+  }
+  return Number(match[1]) === 127;
+}
+function normalizeAllowedOrigin(value) {
+  const url = toUrl(value);
+  if (!HTTP_PROTOCOLS.has(url.protocol) || url.username !== "" || url.password !== "") {
+    throw originError(url, `Invalid allowed origin "${value}".`);
+  }
+  return url.origin;
+}
+function toUrl(value) {
+  try {
+    return value instanceof URL ? new URL(value.href) : new URL(value);
+  } catch (cause) {
+    throw new GuideShotError(
+      "ORIGIN_NOT_ALLOWED",
+      `Invalid URL "${String(value)}".`,
+      {
+        cause
+      }
+    );
+  }
+}
+function originError(url, message) {
+  return new GuideShotError("ORIGIN_NOT_ALLOWED", message, {
+    details: { origin: url.origin }
+  });
+}
+function unsafeOutputPath(value) {
+  return new GuideShotError(
+    "OUTPUT_COLLISION",
+    `Unsafe output path "${value}".`
+  );
+}
+
+// src/manifest.ts
+function buildPublicManifest(assets) {
+  const entries = /* @__PURE__ */ new Map();
+  for (const asset of assets) {
+    assertPublicAsset(asset);
+    const entry = entries.get(asset.recipeId) ?? {
+      ...asset.title === void 0 ? {} : { title: asset.title },
+      variants: /* @__PURE__ */ new Map()
+    };
+    if (entry.title !== void 0 && asset.title !== void 0 && entry.title !== asset.title) {
+      throw new GuideShotError(
+        "OUTPUT_COLLISION",
+        `Recipe "${asset.recipeId}" has conflicting manifest titles.`,
+        { recipeId: asset.recipeId }
+      );
+    }
+    if (entry.title === void 0 && asset.title !== void 0) {
+      entry.title = asset.title;
+    }
+    if (entry.variants.has(asset.variantKey)) {
+      throw new GuideShotError(
+        "OUTPUT_COLLISION",
+        `Manifest variant "${asset.recipeId}::${asset.variantKey}" is duplicated.`,
+        { recipeId: asset.recipeId }
+      );
+    }
+    entry.variants.set(asset.variantKey, {
+      src: asset.src,
+      width: asset.width,
+      height: asset.height,
+      format: asset.format,
+      hash: asset.hash,
+      alt: asset.alt
+    });
+    entries.set(asset.recipeId, entry);
+  }
+  const manifestEntries = [...entries.entries()].sort(([left], [right]) => compareStrings4(left, right)).map(([id, entry]) => ({
+    id,
+    ...entry.title === void 0 ? {} : { title: entry.title },
+    variants: Object.fromEntries(
+      [...entry.variants.entries()].sort(
+        ([left], [right]) => compareStrings4(left, right)
+      )
+    )
+  }));
+  return validateManifest({
+    version: SCHEMA_VERSION,
+    entries: manifestEntries
+  });
+}
+function createAssetPath(recipeId, variantKey, hash, format) {
+  assertHash(hash);
+  const variant = variantKey === "default" ? "default" : variantKey;
+  const filename = [
+    sanitizeFileSegment(recipeId),
+    sanitizeFileSegment(variant),
+    hash.slice(0, 12)
+  ].join(".");
+  return `./assets/${filename}.${format}`;
+}
+function assertPublicAsset(asset) {
+  if (!isSafePublicSource(asset.src)) {
+    throw new GuideShotError(
+      "MANIFEST_INVALID",
+      `Manifest source "${asset.src}" must be a relative asset path.`,
+      { recipeId: asset.recipeId }
+    );
+  }
+  if (!Number.isInteger(asset.width) || asset.width <= 0 || !Number.isInteger(asset.height) || asset.height <= 0) {
+    throw new GuideShotError(
+      "MANIFEST_INVALID",
+      `Manifest variant "${asset.recipeId}::${asset.variantKey}" has invalid dimensions.`,
+      { recipeId: asset.recipeId }
+    );
+  }
+  assertHash(asset.hash);
+}
+function isSafePublicSource(source) {
+  if (source === "" || source.includes("\0") || source.includes("\\") || source.includes("?") || source.includes("#") || path3.posix.isAbsolute(source) || /^[A-Za-z][A-Za-z0-9+.-]*:/.test(source)) {
+    return false;
+  }
+  const normalized = path3.posix.normalize(source.replace(/^\.\//, ""));
+  return normalized.startsWith("assets/") && normalized !== "assets" && !normalized.startsWith("../");
+}
+function assertHash(hash) {
+  if (!/^[a-f0-9]{64}$/.test(hash)) {
+    throw new GuideShotError(
+      "MANIFEST_INVALID",
+      "Manifest asset hashes must be lowercase SHA-256 values."
+    );
+  }
+}
+function compareStrings4(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+// src/matrix.ts
+function expandMatrix(matrix) {
+  if (matrix === void 0) {
+    return [{ key: "default", values: {} }];
+  }
+  const dimensions = Object.keys(matrix.dimensions).sort(compareStrings5);
+  validateDimensions(dimensions, matrix);
+  let rows = [{}];
+  for (const dimension of dimensions) {
+    const values = matrix.dimensions[dimension] ?? [];
+    rows = rows.flatMap(
+      (row) => values.map((value) => ({ ...row, [dimension]: value }))
+    );
+  }
+  rows = rows.filter(
+    (row) => !(matrix.exclude ?? []).some((rule) => matchesRule(row, rule))
+  );
+  for (const included of matrix.include ?? []) {
+    validateIncludedRow(included, dimensions, matrix);
+    if (!rows.some((row) => rowsEqual(row, included))) {
+      rows.push(copySorted(included));
+    }
+  }
+  if (dimensions.length === 0 && rows.length === 0) {
+    rows.push({});
+  }
+  const keys = /* @__PURE__ */ new Map();
+  const expanded = rows.map((values) => {
+    const sorted = copySorted(values);
+    const key = createVariantKey(sorted);
+    const previous = keys.get(key);
+    if (previous !== void 0 && !rowsEqual(previous, sorted)) {
+      throw new GuideShotError(
+        "OUTPUT_COLLISION",
+        `Variant values produce the same key "${key}".`,
+        { details: { key } }
+      );
+    }
+    keys.set(key, sorted);
+    return { key, values: sorted };
+  });
+  return expanded;
+}
+function createVariantKey(variants) {
+  const entries = Object.entries(variants).sort(
+    ([left], [right]) => compareStrings5(left, right)
+  );
+  if (entries.length === 0) {
+    return "default";
+  }
+  return entries.map(
+    ([dimension, value]) => `${encodeURIComponent(dimension)}=${encodeURIComponent(String(value))}`
+  ).join(";");
+}
+function matchesVariantFilter(variants, filter) {
+  return matchesRule(variants, filter);
+}
+function validateDimensions(dimensions, matrix) {
+  for (const dimension of dimensions) {
+    if (!isDimensionName(dimension)) {
+      throw new GuideShotError(
+        "RECIPE_SCHEMA_INVALID",
+        `Invalid matrix dimension name "${dimension}".`
+      );
+    }
+    const values = matrix.dimensions[dimension] ?? [];
+    if (values.length === 0) {
+      throw new GuideShotError(
+        "RECIPE_SCHEMA_INVALID",
+        `Matrix dimension "${dimension}" must contain at least one value.`
+      );
+    }
+    const encoded = /* @__PURE__ */ new Set();
+    for (const value of values) {
+      const key = String(value);
+      if (encoded.has(key)) {
+        throw new GuideShotError(
+          "OUTPUT_COLLISION",
+          `Matrix dimension "${dimension}" contains colliding value "${key}".`
+        );
+      }
+      encoded.add(key);
+    }
+  }
+  for (const rule of matrix.exclude ?? []) {
+    for (const dimension of Object.keys(rule)) {
+      if (!dimensions.includes(dimension)) {
+        throw new GuideShotError(
+          "RECIPE_SCHEMA_INVALID",
+          `Matrix exclusion references unknown dimension "${dimension}".`
+        );
+      }
+    }
+  }
+}
+function validateIncludedRow(row, dimensions, matrix) {
+  const includedDimensions = Object.keys(row).sort(compareStrings5);
+  if (includedDimensions.length !== dimensions.length || includedDimensions.some(
+    (dimension, index) => dimension !== dimensions[index]
+  )) {
+    throw new GuideShotError(
+      "RECIPE_SCHEMA_INVALID",
+      "Every matrix inclusion must specify exactly every declared dimension."
+    );
+  }
+  for (const dimension of dimensions) {
+    const value = row[dimension];
+    const allowed = matrix.dimensions[dimension] ?? [];
+    if (!allowed.some((candidate) => Object.is(candidate, value))) {
+      throw new GuideShotError(
+        "RECIPE_SCHEMA_INVALID",
+        `Matrix inclusion uses an unsupported value for "${dimension}".`
+      );
+    }
+  }
+}
+function matchesRule(row, rule) {
+  return Object.entries(rule).every(
+    ([dimension, value]) => Object.is(row[dimension], value)
+  );
+}
+function rowsEqual(left, right) {
+  const dimensions = Object.keys(left);
+  return dimensions.length === Object.keys(right).length && dimensions.every(
+    (dimension) => Object.is(left[dimension], right[dimension])
+  );
+}
+function copySorted(values) {
+  return Object.fromEntries(
+    Object.entries(values).sort(
+      ([left], [right]) => compareStrings5(left, right)
+    )
+  );
+}
+function isDimensionName(value) {
+  return /^[a-z][a-zA-Z0-9_-]*$/.test(value);
+}
+function compareStrings5(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+// src/planner.ts
+async function planProject(config, projectRoot, options = {}) {
+  const recipes = await discoverRecipes(config, projectRoot);
+  return planRecipes(config, recipes, options);
+}
+function planRecipes(config, sources, options = {}) {
+  validateConfig(config);
+  assertUniqueRecipeIds(sources);
+  const serverUrl = assertAllowedOrigin(
+    config.server.url,
+    config.safety?.allowedOrigins ?? []
+  );
+  const jobs = [];
+  for (const source of sources) {
+    validateRecipeSemantics(source, config);
+    resolvePageUrl(serverUrl, source.recipe.page.path);
+    if (!recipeSelected(source, options)) {
+      continue;
+    }
+    const recipe = source.recipe;
+    const profileName = recipe.profile ?? defaultProfileName(config);
+    const profile = resolveProfile(
+      config.profiles[profileName],
+      recipe.capture?.pixelRatio
+    );
+    for (const row of expandMatrix(recipe.matrix)) {
+      if (options.variants !== void 0 && !matchesVariantFilter(row.values, options.variants)) {
+        continue;
+      }
+      const dimensionVersions = Object.fromEntries(
+        Object.keys(row.values).sort(compareStrings6).map((dimension) => [
+          dimension,
+          requiredDimensionVersion(config, dimension, recipe.id)
+        ])
+      );
+      const scenario = recipe.scenario === void 0 ? void 0 : config.scenarios?.[recipe.scenario.use];
+      const captureIntent = {
+        recipeId: recipe.id,
+        profile: profileName,
+        serverUrl: config.server.url,
+        targetAttribute: config.targetAttribute ?? "data-guide-target",
+        variants: row.values,
+        page: recipe.page,
+        profileConfig: profile,
+        dimensionVersions,
+        driver: { name: config.driver.name, version: config.driver.version },
+        ...recipe.scenario === void 0 ? {} : { scenario: recipe.scenario },
+        ...recipe.prepare === void 0 ? {} : { prepare: recipe.prepare },
+        ...recipe.ready === void 0 ? {} : { ready: recipe.ready },
+        ...recipe.capture === void 0 ? {} : { capture: recipe.capture },
+        ...scenario === void 0 ? {} : {
+          scenarioVersion: scenario.version,
+          ...scenario.datasetRevision === void 0 ? {} : { datasetRevision: scenario.datasetRevision }
+        },
+        ...config.translations === void 0 ? {} : { translationVersion: config.translations.version }
+      };
+      const compositionIntent = {
+        accessibility: recipe.accessibility,
+        renderer: {
+          name: config.renderer.name,
+          version: config.renderer.version
+        },
+        ...recipe.annotations === void 0 ? {} : { annotations: recipe.annotations },
+        ...recipe.output === void 0 ? {} : { output: recipe.output },
+        ...config.translations === void 0 ? {} : { translationVersion: config.translations.version }
+      };
+      jobs.push({
+        key: `${recipe.id}::${row.key}`,
+        recipeId: recipe.id,
+        recipeFile: source.file,
+        profile: profileName,
+        variantKey: row.key,
+        variants: row.values,
+        captureKey: createCaptureHash(captureIntent),
+        captureIntent,
+        compositionIntent,
+        recipe
+      });
+    }
+  }
+  jobs.sort((left, right) => compareStrings6(left.key, right.key));
+  assertUniqueJobKeys(jobs);
+  return { jobs, recipes: [...sources] };
+}
+function createJobCompositionHash(job, sceneHash) {
+  return createCompositionHash({
+    ...job.compositionIntent,
+    sceneHash
+  });
+}
+function recipeSelected(source, options) {
+  if (options.ids !== void 0 && !options.ids.includes(source.recipe.id)) {
+    return false;
+  }
+  if (options.tags !== void 0 && !options.tags.every((tag) => source.recipe.tags?.includes(tag) === true)) {
+    return false;
+  }
+  return true;
+}
+function resolveProfile(profile, pixelRatio) {
+  if (profile === void 0) {
+    throw new GuideShotError(
+      "EXTENSION_NOT_REGISTERED",
+      "The selected capture profile is not registered."
+    );
+  }
+  return {
+    ...profile,
+    ...pixelRatio === void 0 ? {} : { pixelRatio }
+  };
+}
+function requiredDimensionVersion(config, dimension, recipeId) {
+  const definition = config.dimensions?.[dimension];
+  if (definition === void 0) {
+    throw new GuideShotError(
+      "EXTENSION_NOT_REGISTERED",
+      `Recipe "${recipeId}" references unknown dimension "${dimension}".`,
+      { recipeId, details: { dimension } }
+    );
+  }
+  return definition.version;
+}
+function assertUniqueJobKeys(jobs) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const job of jobs) {
+    if (seen.has(job.key)) {
+      throw new GuideShotError(
+        "OUTPUT_COLLISION",
+        `More than one capture job resolves to "${job.key}".`,
+        { recipeId: job.recipeId, jobKey: job.key }
+      );
+    }
+    seen.add(job.key);
+  }
+}
+function compareStrings6(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+// src/text.ts
+async function resolveLocalizedText(value, provider, context) {
+  if (typeof value === "string") {
+    return value;
+  }
+  const candidate = value;
+  if (typeof candidate.message === "string" && (candidate.args === void 0 || isJsonObject(candidate.args))) {
+    if (provider === void 0) {
+      throw new GuideShotError(
+        "EXTENSION_NOT_REGISTERED",
+        `Translation message "${candidate.message}" requires a translation provider.`
+      );
+    }
+    return provider.resolve(candidate.message, {
+      locale: context.locale,
+      args: candidate.args ?? {},
+      variables: context.variables
+    });
+  }
+  const localeMap = value;
+  const exact = localeMap[context.locale];
+  if (exact !== void 0) {
+    return exact;
+  }
+  const baseLocale = context.locale.split("-")[0];
+  const base = baseLocale === void 0 ? void 0 : localeMap[baseLocale];
+  if (base !== void 0) {
+    return base;
+  }
+  throw new GuideShotError(
+    "VARIABLE_UNRESOLVED",
+    `Localized text has no value for locale "${context.locale}".`,
+    { details: { locale: context.locale } }
+  );
+}
+async function resolveRecipeText(recipe, provider, context) {
+  const prepare = await Promise.all(
+    (recipe.prepare ?? []).map(
+      (action) => resolveActionText(action, provider, context)
+    )
+  );
+  const ready = await Promise.all(
+    (recipe.ready ?? []).map(
+      (expectation) => resolveExpectationText(expectation, provider, context)
+    )
+  );
+  const annotations = await Promise.all(
+    (recipe.annotations ?? []).map(
+      (annotation) => resolveAnnotationText(annotation, provider, context)
+    )
+  );
+  const accessibility = "alt" in recipe.accessibility ? {
+    alt: await resolveLocalizedText(
+      recipe.accessibility.alt,
+      provider,
+      context
+    )
+  } : recipe.accessibility;
+  return {
+    ...recipe,
+    ...recipe.prepare === void 0 ? {} : { prepare },
+    ...recipe.ready === void 0 ? {} : { ready },
+    ...recipe.annotations === void 0 ? {} : { annotations },
+    accessibility
+  };
+}
+function resolvedAnnotations(recipe) {
+  return (recipe.annotations ?? []).map((definition) => ({
+    definition,
+    ...(definition.kind === "callout" || definition.kind === "label" || definition.kind === "marker") && typeof definition.content === "string" ? { text: definition.content } : {}
+  }));
+}
+function resolvedAlt(recipe) {
+  const accessibility = recipe.accessibility;
+  if ("decorative" in accessibility) {
+    return "";
+  }
+  if (typeof accessibility.alt !== "string") {
+    throw new GuideShotError(
+      "VARIABLE_UNRESOLVED",
+      `Alt text for recipe "${recipe.id}" has not been resolved.`,
+      { recipeId: recipe.id }
+    );
+  }
+  return accessibility.alt;
+}
+async function resolveActionText(action, provider, context) {
+  if (action.do !== "fill") {
+    return action;
+  }
+  return {
+    ...action,
+    value: await resolveLocalizedText(action.value, provider, context)
+  };
+}
+async function resolveExpectationText(expectation, provider, context) {
+  if (expectation.expect !== "text" && expectation.expect !== "value") {
+    return expectation;
+  }
+  return {
+    ...expectation,
+    value: await resolveLocalizedText(expectation.value, provider, context)
+  };
+}
+async function resolveAnnotationText(annotation, provider, context) {
+  if (annotation.kind !== "callout" && annotation.kind !== "label" && annotation.kind !== "marker") {
+    return annotation;
+  }
+  const content = annotation.content;
+  if (content === void 0) {
+    return annotation;
+  }
+  return {
+    ...annotation,
+    content: await resolveLocalizedText(content, provider, context)
+  };
+}
+function isJsonObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/resolution.ts
+async function resolveJob(planned, config, options) {
+  const scenario = await prepareScenario(planned, config, options);
+  try {
+    const dimensionState = await resolveDimensions(
+      planned,
+      config,
+      options.signal
+    );
+    const safeVariables = scenario?.variables ?? {};
+    const browser = mergeBrowserState(
+      profileBrowserState(planned),
+      dimensionState,
+      scenario?.browser ?? {}
+    );
+    const interpolatedRecipe = validateRecipe(
+      interpolate(planned.recipe, {
+        scenario: safeVariables,
+        variant: planned.variants
+      }),
+      planned.recipeFile
+    );
+    const recipe = validateRecipe(
+      await resolveRecipeText(interpolatedRecipe, config.translations, {
+        locale: browser.locale ?? "en",
+        variables: safeVariables,
+        variants: planned.variants
+      }),
+      planned.recipeFile
+    );
+    resolvePageUrl(options.baseUrl, recipe.page.path);
+    return {
+      recipe,
+      capture: {
+        key: planned.key,
+        recipeId: planned.recipeId,
+        variantKey: planned.variantKey,
+        variants: planned.variants,
+        profile: planned.captureIntent.profileConfig,
+        page: recipe.page,
+        prepare: recipe.prepare ?? [],
+        ready: recipe.ready ?? [],
+        capture: recipe.capture ?? {},
+        browser,
+        safeVariables
+      },
+      ...scenario?.cleanup === void 0 ? {} : { cleanup: scenario.cleanup }
+    };
+  } catch (failure) {
+    return cleanupAfterResolutionFailure(scenario?.cleanup, planned, failure);
+  }
+}
+async function cleanupAfterResolutionFailure(cleanup, planned, failure) {
+  if (cleanup === void 0) throw failure;
+  try {
+    await cleanup();
+  } catch (cleanupFailure) {
+    throw new GuideShotError(
+      "SCENARIO_FAILED",
+      `Scenario cleanup failed after job resolution failed for "${planned.key}".`,
+      {
+        recipeId: planned.recipeId,
+        jobKey: planned.key,
+        details: {
+          resolutionError: errorMessage(failure),
+          cleanupError: errorMessage(cleanupFailure)
+        },
+        cause: new AggregateError(
+          [failure, cleanupFailure],
+          `Resolution and scenario cleanup both failed for "${planned.key}".`
+        )
+      }
+    );
+  }
+  throw failure;
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function mergeBrowserState(...patches) {
+  const scalar = {};
+  const cookies = /* @__PURE__ */ new Map();
+  const storage = /* @__PURE__ */ new Map();
+  const headers = {};
+  for (const patch of patches) {
+    assignDefinedScalar(scalar, patch, "locale");
+    assignDefinedScalar(scalar, patch, "timezoneId");
+    assignDefinedScalar(scalar, patch, "colorScheme");
+    assignDefinedScalar(scalar, patch, "reducedMotion");
+    for (const cookie of patch.cookies ?? []) {
+      cookies.set(cookieKey(cookie), cookie);
+    }
+    for (const origin of patch.localStorage ?? []) {
+      const values = storage.get(origin.origin) ?? /* @__PURE__ */ new Map();
+      for (const [key, value] of Object.entries(origin.values)) {
+        values.set(key, value);
+      }
+      storage.set(origin.origin, values);
+    }
+    Object.assign(headers, patch.extraHTTPHeaders);
+  }
+  return {
+    ...scalar,
+    ...cookies.size === 0 ? {} : { cookies: [...cookies.values()] },
+    ...storage.size === 0 ? {} : {
+      localStorage: [...storage.entries()].map(
+        ([origin, values]) => ({
+          origin,
+          values: Object.fromEntries(values)
+        })
+      )
+    },
+    ...Object.keys(headers).length === 0 ? {} : { extraHTTPHeaders: headers }
+  };
+}
+async function resolveDimensions(planned, config, signal) {
+  const patches = [];
+  for (const dimension of Object.keys(planned.variants).sort(compareStrings7)) {
+    const definition = config.dimensions?.[dimension];
+    if (definition === void 0) {
+      throw new GuideShotError(
+        "EXTENSION_NOT_REGISTERED",
+        `Dimension "${dimension}" is not registered.`,
+        { recipeId: planned.recipeId, jobKey: planned.key }
+      );
+    }
+    const value = planned.variants[dimension];
+    if (value === void 0) {
+      throw new GuideShotError(
+        "RECIPE_SCHEMA_INVALID",
+        `Dimension "${dimension}" has no resolved value.`,
+        { recipeId: planned.recipeId, jobKey: planned.key }
+      );
+    }
+    patches.push(
+      await definition.resolve(value, {
+        dimension,
+        variants: planned.variants,
+        ...signal === void 0 ? {} : { signal }
+      })
+    );
+  }
+  return mergeBrowserState(...patches);
+}
+async function prepareScenario(planned, config, options) {
+  const reference = planned.recipe.scenario;
+  if (reference === void 0) {
+    return void 0;
+  }
+  const definition = config.scenarios?.[reference.use];
+  if (definition === void 0) {
+    throw new GuideShotError(
+      "EXTENSION_NOT_REGISTERED",
+      `Scenario "${reference.use}" is not registered.`,
+      { recipeId: planned.recipeId, jobKey: planned.key }
+    );
+  }
+  const input = interpolate(reference.with ?? {}, {
+    variant: planned.variants
+  });
+  try {
+    return await definition.prepare(
+      {
+        baseUrl: options.baseUrl,
+        recipeId: planned.recipeId,
+        variantKey: planned.variantKey,
+        variants: planned.variants,
+        fetch: options.fetch ?? globalThis.fetch,
+        ...options.signal === void 0 ? {} : { signal: options.signal }
+      },
+      input
+    );
+  } catch (cause) {
+    throw new GuideShotError(
+      "SCENARIO_FAILED",
+      `Scenario "${reference.use}" failed for ${planned.key}.`,
+      {
+        recipeId: planned.recipeId,
+        jobKey: planned.key,
+        cause
+      }
+    );
+  }
+}
+function profileBrowserState(planned) {
+  const profile = planned.captureIntent.profileConfig;
+  return {
+    ...profile.locale === void 0 ? {} : { locale: profile.locale },
+    ...profile.timezoneId === void 0 ? {} : { timezoneId: profile.timezoneId },
+    ...profile.colorScheme === void 0 ? {} : { colorScheme: profile.colorScheme },
+    ...profile.reducedMotion === void 0 ? {} : { reducedMotion: profile.reducedMotion }
+  };
+}
+function assignDefinedScalar(target, source, key) {
+  const value = source[key];
+  if (value !== void 0) {
+    Object.assign(target, { [key]: value });
+  }
+}
+function cookieKey(cookie) {
+  return [
+    cookie.name,
+    cookie.url ?? cookie.domain ?? "",
+    cookie.path ?? "/"
+  ].join("\0");
+}
+function compareStrings7(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+export {
+  DIAGNOSTIC_CODES,
+  GuideShotError,
+  PublicManifestSchema2 as PublicManifestSchema,
+  RecipeSchema2 as RecipeSchema,
+  SCHEMA_VERSION2 as SCHEMA_VERSION,
+  assertAllowedOrigin,
+  assertUniqueRecipeIds,
+  buildPublicManifest,
+  canonicalSerialize,
+  createAssetPath,
+  createCaptureHash,
+  createCompositionHash,
+  createJobCompositionHash,
+  createVariantKey,
+  defaultProfileName,
+  defineConfig,
+  defineDimension,
+  defineScenario,
+  diagnosticFromUnknown,
+  discoverRecipes,
+  expandMatrix,
+  hashCanonical,
+  interpolate,
+  interpolateString,
+  isGuideShotError,
+  matchesVariantFilter,
+  mergeBrowserState,
+  parseRecipe,
+  planProject,
+  planRecipes,
+  resolveArtifactPath,
+  resolveJob,
+  resolveLocalizedText,
+  resolvePageUrl,
+  resolveRecipeText,
+  resolveSafeProjectPaths,
+  resolvedAlt,
+  resolvedAnnotations,
+  sanitizeFileSegment,
+  sha256,
+  validateConfig,
+  validateManifest,
+  validateRecipe,
+  validateRecipeSemantics
+};