@tmlmt/cooklang-parser 3.0.0-alpha.14 → 3.0.0-alpha.15

package/dist/index.cjs

@@ -37,6 +37,7 @@ __export(index_exports, {
   NoProductCatalogForCartError: () => NoProductCatalogForCartError,
   NoShoppingListForCartError: () => NoShoppingListForCartError,
   NoTabAsIndentError: () => NoTabAsIndentError,
+  Pantry: () => Pantry,
   ProductCatalog: () => ProductCatalog,
   Recipe: () => Recipe,
   Section: () => Section,
@@ -120,7 +121,7 @@ var CategoryConfig = class {
   }
 };
 
-// src/classes/product_catalog.ts
+// src/classes/pantry.ts
 var import_smol_toml = __toESM(require("smol-toml"), 1);
 
 // node_modules/.pnpm/human-regex@2.2.0/node_modules/human-regex/dist/human-regex.esm.js
@@ -1017,21 +1018,6 @@ function hasAlternatives(entry) {
 }
 
 // src/quantities/mutations.ts
-function extendAllUnits(q) {
-  if (isAndGroup(q)) {
-    return { and: q.and.map(extendAllUnits) };
-  } else if (isOrGroup(q)) {
-    return { or: q.or.map(extendAllUnits) };
-  } else {
-    const newQ = {
-      quantity: q.quantity
-    };
-    if (q.unit) {
-      newQ.unit = { name: q.unit };
-    }
-    return newQ;
-  }
-}
 function normalizeAllUnits(q) {
   if (isAndGroup(q)) {
     return { and: q.and.map(normalizeAllUnits) };
@@ -1296,30 +1282,51 @@ var flattenPlainUnitGroup = (summed) => {
     }
   } else if (isAndGroup(summed)) {
     const andEntries = [];
+    const standaloneEntries = [];
     const equivalentsList = [];
     for (const entry of summed.and) {
       if (isOrGroup(entry)) {
         const orEntries = entry.or;
-        andEntries.push({
-          quantity: orEntries[0].quantity,
-          ...orEntries[0].unit && { unit: orEntries[0].unit }
-        });
-        equivalentsList.push(...orEntries.slice(1));
-      } else if (isQuantity(entry)) {
-        andEntries.push({
-          quantity: entry.quantity,
-          ...entry.unit && { unit: entry.unit }
+        const firstEntry = orEntries[0];
+        if (isAndGroup(firstEntry)) {
+          for (const nestedEntry of firstEntry.and) {
+            andEntries.push({
+              quantity: nestedEntry.quantity,
+              ...nestedEntry.unit && { unit: nestedEntry.unit }
+            });
+          }
+        } else {
+          const primary = firstEntry;
+          andEntries.push({
+            quantity: primary.quantity,
+            ...primary.unit && { unit: primary.unit }
+          });
+        }
+        const equivEntries = orEntries.slice(1).filter((e2) => isQuantity(e2));
+        equivalentsList.push(
+          ...equivEntries.map((e2) => ({
+            quantity: e2.quantity,
+            ...e2.unit && { unit: e2.unit }
+          }))
+        );
+      } else {
+        const simpleQuantityEntry = entry;
+        standaloneEntries.push({
+          quantity: simpleQuantityEntry.quantity,
+          ...simpleQuantityEntry.unit && { unit: simpleQuantityEntry.unit }
         });
       }
     }
     if (equivalentsList.length === 0) {
-      return andEntries;
+      return [...andEntries, ...standaloneEntries];
     }
-    const result = {
+    const result = [];
+    result.push({
       and: andEntries,
       equivalents: equivalentsList
-    };
-    return [result];
+    });
+    result.push(...standaloneEntries);
+    return result;
   } else {
     return [
       { quantity: summed.quantity, ...summed.unit && { unit: summed.unit } }
@@ -1373,6 +1380,24 @@ function applyBestUnit(q, system) {
     unit: { name: bestUnit.name }
   };
 }
+function subtractQuantities(q1, q2, options = {}) {
+  const { clampToZero = true, system } = options;
+  const negatedQ2 = {
+    ...q2,
+    quantity: multiplyQuantityValue(q2.quantity, -1)
+  };
+  const result = addQuantities(q1, negatedQ2, system);
+  if (clampToZero) {
+    const avg = getAverageValue(result.quantity);
+    if (typeof avg === "number" && avg < 0) {
+      return {
+        quantity: { type: "fixed", value: { type: "decimal", decimal: 0 } },
+        unit: result.unit
+      };
+    }
+  }
+  return result;
+}
 
 // src/utils/parser_helpers.ts
 function flushPendingNote(section, noteItems) {
@@ -1513,6 +1538,97 @@ function parseQuantityInput(input_str) {
   }
   return { type: "fixed", value: parseFixedValue(clean_str) };
 }
+function parseQuantityWithUnit(input) {
+  const trimmed = input.trim();
+  const separatorIndex = trimmed.indexOf("%");
+  if (separatorIndex === -1) {
+    return { value: parseQuantityInput(trimmed) };
+  }
+  const valuePart = trimmed.slice(0, separatorIndex).trim();
+  const unitPart = trimmed.slice(separatorIndex + 1).trim();
+  return {
+    value: parseQuantityInput(valuePart),
+    unit: unitPart || void 0
+  };
+}
+function parseDateFromFormat(input, format) {
+  const delimiterMatch = format.match(/[^A-Za-z]/);
+  if (!delimiterMatch) {
+    throw new Error(`Invalid date format: ${format}. No delimiter found.`);
+  }
+  const delimiter = delimiterMatch[0];
+  const formatParts = format.split(delimiter);
+  const inputParts = input.trim().split(delimiter);
+  if (formatParts.length !== 3 || inputParts.length !== 3) {
+    throw new Error(
+      `Invalid date input "${input}" for format "${format}". Expected 3 parts.`
+    );
+  }
+  let day = 0, month = 0, year = 0;
+  for (let i2 = 0; i2 < 3; i2++) {
+    const token = formatParts[i2].toUpperCase();
+    const value = parseInt(inputParts[i2], 10);
+    if (isNaN(value)) {
+      throw new Error(
+        `Invalid date input "${input}": non-numeric part "${inputParts[i2]}".`
+      );
+    }
+    if (token === "DD") day = value;
+    else if (token === "MM") month = value;
+    else if (token === "YYYY") year = value;
+    else
+      throw new Error(
+        `Unknown token "${formatParts[i2]}" in format "${format}"`
+      );
+  }
+  const date = new Date(year, month - 1, day);
+  if (date.getFullYear() !== year || date.getMonth() !== month - 1 || date.getDate() !== day) {
+    throw new Error(`Invalid date: "${input}" does not form a valid date.`);
+  }
+  return date;
+}
+function disambiguateDayMonth(first, second, year) {
+  if (second > 12 && first <= 12) {
+    return [second, first, year];
+  }
+  return [first, second, year];
+}
+function parseFuzzyDate(input) {
+  const trimmed = input.trim();
+  const delimiterMatch = trimmed.match(/[./-]/);
+  if (!delimiterMatch) {
+    throw new Error(`Cannot parse date "${input}": no delimiter found.`);
+  }
+  const delimiter = delimiterMatch[0];
+  const parts = trimmed.split(delimiter);
+  if (parts.length !== 3) {
+    throw new Error(
+      `Cannot parse date "${input}": expected 3 parts, got ${parts.length}.`
+    );
+  }
+  const nums = parts.map((p) => parseInt(p, 10));
+  if (nums.some((n2) => isNaN(n2))) {
+    throw new Error(`Cannot parse date "${input}": non-numeric parts found.`);
+  }
+  let day, month, year;
+  if (nums[0] >= 1e3) {
+    year = nums[0];
+    month = nums[1];
+    day = nums[2];
+  } else if (nums[2] >= 1e3) {
+    [day, month, year] = disambiguateDayMonth(nums[0], nums[1], nums[2]);
+  } else {
+    if (nums[2] >= 100)
+      throw new Error(`Invalid date: "${input}" does not form a valid date.`);
+    [day, month] = disambiguateDayMonth(nums[0], nums[1], 0);
+    year = 2e3 + nums[2];
+  }
+  const date = new Date(year, month - 1, day);
+  if (date.getFullYear() !== year || date.getMonth() !== month - 1 || date.getDate() !== day) {
+    throw new Error(`Invalid date: "${input}" does not form a valid date.`);
+  }
+  return date;
+}
 function parseMarkdownSegments(text) {
   const items = [];
   let cursor = 0;
@@ -1893,7 +2009,227 @@ function getAlternativeSignature(alternatives) {
   return alternatives.map((a2) => a2.index).sort((a2, b) => a2 - b).join(",");
 }
 
+// src/classes/pantry.ts
+var Pantry = class {
+  /**
+   * Creates a new Pantry instance.
+   * @param tomlContent - Optional TOML content to parse.
+   * @param options - Optional configuration options.
+   */
+  constructor(tomlContent, options = {}) {
+    /**
+     * The parsed pantry items.
+     */
+    __publicField(this, "items", []);
+    /**
+     * Options for date parsing and other configuration.
+     */
+    __publicField(this, "options");
+    /**
+     * Optional category configuration for alias-based lookups.
+     */
+    __publicField(this, "categoryConfig");
+    this.options = options;
+    if (tomlContent) {
+      this.parse(tomlContent);
+    }
+  }
+  /**
+   * Parses a TOML string into pantry items.
+   * @param tomlContent - The TOML string to parse.
+   * @returns The parsed list of pantry items.
+   */
+  parse(tomlContent) {
+    const raw = import_smol_toml.default.parse(tomlContent);
+    this.items = [];
+    for (const [location, locationData] of Object.entries(raw)) {
+      const locationTable = locationData;
+      for (const [itemName, itemData] of Object.entries(locationTable)) {
+        const item = this.parseItem(
+          itemName,
+          location,
+          itemData
+        );
+        this.items.push(item);
+      }
+    }
+    return this.items;
+  }
+  /**
+   * Parses a single pantry item from its TOML representation.
+   */
+  parseItem(name, location, data) {
+    const item = { name, location };
+    if (typeof data === "string") {
+      const parsed = parseQuantityWithUnit(data);
+      item.quantity = parsed.value;
+      if (parsed.unit) item.unit = parsed.unit;
+    } else {
+      if (data.quantity) {
+        const parsed = parseQuantityWithUnit(data.quantity);
+        item.quantity = parsed.value;
+        if (parsed.unit) item.unit = parsed.unit;
+      }
+      if (data.low) {
+        const parsed = parseQuantityWithUnit(data.low);
+        item.low = parsed.value;
+        if (parsed.unit) item.lowUnit = parsed.unit;
+      }
+      if (data.bought) {
+        item.bought = this.parseDate(data.bought);
+      }
+      if (data.expire) {
+        item.expire = this.parseDate(data.expire);
+      }
+    }
+    return item;
+  }
+  /**
+   * Parses a date string using the configured format or fuzzy detection.
+   */
+  parseDate(input) {
+    if (this.options.dateFormat) {
+      return parseDateFromFormat(input, this.options.dateFormat);
+    }
+    return parseFuzzyDate(input);
+  }
+  /**
+   * Sets a category configuration for alias-based item lookups.
+   * @param config - The category configuration to use.
+   */
+  setCategoryConfig(config) {
+    this.categoryConfig = config;
+  }
+  /**
+   * Finds a pantry item by name, using exact match first, then alias lookup
+   * via the stored CategoryConfig.
+   * @param name - The name to search for.
+   * @returns The matching pantry item, or undefined if not found.
+   */
+  findItem(name) {
+    const lowerName = name.toLowerCase();
+    const exact = this.items.find(
+      (item) => item.name.toLowerCase() === lowerName
+    );
+    if (exact) return exact;
+    if (this.categoryConfig) {
+      for (const category of this.categoryConfig.categories) {
+        for (const catIngredient of category.ingredients) {
+          if (catIngredient.aliases.some(
+            (alias) => alias.toLowerCase() === lowerName
+          )) {
+            const canonicalName = catIngredient.name.toLowerCase();
+            const byCanonical = this.items.find(
+              (item) => item.name.toLowerCase() === canonicalName
+            );
+            if (byCanonical) return byCanonical;
+            for (const alias of catIngredient.aliases) {
+              const byAlias = this.items.find(
+                (item) => item.name.toLowerCase() === alias.toLowerCase()
+              );
+              if (byAlias) return byAlias;
+            }
+          }
+        }
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Gets the numeric value of a pantry item's quantity, optionally converted to base units.
+   * Returns undefined if the quantity has a text value or is not set.
+   */
+  getItemNumericValue(quantity, unit) {
+    if (!quantity) return void 0;
+    let numericValue;
+    if (quantity.type === "fixed") {
+      if (quantity.value.type === "text") return void 0;
+      numericValue = getNumericValue(quantity.value);
+    } else {
+      numericValue = (getNumericValue(quantity.min) + getNumericValue(quantity.max)) / 2;
+    }
+    if (unit) {
+      const unitDef = normalizeUnit(unit);
+      if (unitDef) {
+        const toBase = getToBase(unitDef);
+        numericValue *= toBase;
+      }
+    }
+    return numericValue;
+  }
+  /**
+   * Returns all items that are depleted (quantity = 0) or below their low threshold.
+   * @returns An array of depleted pantry items.
+   */
+  getDepletedItems() {
+    return this.items.filter((item) => this.isItemLow(item));
+  }
+  /**
+   * Returns all items whose expiration date is within `nbDays` days from today
+   * (or already passed).
+   * @param nbDays - Number of days ahead to check. Defaults to 0 (already expired).
+   * @returns An array of expired pantry items.
+   */
+  getExpiredItems(nbDays = 0) {
+    return this.items.filter((item) => this.isItemExpired(item, nbDays));
+  }
+  /**
+   * Checks if a specific item is low (quantity = 0 or below `low` threshold).
+   * @param itemName - The name of the item to check (supports aliases if CategoryConfig is set).
+   * @returns true if the item is low, false otherwise. Returns false if item not found.
+   */
+  isLow(itemName) {
+    const item = this.findItem(itemName);
+    if (!item) return false;
+    return this.isItemLow(item);
+  }
+  /**
+   * Checks if a specific item is expired or expires within `nbDays` days.
+   * @param itemName - The name of the item to check (supports aliases if CategoryConfig is set).
+   * @param nbDays - Number of days ahead to check. Defaults to 0.
+   * @returns true if the item is expired, false otherwise. Returns false if item not found.
+   */
+  isExpired(itemName, nbDays = 0) {
+    const item = this.findItem(itemName);
+    if (!item) return false;
+    return this.isItemExpired(item, nbDays);
+  }
+  /**
+   * Internal: checks if a pantry item is low.
+   */
+  isItemLow(item) {
+    if (!item.quantity) return false;
+    const qtyValue = this.getItemNumericValue(item.quantity, item.unit);
+    if (qtyValue === void 0) return false;
+    if (qtyValue === 0) return true;
+    if (item.low) {
+      const lowValue = this.getItemNumericValue(item.low, item.lowUnit);
+      if (lowValue !== void 0 && qtyValue <= lowValue) return true;
+    }
+    return false;
+  }
+  /**
+   * Internal: checks if a pantry item is expired.
+   */
+  isItemExpired(item, nbDays) {
+    if (!item.expire) return false;
+    const now = /* @__PURE__ */ new Date();
+    const cutoff = new Date(
+      now.getFullYear(),
+      now.getMonth(),
+      now.getDate() + nbDays
+    );
+    const expireDay = new Date(
+      item.expire.getFullYear(),
+      item.expire.getMonth(),
+      item.expire.getDate()
+    );
+    return expireDay <= cutoff;
+  }
+};
+
 // src/classes/product_catalog.ts
+var import_smol_toml2 = __toESM(require("smol-toml"), 1);
 var ProductCatalog = class {
   constructor(tomlContent) {
     __publicField(this, "products", []);
@@ -1905,7 +2241,7 @@ var ProductCatalog = class {
    * @returns A parsed list of `ProductOption`.
    */
   parse(tomlContent) {
-    const catalogRaw = import_smol_toml.default.parse(tomlContent);
+    const catalogRaw = import_smol_toml2.default.parse(tomlContent);
     this.products = [];
     if (!this.isValidTomlContent(catalogRaw)) {
       throw new InvalidProductCatalogFormat();
@@ -1978,7 +2314,7 @@ var ProductCatalog = class {
         size: sizeStrings.length === 1 ? sizeStrings[0] : sizeStrings
       };
     }
-    return import_smol_toml.default.stringify(grouped);
+    return import_smol_toml2.default.stringify(grouped);
   }
   /**
    * Adds a product to the catalog.
@@ -2115,7 +2451,6 @@ function getEquivalentUnitsLists(...quantities) {
   const OrGroups = quantitiesCopy.filter(isOrGroup).filter((q) => q.or.length > 1);
   const unitLists = [];
   const normalizeOrGroup = (og) => ({
-    ...og,
     or: og.or.map((q) => ({
       ...q,
       unit: resolveUnit(q.unit?.name, q.unit?.integerProtected)
@@ -2796,34 +3131,10 @@ var _Recipe = class _Recipe {
       }
     }
   }
-  /**
-   * Gets ingredients with their quantities populated, optionally filtered by section/step
-   * and respecting user choices for alternatives.
-   *
-   * When no options are provided, returns all recipe ingredients with quantities
-   * calculated using primary alternatives (same as after parsing).
-   *
-   * @param options - Options for filtering and choice selection:
-   *   - `section`: Filter to a specific section (Section object or 0-based index)
-   *   - `step`: Filter to a specific step (Step object or 0-based index)
-   *   - `choices`: Choices for alternative ingredients (defaults to primary)
-   * @returns Array of Ingredient objects with quantities populated
-   *
-   * @example
-   * ```typescript
-   * // Get all ingredients with primary alternatives
-   * const ingredients = recipe.getIngredientQuantities();
-   *
-   * // Get ingredients for a specific section
-   * const sectionIngredients = recipe.getIngredientQuantities({ section: 0 });
-   *
-   * // Get ingredients with specific choices applied
-   * const withChoices = recipe.getIngredientQuantities({
-   *   choices: { ingredientItems: new Map([['ingredient-item-2', 1]]) }
-   * });
-   * ```
-   */
-  getIngredientQuantities(options) {
+  // Type for accumulated quantities (used internally by collectQuantityGroups)
+  // Defined as a static type alias for the private method's return type
+  /** @internal */
+  collectQuantityGroups(options) {
     const { section, step, choices } = options || {};
     const sectionsToProcess = section !== void 0 ? (() => {
       const idx = typeof section === "number" ? section : this.sections.indexOf(section);
@@ -2941,6 +3252,78 @@ var _Recipe = class _Recipe {
         }
       }
     }
+    return { ingredientGroups, selectedIndices, referencedIndices };
+  }
+  /**
+   * Gets the raw (unprocessed) quantity groups for each ingredient, before
+   * any summation or equivalents simplification. This is useful for cross-recipe
+   * aggregation (e.g., in {@link ShoppingList}), where quantities from multiple
+   * recipes should be combined before processing.
+   *
+   * @param options - Options for filtering and choice selection (same as {@link getIngredientQuantities}).
+   * @returns Array of {@link RawQuantityGroup} objects, one per ingredient with quantities.
+   *
+   * @example
+   * ```typescript
+   * const rawGroups = recipe.getRawQuantityGroups();
+   * // Each group has: name, usedAsPrimary, flags, quantities[]
+   * // quantities are the raw QuantityWithExtendedUnit or FlatOrGroup entries
+   * ```
+   */
+  getRawQuantityGroups(options) {
+    const { ingredientGroups, selectedIndices, referencedIndices } = this.collectQuantityGroups(options);
+    const result = [];
+    for (let index = 0; index < this.ingredients.length; index++) {
+      if (!referencedIndices.has(index)) continue;
+      const orig = this.ingredients[index];
+      const usedAsPrimary = selectedIndices.has(index);
+      const quantities = [];
+      if (usedAsPrimary) {
+        const groupsForIng = ingredientGroups.get(index);
+        if (groupsForIng) {
+          for (const [, group] of groupsForIng) {
+            quantities.push(...group.quantities);
+          }
+        }
+      }
+      result.push({
+        name: orig.name,
+        ...usedAsPrimary && { usedAsPrimary: true },
+        ...orig.flags && { flags: orig.flags },
+        quantities
+      });
+    }
+    return result;
+  }
+  /**
+   * Gets ingredients with their quantities populated, optionally filtered by section/step
+   * and respecting user choices for alternatives.
+   *
+   * When no options are provided, returns all recipe ingredients with quantities
+   * calculated using primary alternatives (same as after parsing).
+   *
+   * @param options - Options for filtering and choice selection:
+   *   - `section`: Filter to a specific section (Section object or 0-based index)
+   *   - `step`: Filter to a specific step (Step object or 0-based index)
+   *   - `choices`: Choices for alternative ingredients (defaults to primary)
+   * @returns Array of Ingredient objects with quantities populated
+   *
+   * @example
+   * ```typescript
+   * // Get all ingredients with primary alternatives
+   * const ingredients = recipe.getIngredientQuantities();
+   *
+   * // Get ingredients for a specific section
+   * const sectionIngredients = recipe.getIngredientQuantities({ section: 0 });
+   *
+   * // Get ingredients with specific choices applied
+   * const withChoices = recipe.getIngredientQuantities({
+   *   choices: { ingredientItems: new Map([['ingredient-item-2', 1]]) }
+   * });
+   * ```
+   */
+  getIngredientQuantities(options) {
+    const { ingredientGroups, selectedIndices, referencedIndices } = this.collectQuantityGroups(options);
     const result = [];
     for (let index = 0; index < this.ingredients.length; index++) {
       if (!referencedIndices.has(index)) continue;
@@ -3469,13 +3852,12 @@ __publicField(_Recipe, "itemCounts", /* @__PURE__ */ new WeakMap());
 var Recipe = _Recipe;
 
 // src/classes/shopping_list.ts
-var ShoppingList = class {
+var ShoppingList = class _ShoppingList {
   /**
    * Creates a new ShoppingList instance
    * @param categoryConfigStr - The category configuration to parse.
    */
   constructor(categoryConfigStr) {
-    // TODO: backport type change
     /**
      * The ingredients in the shopping list.
      */
@@ -3492,38 +3874,38 @@ var ShoppingList = class {
      * The categorized ingredients in the shopping list.
      */
     __publicField(this, "categories");
+    /**
+     * The unit system to use for quantity simplification.
+     * When set, overrides per-recipe unit systems.
+     */
+    __publicField(this, "unitSystem");
+    /**
+     * Per-ingredient equivalence ratio maps for recomputing equivalents
+     * after pantry subtraction. Keyed by ingredient name.
+     * @internal
+     */
+    __publicField(this, "equivalenceRatios", /* @__PURE__ */ new Map());
+    /**
+     * The original pantry (never mutated by recipe calculations).
+     */
+    __publicField(this, "pantry");
+    /**
+     * The pantry with quantities updated after subtracting recipe needs.
+     * Recomputed on every {@link ShoppingList.calculateIngredients | calculateIngredients()} call.
+     */
+    __publicField(this, "resultingPantry");
     if (categoryConfigStr) {
       this.setCategoryConfig(categoryConfigStr);
     }
   }
   calculateIngredients() {
     this.ingredients = [];
-    const addIngredientQuantity = (name, quantityTotal) => {
-      const quantityTotalExtended = extendAllUnits(quantityTotal);
-      const newQuantities = isAndGroup(quantityTotalExtended) ? quantityTotalExtended.and : [quantityTotalExtended];
-      const existing = this.ingredients.find((i2) => i2.name === name);
-      if (existing) {
-        if (!existing.quantityTotal) {
-          existing.quantityTotal = quantityTotal;
-          return;
-        }
-        try {
-          const existingQuantityTotalExtended = extendAllUnits(
-            existing.quantityTotal
-          );
-          const existingQuantities = isAndGroup(existingQuantityTotalExtended) ? existingQuantityTotalExtended.and : [existingQuantityTotalExtended];
-          existing.quantityTotal = addEquivalentsAndSimplify([
-            ...existingQuantities,
-            ...newQuantities
-          ]);
-          return;
-        } catch {
-        }
+    const rawQuantitiesMap = /* @__PURE__ */ new Map();
+    const nameOrder = [];
+    const trackName = (name) => {
+      if (!nameOrder.includes(name)) {
+        nameOrder.push(name);
       }
-      this.ingredients.push({
-        name,
-        quantityTotal
-      });
     };
     for (const addedRecipe of this.recipes) {
       let scaledRecipe;
@@ -3533,48 +3915,253 @@ var ShoppingList = class {
       } else {
         scaledRecipe = addedRecipe.recipe.scaleTo(addedRecipe.servings);
       }
-      const ingredients = scaledRecipe.getIngredientQuantities({
+      const rawGroups = scaledRecipe.getRawQuantityGroups({
         choices: addedRecipe.choices
       });
-      for (const ingredient of ingredients) {
-        if (ingredient.flags && ingredient.flags.includes("hidden")) {
+      for (const group of rawGroups) {
+        if (group.flags?.includes("hidden") || !group.usedAsPrimary) {
           continue;
         }
-        if (!ingredient.usedAsPrimary) {
-          continue;
+        trackName(group.name);
+        if (group.quantities.length > 0) {
+          const existing = rawQuantitiesMap.get(group.name) ?? [];
+          existing.push(...group.quantities);
+          rawQuantitiesMap.set(group.name, existing);
         }
-        if (ingredient.quantities && ingredient.quantities.length > 0) {
-          const allQuantities = [];
-          for (const qGroup of ingredient.quantities) {
-            if ("and" in qGroup) {
-              for (const qty of qGroup.and) {
-                allQuantities.push(qty);
+      }
+    }
+    this.equivalenceRatios.clear();
+    for (const name of nameOrder) {
+      const rawQuantities = rawQuantitiesMap.get(name);
+      if (!rawQuantities || rawQuantities.length === 0) {
+        this.ingredients.push({ name });
+        continue;
+      }
+      const textEntries = [];
+      const numericEntries = [];
+      for (const q of rawQuantities) {
+        if ("quantity" in q && q.quantity.type === "fixed" && q.quantity.value.type === "text") {
+          textEntries.push(q);
+        } else {
+          numericEntries.push(q);
+        }
+      }
+      if (numericEntries.length > 1) {
+        const ratioMap = _ShoppingList.buildEquivalenceRatioMap(
+          getEquivalentUnitsLists(...numericEntries)
+        );
+        if (Object.keys(ratioMap).length > 0) {
+          this.equivalenceRatios.set(name, ratioMap);
+        }
+      }
+      const resultQuantities = [];
+      for (const t2 of textEntries) {
+        resultQuantities.push(toPlainUnit(t2));
+      }
+      if (numericEntries.length > 0) {
+        resultQuantities.push(
+          ...flattenPlainUnitGroup(
+            addEquivalentsAndSimplify(numericEntries, this.unitSystem)
+          )
+        );
+      }
+      this.ingredients.push({
+        name,
+        quantities: resultQuantities
+      });
+    }
+    this.applyPantrySubtraction();
+  }
+  /**
+   * Subtracts pantry item quantities from calculated ingredient quantities
+   * and updates the resultingPantry to reflect consumed stock.
+   */
+  applyPantrySubtraction() {
+    if (!this.pantry) {
+      this.resultingPantry = void 0;
+      return;
+    }
+    const clonedPantry = new Pantry();
+    clonedPantry.items = deepClone(this.pantry.items);
+    if (this.categoryConfig) {
+      clonedPantry.setCategoryConfig(this.categoryConfig);
+    }
+    for (const ingredient of this.ingredients) {
+      if (!ingredient.quantities || ingredient.quantities.length === 0)
+        continue;
+      const pantryItem = clonedPantry.findItem(ingredient.name);
+      if (!pantryItem || !pantryItem.quantity) continue;
+      let pantryExtended = {
+        quantity: pantryItem.quantity,
+        ...pantryItem.unit && { unit: { name: pantryItem.unit } }
+      };
+      for (let i2 = 0; i2 < ingredient.quantities.length; i2++) {
+        const entry = ingredient.quantities[i2];
+        const leaves = "and" in entry ? entry.and : [entry];
+        for (const leaf of leaves) {
+          const ingredientExtended = toExtendedUnit(leaf);
+          const leafHasUnit = leaf.unit !== void 0 && leaf.unit !== "";
+          const pantryHasUnit = pantryExtended.unit !== void 0 && pantryExtended.unit.name !== "";
+          const ratioMap = this.equivalenceRatios.get(ingredient.name);
+          const unitMismatch = leafHasUnit !== pantryHasUnit && ratioMap !== void 0;
+          if (unitMismatch) {
+            const leafUnit = leaf.unit ?? NO_UNIT;
+            const pantryUnit = pantryExtended.unit?.name ?? NO_UNIT;
+            const ratioFromPantry = ratioMap[leafUnit]?.[pantryUnit];
+            if (ratioFromPantry !== void 0) {
+              const pantryValue = getAverageValue(pantryExtended.quantity);
+              const leafValue = getAverageValue(ingredientExtended.quantity);
+              if (typeof pantryValue === "number" && typeof leafValue === "number") {
+                const pantryInLeafUnits = pantryValue * ratioFromPantry;
+                const subtracted = Math.min(pantryInLeafUnits, leafValue);
+                const remainingLeafValue = Math.max(
+                  leafValue - pantryInLeafUnits,
+                  0
+                );
+                leaf.quantity = {
+                  type: "fixed",
+                  value: { type: "decimal", decimal: remainingLeafValue }
+                };
+                const consumedInPantryUnits = ratioFromPantry !== 0 ? subtracted / ratioFromPantry : pantryValue;
+                const remainingPantryValue = Math.max(
+                  pantryValue - consumedInPantryUnits,
+                  0
+                );
+                pantryExtended = {
+                  quantity: {
+                    type: "fixed",
+                    value: {
+                      type: "decimal",
+                      decimal: remainingPantryValue
+                    }
+                  },
+                  ...pantryExtended.unit && { unit: pantryExtended.unit }
+                };
+                continue;
               }
-            } else {
-              const plainQty = {
-                quantity: qGroup.quantity
-              };
-              if (qGroup.unit) plainQty.unit = qGroup.unit;
-              if (qGroup.equivalents) plainQty.equivalents = qGroup.equivalents;
-              allQuantities.push(plainQty);
             }
           }
-          if (allQuantities.length === 1) {
-            addIngredientQuantity(ingredient.name, allQuantities[0]);
-          } else {
-            const extendedQuantities = allQuantities.map(
-              (q) => extendAllUnits(q)
+          try {
+            const remaining = subtractQuantities(
+              ingredientExtended,
+              pantryExtended,
+              { clampToZero: true }
+            );
+            const consumed = subtractQuantities(
+              pantryExtended,
+              ingredientExtended,
+              { clampToZero: true }
+            );
+            pantryExtended = consumed;
+            const updated = toPlainUnit(remaining);
+            leaf.quantity = updated.quantity;
+            leaf.unit = updated.unit;
+          } catch {
+          }
+        }
+        if ("and" in entry) {
+          const nonZero = entry.and.filter(
+            (leaf) => leaf.quantity.type !== "fixed" || leaf.quantity.value.type !== "decimal" || leaf.quantity.value.decimal !== 0
+          );
+          entry.and.length = 0;
+          entry.and.push(...nonZero);
+          const ratioMap = this.equivalenceRatios.get(ingredient.name);
+          if (entry.equivalents && ratioMap) {
+            const equivUnits = entry.equivalents.map((e2) => e2.unit ?? NO_UNIT);
+            entry.equivalents = _ShoppingList.recomputeEquivalents(
+              entry.and,
+              ratioMap,
+              equivUnits
+            );
+          }
+          if (entry.and.length === 1) {
+            const single = entry.and[0];
+            ingredient.quantities[i2] = {
+              quantity: single.quantity,
+              ...single.unit && { unit: single.unit },
+              ...entry.equivalents && { equivalents: entry.equivalents },
+              ...entry.alternatives && { alternatives: entry.alternatives }
+            };
+          }
+        } else if ("equivalents" in entry && entry.equivalents) {
+          const ratioMap = this.equivalenceRatios.get(ingredient.name);
+          if (ratioMap) {
+            const equivUnits = entry.equivalents.map(
+              (e2) => e2.unit ?? NO_UNIT
             );
-            const totalQuantity = addEquivalentsAndSimplify(
-              extendedQuantities
+            const recomputed = _ShoppingList.recomputeEquivalents(
+              [entry],
+              ratioMap,
+              equivUnits
             );
-            addIngredientQuantity(ingredient.name, totalQuantity);
+            entry.equivalents = recomputed;
           }
-        } else if (!this.ingredients.some((i2) => i2.name === ingredient.name)) {
-          this.ingredients.push({ name: ingredient.name });
         }
       }
+      ingredient.quantities = ingredient.quantities.filter((entry) => {
+        if ("and" in entry) return entry.and.length > 0;
+        return !(entry.quantity.type === "fixed" && entry.quantity.value.type === "decimal" && entry.quantity.value.decimal === 0);
+      });
+      if (ingredient.quantities.length === 0) {
+        ingredient.quantities = void 0;
+      }
+      pantryItem.quantity = pantryExtended.quantity;
+      if (pantryExtended.unit) {
+        pantryItem.unit = pantryExtended.unit.name;
+      }
     }
+    this.resultingPantry = clonedPantry;
+  }
+  /**
+   * Builds a ratio map from equivalence lists.
+   * For each equivalence list, stores ratio = equiv_value / primary_value
+   * for every pair of units, so equivalents can be recomputed after
+   * pantry subtraction modifies primary quantities.
+   */
+  static buildEquivalenceRatioMap(unitsLists) {
+    const ratioMap = {};
+    for (const list of unitsLists) {
+      for (const equiv of list) {
+        const equivValue = getAverageValue(equiv.quantity);
+        for (const primary of list) {
+          if (primary === equiv) continue;
+          const primaryValue = getAverageValue(primary.quantity);
+          const equivUnit = equiv.unit.name;
+          const primaryUnit = primary.unit.name;
+          ratioMap[equivUnit] ?? (ratioMap[equivUnit] = {});
+          ratioMap[equivUnit][primaryUnit] = equivValue / primaryValue;
+        }
+      }
+    }
+    return ratioMap;
+  }
+  /**
+   * Recomputes equivalent quantities from current primary values and stored ratios.
+   * For each equivalent unit in equivUnits, new_value = Σ (primary_value × ratio[equivUnit][primaryUnit]).
+   * Returns undefined if all equivalents compute to zero.
+   */
+  static recomputeEquivalents(primaries, ratioMap, equivUnits) {
+    const equivalents = [];
+    for (const equivUnit of equivUnits) {
+      const ratios = ratioMap[equivUnit];
+      let total = 0;
+      for (const primary of primaries) {
+        const pUnit = primary.unit ?? NO_UNIT;
+        const ratio = ratios[pUnit];
+        const pValue = getAverageValue(primary.quantity);
+        total += pValue * ratio;
+      }
+      if (total > 0) {
+        equivalents.push({
+          quantity: {
+            type: "fixed",
+            value: { type: "decimal", decimal: total }
+          },
+          ...equivUnit !== "" && { unit: equivUnit }
+        });
+      }
+    }
+    return equivalents.length > 0 ? equivalents : void 0;
   }
   /**
    * Adds a recipe to the shopping list, then automatically
@@ -3663,9 +4250,41 @@ var ShoppingList = class {
     this.calculateIngredients();
     this.categorize();
   }
+  /**
+   * Adds a pantry to the shopping list. On-hand pantry quantities will be
+   * subtracted from recipe ingredient needs on each recalculation.
+   * @param pantry - A Pantry instance or a TOML string to parse.
+   * @param options - Options for pantry parsing (only used when providing a TOML string).
+   */
+  addPantry(pantry, options) {
+    if (typeof pantry === "string") {
+      this.pantry = new Pantry(pantry, options);
+    } else if (pantry instanceof Pantry) {
+      this.pantry = pantry;
+    } else {
+      throw new Error(
+        "Invalid pantry: expected a Pantry instance or TOML string"
+      );
+    }
+    if (this.categoryConfig) {
+      this.pantry.setCategoryConfig(this.categoryConfig);
+    }
+    this.calculateIngredients();
+    this.categorize();
+  }
+  /**
+   * Returns the resulting pantry with quantities updated to reflect
+   * what was consumed by the shopping list's recipes.
+   * Returns undefined if no pantry was added.
+   * @returns The resulting Pantry, or undefined.
+   */
+  getPantry() {
+    return this.resultingPantry;
+  }
   /**
    * Sets the category configuration for the shopping list
    * and automatically categorize current ingredients from the list.
+   * Also propagates the configuration to the pantry if one is set.
    * @param config - The category configuration to parse.
    */
   setCategoryConfig(config) {
@@ -3673,6 +4292,9 @@ var ShoppingList = class {
       this.categoryConfig = new CategoryConfig(config);
     else if (config instanceof CategoryConfig) this.categoryConfig = config;
     else throw new Error("Invalid category configuration");
+    if (this.pantry) {
+      this.pantry.setCategoryConfig(this.categoryConfig);
+    }
     this.categorize();
   }
   /**
@@ -3817,8 +4439,27 @@ var ShoppingCart = class {
   getOptimumMatch(ingredient, options) {
     if (options.length === 0)
       throw new NoProductMatchError(ingredient.name, "noProduct");
-    if (!ingredient.quantityTotal)
+    if (!ingredient.quantities || ingredient.quantities.length === 0)
       throw new NoProductMatchError(ingredient.name, "noQuantity");
+    const allPlainEntries = [];
+    for (const q of ingredient.quantities) {
+      if ("and" in q) {
+        allPlainEntries.push({ and: q.and });
+      } else {
+        const entry = {
+          quantity: q.quantity,
+          ...q.unit && { unit: q.unit },
+          ...q.equivalents && { equivalents: q.equivalents }
+        };
+        allPlainEntries.push(entry);
+      }
+    }
+    let quantityTotal;
+    if (allPlainEntries.length === 1) {
+      quantityTotal = allPlainEntries[0];
+    } else {
+      quantityTotal = { and: allPlainEntries };
+    }
     const normalizedOptions = options.map(
       (option) => ({
         ...option,
@@ -3834,7 +4475,7 @@ var ShoppingCart = class {
         })
       })
     );
-    const normalizedQuantityTotal = normalizeAllUnits(ingredient.quantityTotal);
+    const normalizedQuantityTotal = normalizeAllUnits(quantityTotal);
     function getOptimumMatchForQuantityParts(normalizedQuantities, normalizedOptions2, selection = []) {
       if (isAndGroup(normalizedQuantities)) {
         for (const q of normalizedQuantities.and) {
@@ -4062,6 +4703,7 @@ function isAlternativeSelected(recipe, choices, item, alternativeIndex) {
   NoProductCatalogForCartError,
   NoShoppingListForCartError,
   NoTabAsIndentError,
+  Pantry,
   ProductCatalog,
   Recipe,
   Section,
@@ -4088,6 +4730,9 @@ function isAlternativeSelected(recipe, choices, item, alternativeIndex) {
 // v8 ignore else -- @preserve
 // v8 ignore if -- @preserve
 /* v8 ignore else -- expliciting error type -- @preserve */
+// v8 ignore if -- @preserve: defensive type guard
 /* v8 ignore if -- @preserve */
 // v8 ignore next -- @preserve
+// v8 ignore else --@preserve: defensive type guard
+// v8 ignore else -- @preserve: detection if
 //# sourceMappingURL=index.cjs.map