@tmlmt/cooklang-parser 3.0.0-alpha.8 → 3.0.0-elpha.22

package/dist/index.d.ts

@@ -16,11 +16,17 @@ declare class Section {
     name: string;
     /** An array of steps and notes that make up the content of the section. */
     content: (Step | Note)[];
+    /** Optional list of variant names this section belongs to. */
+    variants?: string[];
+    /** Whether the section has been marked as optional ([?]) */
+    optional?: boolean;
     /**
      * Creates an instance of Section.
      * @param name - The name of the section. Defaults to an empty string.
+     * @param variants - Optional variant names for this section.
+     * @param optional - Whether the section is optional.
      */
-    constructor(name?: string);
+    constructor(name?: string, variants?: string[], optional?: boolean);
     /**
      * Checks if the section is blank (has no name and no content).
      * Used during recipe parsing
@@ -66,8 +72,7 @@ declare class Recipe {
      */
     metadata: Metadata;
     /**
-     * The default or manual choice of alternative ingredients.
-     * Contains the full context including alternatives list and active selection index.
+     * The possible choices of alternative ingredients for this recipe.
      */
     choices: RecipeAlternatives;
     /**
@@ -98,11 +103,28 @@ declare class Recipe {
      * @see {@link Recipe.scaleBy | scaleBy()} and {@link Recipe.scaleTo | scaleTo()} methods
      */
     servings?: number;
+    /**
+     * Gets the unit system specified in the recipe metadata.
+     * Used for resolving ambiguous units like tsp, tbsp, cup, etc.
+     *
+     * @returns The unit system if specified, or undefined to use defaults
+     */
+    get unitSystem(): SpecificUnitSystem | undefined;
+    /**
+     * External storage for unit system (not a property on instances).
+     * Used for resolving ambiguous units during quantity addition.
+     */
+    private static unitSystems;
     /**
      * External storage for item count (not a property on instances).
      * Used for giving ID numbers to items during parsing.
      */
     private static itemCounts;
+    /**
+     * External storage for subgroup index tracking during parsing.
+     * Maps groupKey → subgroupKey → index within the subgroups array.
+     */
+    private static subgroupIndices;
     /**
      * Gets the current item count for this recipe.
      */
@@ -143,16 +165,73 @@ declare class Recipe {
      * Quantities are grouped by their alternative signature and summed using addEquivalentsAndSimplify.
      * @internal
      */
-    private _populate_ingredient_quantities;
+    private _populateIngredientQuantities;
+    /** @internal */
+    private collectQuantityGroups;
     /**
-     * Calculates ingredient quantities based on the provided choices.
-     * Returns a list of computed ingredients with their total quantities.
+     * 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 choices - The recipe choices to apply when computing quantities.
-     *   If not provided, uses the default choices (first alternative for each item).
-     * @returns An array of ComputedIngredient with quantityTotal calculated based on choices.
+     * @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
+     * ```
      */
-    calc_ingredient_quantities(choices?: RecipeChoices): ComputedIngredient[];
+    getRawQuantityGroups(options?: GetIngredientQuantitiesOptions): RawQuantityGroup[];
+    /**
+     * 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?: GetIngredientQuantitiesOptions): Ingredient[];
+    /**
+     * Returns the list of cookware items that are used in the active variant.
+     * Cookware in steps/sections not matching the active variant are excluded.
+     * Hidden cookware is always excluded.
+     *
+     * @param options - Options for filtering:
+     *   - `choices`: The choices to apply (only `variant` is used)
+     * @returns Array of Cookware objects referenced by active steps
+     *
+     * @example
+     * ```typescript
+     * // Get all cookware for the default variant
+     * const cookware = recipe.getCookwareForVariant();
+     *
+     * // Get cookware for a specific variant
+     * const veganCookware = recipe.getCookwareForVariant({ choices: { variant: 'vegan' } });
+     * ```
+     */
+    getCookwareForVariant(options?: Pick<GetIngredientQuantitiesOptions, "choices">): Cookware[];
     /**
      * Parses a recipe from a string.
      * @param content - The recipe content to parse.
@@ -174,6 +253,26 @@ declare class Recipe {
      * @returns A new Recipe instance with the scaled ingredients.
      */
     scaleBy(factor: number | Big): Recipe;
+    /**
+     * Converts all ingredient quantities in the recipe to a target unit system.
+     *
+     * @param system - The target unit system to convert to (metric, US, UK, JP)
+     * @param method - How to handle existing quantities:
+     *   - "keep": Keep all existing equivalents (swap if needed, or add converted)
+     *   - "replace": Replace primary with target system quantity, discard equivalent used for conversion
+     *   - "remove": Only keep target system quantity, delete all equivalents
+     * @returns A new Recipe instance with converted quantities
+     *
+     * @example
+     * ```typescript
+     * // Convert a recipe to metric, keeping original units as equivalents
+     * const metricRecipe = recipe.convertTo("metric", "keep");
+     *
+     * // Convert to US units, removing all other equivalents
+     * const usRecipe = recipe.convertTo("US", "remove");
+     * ```
+     */
+    convertTo(system: SpecificUnitSystem, method: "keep" | "replace" | "remove"): Recipe;
     /**
      * Gets the number of servings for the recipe.
      * @private
@@ -187,6 +286,55 @@ declare class Recipe {
     clone(): Recipe;
 }
 
+/**
+ * Represents source attribution information for a recipe.
+ * @category Types
+ */
+interface MetadataSource {
+    /** The name of the source (e.g., "New York Times Cooking"). */
+    name?: string;
+    /** The URL of the source recipe. */
+    url?: string;
+    /** The author at the source. */
+    author?: string;
+}
+/**
+ * Represents a yield metadata value for a recipe.
+ * Supports plain quantities (e.g. `yield: 300%g`), complex format with
+ * surrounding text (e.g. `yield: about {{300%g}} of bread`), or simple
+ * numbers (e.g. `yield: 2`).
+ * @category Types
+ */
+interface Yield extends QuantityWithPlainUnit {
+    /** The text before the scaling variable (complex `{{}}` format). */
+    textBefore?: string;
+    /** The text after the scaling variable (complex `{{}}` format). */
+    textAfter?: string;
+}
+/**
+ * Represents time information for a recipe.
+ * @category Types
+ */
+interface MetadataTime {
+    /** The preparation time (not parsed into DateTime format). */
+    prep?: string;
+    /** The cooking time (not parsed into DateTime format). */
+    cook?: string;
+    /** The total time required (not parsed into DateTime format). */
+    total?: string;
+}
+/**
+ * Represents a nested metadata object with arbitrary keys.
+ * @category Types
+ */
+interface MetadataObject {
+    [key: string]: MetadataValue;
+}
+/**
+ * Represents any value that can appear in recipe metadata.
+ * @category Types
+ */
+type MetadataValue = string | number | (string | number)[] | MetadataObject | MetadataSource | MetadataTime | Yield | undefined;
 /**
  * Represents the metadata of a recipe.
  * @category Types
@@ -196,56 +344,60 @@ interface Metadata {
     title?: string;
     /** The tags of the recipe. */
     tags?: string[];
-    /** The source of the recipe. */
-    source?: string;
-    /** The source name of the recipe. */
-    "source.name"?: string;
-    /** The source url of the recipe. */
-    "source.url"?: string;
-    /** The source author of the recipe. */
-    "source.author"?: string;
-    /** The author of the recipe. */
+    /**
+     * The source of the recipe. Can be a simple URL string or structured attribution.
+     * When parsed from YAML, `source.name`, `source.url`, `source.author` keys are merged here.
+     */
+    source?: string | MetadataSource;
+    /** The author of the recipe (separate from source author). */
     author?: string;
     /** The number of servings the recipe makes.
-     * Should be either a number or a string which starts with a number
-     * (which will be used for scaling) followed by a comma and then
-     * whatever you want.
+     * Stored as a number when the value is numeric, or as a string when non-numeric
+     * (e.g. `servings: two`). Non-numeric values default the internal scaling baseline to 1.
      *
-     * Interchangeable with `yield` or `serves`. If multiple ones are defined,
-     * the prevailance order for the number which will used for scaling
-     * is `servings` \> `yield` \> `serves`.
+     * Interchangeable with `yield` or `serves` for the purpose of setting
+     * {@link Recipe.servings}. If multiple ones are defined, the prevalence
+     * order is `servings` \> `serves` \> `yield`.
      *
      * @example
      * ```yaml
      * servings: 4
      * ```
+     */
+    servings?: number | string;
+    /** The yield of the recipe.
+     * Can be given as:
+     * - a plain quantity with optional unit: `yield: 300%g` or `yield: 2`
+     * - a complex format with `{{}}` and optional surrounding text:
+     *   `yield: about {{300%g}} of bread`
+     *
+     * Interchangeable with `servings` or `serves` for the purpose of setting
+     * {@link Recipe.servings}. If multiple ones are defined, the prevalence
+     * order is `servings` \> `serves` \> `yield`.
      *
      * @example
      * ```yaml
-     * servings: 2, a few
+     * yield: 300%g
      * ```
-     */
-    servings?: number | string;
-    /** The yield of the recipe.
-     * Should be either a number or a string which starts with a number
-     * (which will be used for scaling) followed by a comma and then
-     * whatever you want.
      *
-     * Interchangeable with `servings` or `serves`. If multiple ones are defined,
-     * the prevailance order for the number which will used for scaling
-     * is `servings` \> `yield` \> `serves`. See {@link Metadata.servings | servings}
-     * for examples.
+     * @example
+     * ```yaml
+     * yield: about {{300%g}} of bread
+     * ```
      */
-    yield?: number | string;
+    yield?: Yield;
     /** The number of people the recipe serves.
-     * Should be either a number or a string which starts with a number
-     * (which will be used for scaling) followed by a comma and then
-     * whatever you want.
+     * Stored as a number when the value is numeric, or as a string when non-numeric
+     * (e.g. `serves: two`). Non-numeric values default the internal scaling baseline to 1.
+     *
+     * Interchangeable with `servings` or `yield` for the purpose of setting
+     * {@link Recipe.servings}. If multiple ones are defined, the prevalence
+     * order is `servings` \> `serves` \> `yield`.
      *
-     * Interchangeable with `servings` or `yield`. If multiple ones are defined,
-     * the prevailance order for the number which will used for scaling
-     * is `servings` \> `yield` \> `serves`. See {@link Metadata.servings | servings}
-     * for examples.
+     * @example
+     * ```yaml
+     * serves: 4
+     * ```
      */
     serves?: number | string;
     /** The course of the recipe. */
@@ -255,30 +407,11 @@ interface Metadata {
     /** The locale of the recipe. */
     locale?: string;
     /**
-     *  The preparation time of the recipe.
-     *  Will not be further parsed into any DateTime format nor normalize
-     */
-    "prep time"?: string;
-    /**
-     *  Alias of `prep time`
-     */
-    "time.prep"?: string;
-    /**
-     *  The cooking time of the recipe.
-     *  Will not be further parsed into any DateTime format nor normalize
-     */
-    "cook time"?: string;
-    /**
-     *  Alias of `cook time`
+     * Time information for the recipe.
+     * When parsed from YAML, `prep time`, `time.prep`, `cook time`, `time.cook`,
+     * `time required`, `time`, `duration` keys are merged here.
      */
-    "time.cook"?: string;
-    /**
-     *  The total time of the recipe.
-     *  Will not be further parsed into any DateTime format nor normalize
-     */
-    "time required"?: string;
-    time?: string;
-    duration?: string;
+    time?: MetadataTime;
     /** The difficulty of the recipe. */
     difficulty?: string;
     /** The cuisine of the recipe. */
@@ -287,16 +420,25 @@ interface Metadata {
     diet?: string;
     /** The description of the recipe. */
     description?: string;
-    /** The images of the recipe. Alias of `pictures` */
+    /** The images of the recipe. */
     images?: string[];
-    /** The images of the recipe. Alias of `images` */
-    pictures?: string[];
-    /** The picture of the recipe. Alias of `picture` */
+    /** The primary image of the recipe. */
     image?: string;
-    /** The picture of the recipe. Alias of `image` */
-    picture?: string;
     /** The introduction of the recipe. */
     introduction?: string;
+    /**
+     * The unit system used in the recipe for ambiguous units like tsp, tbsp, cup.
+     * See [Unit Conversion Guide](/guide-unit-conversion) for more information.
+     * This stores the original value as written by the user.
+     */
+    unitSystem?: string;
+    /** The list of available variant names for this recipe. */
+    variants?: string[];
+    /**
+     * Index signature for additional metadata fields not explicitly typed.
+     * Any metadata key in the frontmatter will be captured here.
+     */
+    [key: string]: MetadataValue;
 }
 /**
  * Represents a quantity described by text, e.g. "a pinch"
@@ -367,7 +509,7 @@ interface IngredientExtras {
      * Used if: the ingredient is a recipe
      *
      * @example
-     * ```cooklang
+     * ```yaml
      * Take @./essentials/doughs/pizza dough{1} out of the freezer and let it unfreeze overnight
      * ```
      * Would lead to:
@@ -399,30 +541,31 @@ interface AlternativeIngredientRef {
 interface IngredientQuantityGroup extends QuantityWithPlainUnit {
     /**
      * References to alternative ingredients for this quantity group.
+     * Each inner array represents one alternative choice option (subgroup).
+     * Items within the same inner array are combined with "+" (AND),
+     * while different inner arrays represent "or" alternatives.
      * If undefined, this group has no alternatives.
      */
-    alternatives?: AlternativeIngredientRef[];
+    alternatives?: AlternativeIngredientRef[][];
 }
 /**
  * Represents an AND group of quantities when primary units are incompatible but equivalents can be summed.
- * For example: 1 large carrot + 2 small carrots, both with cup equivalents that sum to 5 cups.
+ * For example: 1 large carrot + 2 small carrots, both with cup equivalents (resp. 2 cup and 1.5 cup) that sum to 5 cups.
  * @category Types
  */
-interface IngredientQuantityAndGroup {
-    type: "and";
-    /**
-     * The incompatible primary quantities (e.g., "1 large" and "2 small").
-     */
-    entries: QuantityWithPlainUnit[];
+interface IngredientQuantityAndGroup extends FlatAndGroup<QuantityWithPlainUnit> {
     /**
      * The summed equivalent quantities (e.g., "5 cups" from summing "1.5 cup + 2 cup + 1.5 cup").
      */
     equivalents?: QuantityWithPlainUnit[];
     /**
      * References to alternative ingredients for this quantity group.
+     * Each inner array represents one alternative choice option (subgroup).
+     * Items within the same inner array are combined with "+" (AND),
+     * while different inner arrays represent "or" alternatives.
      * If undefined, this group has no alternatives.
      */
-    alternatives?: AlternativeIngredientRef[];
+    alternatives?: AlternativeIngredientRef[][];
 }
 /**
  * Represents an ingredient in a recipe.
@@ -458,49 +601,40 @@ interface Ingredient {
     extras?: IngredientExtras;
 }
 /**
- * Represents a computed ingredient with its total quantity after applying choices.
- * Used as the return type of {@link Recipe.calc_ingredient_quantities}.
+ * Represents a quantity with extended unit and additional information
+ * about its scalability and potential equivalents
+ *
  * @category Types
  */
-interface ComputedIngredient {
-    /** The name of the ingredient. */
-    name: string;
-    /** The total quantity of the ingredient after applying choices. */
-    quantityTotal?: QuantityWithPlainUnit | MaybeNestedGroup<QuantityWithPlainUnit>;
-    /** The preparation of the ingredient. */
-    preparation?: string;
-    /** The list of ingredients mentioned in the preparation as alternatives to this ingredient */
-    alternatives?: Set<number>;
-    /** A list of potential state modifiers or other flags for the ingredient */
-    flags?: IngredientFlag[];
-    /** The collection of potential additional metadata for the ingredient */
-    extras?: IngredientExtras;
-}
+type MaybeScalableQuantity = QuantityWithExtendedUnit & {
+    /** Indicates whether this quantity should be scaled when the recipe serving size changes. */
+    scalable: boolean;
+    /** A list of equivalent quantities/units for this ingredient mention besides the primary quantity.
+     * For `@salt{1%tsp|5%g}`, the main quantity is 1 tsp and the equivalents will contain 5 g. */
+    equivalents?: QuantityWithExtendedUnit[];
+};
 /**
- * Represents a contributor to an ingredient's total quantity, corresponding
- * to a single mention in the recipe text. It can contain multiple
- * equivalent quantities (e.g., in different units).
+ * Defines a type containing an optional {@link QuantityWithExtendedUnit} with scalability and potential info about equivalents
+ *
+ * Used in {@link IngredientAlternative}
+ *
+ * @param T - The base type to which the optional quantity properties will be added.
+ *
  * @category Types
  */
-interface IngredientItemQuantity extends QuantityWithExtendedUnit {
-    /**
-     * A list of equivalent quantities/units for this ingredient mention besides the primary quantity.
-     * For `@salt{1%tsp|5%g}`, the main quantity is 1 tsp and the equivalents will contain 5 g.
-     */
-    equivalents?: QuantityWithExtendedUnit[];
-    /** Indicates whether this quantity should be scaled when the recipe serving size changes. */
-    scalable: boolean;
-}
+type WithOptionalQuantity<T> = (T & MaybeScalableQuantity) | (T & {
+    quantity?: undefined;
+    scalable?: never;
+    unit?: never;
+    equivalents?: never;
+});
 /**
- * Represents a single ingredient choice within a single or a group of `IngredientItem`s. It points
- * to a specific ingredient and its corresponding quantity information.
+ * Base type of {@link IngredientAlternative}
  * @category Types
  */
-interface IngredientAlternative {
+type IngredientAlternativeBase = {
     /** The index of the ingredient within the {@link Recipe.ingredients} array. */
     index: number;
-    /** The quantity of this specific mention of the ingredient */
-    itemQuantity?: IngredientItemQuantity;
     /** The alias/name of the ingredient as it should be displayed for this occurrence. */
     displayName: string;
     /** An optional note for this specific choice (e.g., "for a vegan version"). */
@@ -509,7 +643,16 @@ interface IngredientAlternative {
      * with group keys: the id of the corresponding ingredient item (e.g. "ingredient-item-2").
      * Can be useful for creating alternative selection UI elements with anchor links */
     itemId?: string;
-}
+};
+/**
+ * Represents a single ingredient choice within a single or a group of `IngredientItem`s. It points
+ * to a specific ingredient and its corresponding quantity information.
+ *
+ * Used in {@link IngredientItem} and for the various maps of {@link RecipeAlternatives}
+ *
+ * @category Types
+ */
+type IngredientAlternative = WithOptionalQuantity<IngredientAlternativeBase>;
 /**
  * Represents an ingredient item in a recipe step.
  * @category Types
@@ -530,6 +673,12 @@ interface IngredientItem {
      * `@|group|...` syntax), they represent a single logical choice.
      */
     group?: string;
+    /**
+     * An optional subgroup identifier for binding multiple ingredients together
+     * within a group. Ingredients sharing the same `group` and `subgroup` are
+     * selected together as a unit (e.g., from `@|group/1|...` syntax).
+     */
+    subgroup?: string;
 }
 /**
  * Represents the choices one can make in a recipe
@@ -543,9 +692,18 @@ interface RecipeAlternatives {
     ingredientItems: Map<string, IngredientAlternative[]>;
     /** Map of choices that can be made for Grouped Ingredient StepItem's
      * - Keys are the Group IDs (e.g. "eggs" for `@|eggs|...`)
-     * - Values are arrays of IngredientAlternative objects representing the choices available for that group
+     * - Values are arrays of subgroups, where each subgroup is an array of
+     *   bound IngredientAlternative objects that are selected together.
+     *   Items sharing the same subgroup key (e.g., `@|group/1|...`) are
+     *   in the same inner array. Items without a subgroup key each form
+     *   their own single-element subgroup.
+     */
+    ingredientGroups: Map<string, IngredientAlternative[][]>;
+    /**
+     * All variant names discovered in the recipe (from metadata, step tags,
+     * and section tags). Includes `*` if any step/section uses the default tag.
      */
-    ingredientGroups: Map<string, IngredientAlternative[]>;
+    variants: string[];
 }
 /**
  * Represents the choices to apply when computing ingredient quantities.
@@ -557,6 +715,46 @@ interface RecipeChoices {
     ingredientItems?: Map<string, number>;
     /** Map of choices that can be made for Grouped Ingredient StepItem's */
     ingredientGroups?: Map<string, number>;
+    /** The selected variant name */
+    variant?: string;
+}
+/**
+ * Options for the {@link Recipe.getIngredientQuantities | getIngredientQuantities()} method.
+ * @category Types
+ */
+interface GetIngredientQuantitiesOptions {
+    /**
+     * Filter ingredients to only those appearing in a specific section.
+     * Can be a Section object or section index (0-based).
+     */
+    section?: Section | number;
+    /**
+     * Filter ingredients to only those appearing in a specific step.
+     * Can be a Step object or step index (0-based within the section, or global if no section specified).
+     */
+    step?: Step | number;
+    /**
+     * The choices to apply when computing quantities.
+     * If not provided, uses primary alternatives (index 0 for all).
+     */
+    choices?: RecipeChoices;
+}
+/**
+ * Represents a raw (unprocessed) group of quantities for a single ingredient.
+ * Returned by {@link Recipe.getRawQuantityGroups},
+ * these are the pre-addition quantities that are fed internally
+ * to another non-public helper function for cross-recipe aggregation.
+ * @category Types
+ */
+interface RawQuantityGroup {
+    /** The name of the ingredient. */
+    name: string;
+    /** Whether this ingredient is used as a primary choice. */
+    usedAsPrimary?: boolean;
+    /** Flags on the ingredient (e.g., "hidden", "optional"). */
+    flags?: IngredientFlag[];
+    /** The raw, unprocessed quantities for this ingredient across all its mentions. */
+    quantities: (QuantityWithExtendedUnit | FlatOrGroup<QuantityWithExtendedUnit>)[];
 }
 /**
  * Represents a cookware item in a recipe step.
@@ -592,6 +790,11 @@ interface Timer {
     /** The unit of the timer. */
     unit: string;
 }
+/**
+ * Represents a formatting attribute for a {@link TextItem}.
+ * @category Types
+ */
+type TextAttribute = "bold" | "italic" | "bold+italic" | "link" | "code";
 /**
  * Represents a text item in a recipe step.
  * @category Types
@@ -601,6 +804,10 @@ interface TextItem {
     type: "text";
     /** The content of the text item. */
     value: string;
+    /** The formatting attribute of the text item, if any. */
+    attribute?: TextAttribute;
+    /** The URL target, only present when attribute is "link". */
+    href?: string;
 }
 /**
  * Represents an arbitrary scalable quantity in a recipe.
@@ -637,6 +844,10 @@ interface Step {
     type: "step";
     /** The items in the step. */
     items: StepItem[];
+    /** Optional list of variant names this step belongs to */
+    variants?: string[];
+    /** Whether the step has been marked as optional ("[?]") */
+    optional?: boolean;
 }
 /**
  * Represents an item in a note (can be text or arbitrary scalable).
@@ -707,6 +918,9 @@ interface RecipeWithServings {
 type AddedRecipe = RecipeWithFactor | RecipeWithServings;
 /**
  * Options for adding a recipe to a shopping list
+ *
+ * Used in {@link ShoppingList.addRecipe}
+ *
  * @category Types
  */
 type AddedRecipeOptions = {
@@ -723,7 +937,7 @@ type AddedRecipeOptions = {
  * Represents an ingredient that has been added to a shopping list
  * @category Types
  */
-type AddedIngredient = Pick<ComputedIngredient, "name" | "quantityTotal">;
+type AddedIngredient = Pick<Ingredient, "name" | "quantities">;
 /**
  * Represents an ingredient in a category.
  * @category Types
@@ -783,6 +997,48 @@ type ProductOption = ProductOptionBase & {
     /** The size(s) of the product. Multiple sizes allow equivalent expressions (e.g., "1%dozen" and "12") */
     sizes: ProductSize[];
 };
+/**
+ * Represents a pantry item entry in the TOML file.
+ * Can be a simple quantity string (e.g. `"500%g"`) or an object with details.
+ * @category Types
+ */
+type PantryItemToml = string | {
+    quantity?: string;
+    bought?: string;
+    expire?: string;
+    low?: string;
+};
+/**
+ * Represents a parsed pantry item.
+ * @category Types
+ */
+interface PantryItem {
+    /** The name of the item. */
+    name: string;
+    /** The storage location (TOML section name, e.g. "freezer", "fridge"). */
+    location: string;
+    /** The quantity value of the item. */
+    quantity?: FixedValue | Range;
+    /** The unit of the item's quantity. */
+    unit?: string;
+    /** The date when the item was purchased. */
+    bought?: Date;
+    /** The expiration date of the item. */
+    expire?: Date;
+    /** The low stock threshold value. */
+    low?: FixedValue | Range;
+    /** The unit of the low stock threshold. */
+    lowUnit?: string;
+}
+/**
+ * Options for configuring a {@link Pantry}.
+ * @category Types
+ */
+interface PantryOptions {
+    /** Date format pattern for parsing date strings (e.g. `"DD.MM.YYYY"`, `"MM/DD/YYYY"`, `"YYYY-MM-DD"`).
+     * If not provided, dates are parsed with fuzzy detection defaulting to day-first when ambiguous. */
+    dateFormat?: string;
+}
 /**
  * Represents a product selection in a {@link ShoppingCart}
  * @category Types
@@ -835,12 +1091,23 @@ type CartMisMatch = ProductMisMatch[];
  * Represents the type category of a unit used for quantities
  * @category Types
  */
-type UnitType = "mass" | "volume" | "count";
+type UnitType = "mass" | "volume" | "count" | "other";
+/**
+ * Represents the specific measurement systems
+ * @category Types
+ */
+type SpecificUnitSystem = "metric" | "US" | "UK" | "JP";
 /**
  * Represents the measurement system a unit belongs to
  * @category Types
  */
-type UnitSystem = "metric" | "imperial";
+type UnitSystem = SpecificUnitSystem | "ambiguous";
+/**
+ * Conversion factors for ambiguous units that can belong to multiple systems.
+ * Maps each possible system to its toBase conversion factor.
+ * @category Types
+ */
+type ToBaseBySystem = Partial<Record<SpecificUnitSystem, number>>;
 /**
  * Represents a unit used to describe quantities
  * @category Types
@@ -860,8 +1127,28 @@ interface UnitDefinition extends Unit {
     system: UnitSystem;
     /** e.g. ['gram', 'grams'] */
     aliases: string[];
-    /** Conversion factor to the base unit of its type */
+    /** Conversion factor to the base unit of its type (uses default system for ambiguous units) */
     toBase: number;
+    /** For ambiguous units: conversion factors for each possible system */
+    toBaseBySystem?: ToBaseBySystem;
+    /** Whether this unit is a candidate for "best unit" selection (default: true) */
+    isBestUnit?: boolean;
+    /** Maximum value before upgrading to a larger unit (default: 999) */
+    maxValue?: number;
+    /** Fraction display configuration */
+    fractions?: UnitFractionConfig;
+}
+/**
+ * Configuration for fraction display on a unit
+ * @category Types
+ */
+interface UnitFractionConfig {
+    /** Whether to approximate decimals as fractions for this unit */
+    enabled: boolean;
+    /** Allowed denominators (default: [2, 3, 4, 8]) */
+    denominators?: number[];
+    /** Maximum whole number in mixed fraction before falling back to decimal (default: 4) */
+    maxWhole?: number;
 }
 /**
  * Represents a resolved unit definition or a lightweight placeholder for non-standard units
@@ -908,27 +1195,59 @@ interface QuantityWithUnitDef extends QuantityBase {
  * @category Types
  */
 type QuantityWithUnitLike = QuantityWithPlainUnit | QuantityWithExtendedUnit | QuantityWithUnitDef;
+/**
+ * Represents a flat "or" group of alternative quantities (for alternative units)
+ * @category Types
+ */
+interface FlatOrGroup<T = QuantityWithUnitLike> {
+    or: T[];
+}
 /**
  * Represents an "or" group of alternative quantities that may contain nested groups (alternatives with nested structure)
  * @category Types
  */
 interface MaybeNestedOrGroup<T = QuantityWithUnitLike> {
-    type: "or";
-    entries: (T | MaybeNestedGroup<T>)[];
+    or: (T | MaybeNestedGroup<T>)[];
+}
+/**
+ * Represents a flat "and" group of quantities (combined quantities)
+ * @category Types
+ */
+interface FlatAndGroup<T = QuantityWithUnitLike> {
+    and: T[];
 }
 /**
  * Represents an "and" group of quantities that may contain nested groups (combinations with nested structure)
  * @category Types
  */
 interface MaybeNestedAndGroup<T = QuantityWithUnitLike> {
-    type: "and";
-    entries: (T | MaybeNestedGroup<T>)[];
+    and: (T | MaybeNestedGroup<T>)[];
 }
+/**
+ * Represents any flat group type ("and" or "or")
+ * @category Types
+ */
+type FlatGroup<T = QuantityWithUnitLike> = FlatAndGroup<T> | FlatOrGroup<T>;
 /**
  * Represents any group type that may include nested groups
  * @category Types
  */
 type MaybeNestedGroup<T = QuantityWithUnitLike> = MaybeNestedAndGroup<T> | MaybeNestedOrGroup<T>;
+/**
+ * Represents any group type (flat or nested)
+ * @category Types
+ */
+type Group<T = QuantityWithUnitLike> = MaybeNestedGroup<T> | FlatGroup<T>;
+/**
+ * Represents any "or" group (flat or nested)
+ * @category Types
+ */
+type OrGroup<T = QuantityWithUnitLike> = MaybeNestedOrGroup<T> | FlatOrGroup<T>;
+/**
+ * Represents any "and" group (flat or nested)
+ * @category Types
+ */
+type AndGroup<T = QuantityWithUnitLike> = MaybeNestedAndGroup<T> | FlatAndGroup<T>;
 
 /**
  * Parser for category configurations specified à-la-cooklang.
@@ -979,6 +1298,127 @@ declare class CategoryConfig {
     parse(config: string): void;
 }
 
+/**
+ * Pantry Inventory Manager: parses and queries a pantry inventory file.
+ *
+ * ## Usage
+ *
+ * Create a new Pantry instance with optional TOML content and options
+ * (see {@link Pantry."constructor" | constructor}), then query items
+ * using {@link Pantry.getDepletedItems | getDepletedItems()},
+ * {@link Pantry.getExpiredItems | getExpiredItems()},
+ * {@link Pantry.isLow | isLow()}, or {@link Pantry.isExpired | isExpired()}.
+ *
+ * A Pantry can also be attached to a {@link ShoppingList} via
+ * {@link ShoppingList.addPantry | addPantry()} so that on-hand stock
+ * is subtracted from recipe ingredient needs.
+ *
+ * @example
+ * ```typescript
+ * import { Pantry } from "@tmlmt/cooklang-parser";
+ *
+ * const pantryToml = `
+ * [fridge]
+ * milk = { expire = "10.05.2024", quantity = "1%L" }
+ *
+ * [freezer]
+ * spinach = { quantity = "1%kg", low = "200%g" }
+ * `;
+ *
+ * const pantry = new Pantry(pantryToml);
+ * console.log(pantry.getExpiredItems());
+ * console.log(pantry.isLow("spinach"));
+ * ```
+ *
+ * @see [Pantry Configuration](https://cooklang.org/docs/spec/#pantry-configuration) section of the cooklang specs
+ *
+ * @category Classes
+ */
+declare class Pantry {
+    /**
+     * The parsed pantry items.
+     */
+    items: PantryItem[];
+    /**
+     * Options for date parsing and other configuration.
+     */
+    private options;
+    /**
+     * Optional category configuration for alias-based lookups.
+     */
+    private categoryConfig?;
+    /**
+     * Creates a new Pantry instance.
+     * @param tomlContent - Optional TOML content to parse.
+     * @param options - Optional configuration options.
+     */
+    constructor(tomlContent?: string, options?: PantryOptions);
+    /**
+     * Parses a TOML string into pantry items.
+     * @param tomlContent - The TOML string to parse.
+     * @returns The parsed list of pantry items.
+     */
+    parse(tomlContent: string): PantryItem[];
+    /**
+     * Parses a single pantry item from its TOML representation.
+     */
+    private parseItem;
+    /**
+     * Parses a date string using the configured format or fuzzy detection.
+     */
+    private parseDate;
+    /**
+     * Sets a category configuration for alias-based item lookups.
+     * @param config - The category configuration to use.
+     */
+    setCategoryConfig(config: CategoryConfig): void;
+    /**
+     * 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: string): PantryItem | undefined;
+    /**
+     * 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.
+     */
+    private getItemNumericValue;
+    /**
+     * Returns all items that are depleted (quantity = 0) or below their low threshold.
+     * @returns An array of depleted pantry items.
+     */
+    getDepletedItems(): PantryItem[];
+    /**
+     * 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?: number): PantryItem[];
+    /**
+     * 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: string): boolean;
+    /**
+     * 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: string, nbDays?: number): boolean;
+    /**
+     * Internal: checks if a pantry item is low.
+     */
+    private isItemLow;
+    /**
+     * Internal: checks if a pantry item is expired.
+     */
+    private isItemExpired;
+}
+
 /**
  * Product Catalog Manager: used in conjunction with {@link ShoppingCart}
  *
@@ -1005,7 +1445,7 @@ declare class CategoryConfig {
  * 14141 = { name = "Big pack", size = "6%kg", price = 10 }
  * `
  * const catalog = new ProductCatalog(catalog);
- * const eggs = catalog.find("oeuf");
+ * const eggs = catalog.products.find(p => p.ingredientName === "eggs");
  * ```
  */
 declare class ProductCatalog {
@@ -1041,7 +1481,7 @@ declare class ProductCatalog {
  * ## Usage
  *
  * - Create a new ShoppingList instance with an optional category configuration (see {@link ShoppingList."constructor" | constructor})
- * - Add recipes, scaling them as needed (see {@link ShoppingList.add_recipe | add_recipe()})
+ * - Add recipes, scaling them as needed (see {@link ShoppingList.addRecipe | addRecipe()})
  * - Categorize the ingredients (see {@link ShoppingList.categorize | categorize()})
  *
  * @example
@@ -1053,10 +1493,10 @@ declare class ProductCatalog {
  * const categoryConfig = fs.readFileSync("./myconfig.txt", "utf-8")
  * const recipe1 = new Recipe(fs.readFileSync("./myrecipe.cook", "utf-8"));
  * const shoppingList = new ShoppingList();
- * shoppingList.set_category_config(categoryConfig);
+ * shoppingList.setCategoryConfig(categoryConfig);
  * // Quantities are automatically calculated and ingredients categorized
  * // when adding a recipe
- * shoppingList.add_recipe(recipe1);
+ * shoppingList.addRecipe(recipe1);
  * ```
  *
  * @category Classes
@@ -1073,36 +1513,84 @@ declare class ShoppingList {
     /**
      * The category configuration for the shopping list.
      */
-    category_config?: CategoryConfig;
+    categoryConfig?: CategoryConfig;
     /**
      * The categorized ingredients in the shopping list.
      */
     categories?: CategorizedIngredients;
+    /**
+     * The unit system to use for quantity simplification.
+     * When set, overrides per-recipe unit systems.
+     */
+    unitSystem?: SpecificUnitSystem;
+    /**
+     * Per-ingredient equivalence ratio maps for recomputing equivalents
+     * after pantry subtraction. Keyed by ingredient name.
+     * @internal
+     */
+    private equivalenceRatios;
+    /**
+     * The original pantry (never mutated by recipe calculations).
+     */
+    pantry?: Pantry;
+    /**
+     * The pantry with quantities updated after subtracting recipe needs.
+     * Recomputed on every {@link ShoppingList.calculateIngredients | calculateIngredients()} call.
+     */
+    private resultingPantry?;
     /**
      * Creates a new ShoppingList instance
-     * @param category_config_str - The category configuration to parse.
+     * @param categoryConfigStr - The category configuration to parse.
      */
-    constructor(category_config_str?: string | CategoryConfig);
-    private calculate_ingredients;
+    constructor(categoryConfigStr?: string | CategoryConfig);
+    private calculateIngredients;
+    /**
+     * Subtracts pantry item quantities from calculated ingredient quantities
+     * and updates the resultingPantry to reflect consumed stock.
+     */
+    private applyPantrySubtraction;
     /**
      * Adds a recipe to the shopping list, then automatically
      * recalculates the quantities and recategorize the ingredients.
      * @param recipe - The recipe to add.
      * @param options - Options for adding the recipe.
+     * @throws Error if the recipe has alternatives without corresponding choices.
+     */
+    addRecipe(recipe: Recipe, options?: AddedRecipeOptions): void;
+    /**
+     * Checks if a recipe has unresolved alternatives (alternatives without provided choices).
+     * @param recipe - The recipe to check.
+     * @param choices - The choices provided for the recipe.
+     * @returns An error message if there are unresolved alternatives, undefined otherwise.
      */
-    add_recipe(recipe: Recipe, options?: AddedRecipeOptions): void;
+    private getUnresolvedAlternativesError;
     /**
      * Removes a recipe from the shopping list, then automatically
-     * recalculates the quantities and recategorize the ingredients.s
+     * recalculates the quantities and recategorize the ingredients.
      * @param index - The index of the recipe to remove.
      */
-    remove_recipe(index: number): void;
+    removeRecipe(index: number): void;
+    /**
+     * 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: Pantry | string, options?: PantryOptions): void;
+    /**
+     * 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(): Pantry | undefined;
     /**
      * 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.
      */
-    set_category_config(config: string | CategoryConfig): void;
+    setCategoryConfig(config: string | CategoryConfig): void;
     /**
      * Categorizes the ingredients in the shopping list
      * Will use the category config if any, otherwise all ingredients will be placed in the "other" category
@@ -1145,7 +1633,7 @@ interface ShoppingCartSummary {
  * ```ts
  * const shoppingList = new ShoppingList();
  * const recipe = new Recipe("@flour{600%g}");
- * shoppingList.add_recipe(recipe);
+ * shoppingList.addRecipe(recipe);
  *
  * const catalog = new ProductCatalog();
  * catalog.products = [
@@ -1255,6 +1743,329 @@ declare class ShoppingCart {
     summarize(): ShoppingCartSummary;
 }
 
+/**
+ * Render a fraction using Unicode vulgar fraction characters when available.
+ * Handles improper fractions by extracting the whole part (e.g., 5/4 → "1¼").
+ *
+ * @param num - The numerator
+ * @param den - The denominator
+ * @returns The fraction as a string, using vulgar characters if available
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * renderFractionAsVulgar(1, 2); // "½"
+ * renderFractionAsVulgar(3, 4); // "¾"
+ * renderFractionAsVulgar(5, 4); // "1¼"
+ * renderFractionAsVulgar(7, 3); // "2⅓"
+ * renderFractionAsVulgar(2, 5); // "2/5" (no vulgar character available)
+ * ```
+ */
+declare function renderFractionAsVulgar(num: number, den: number): string;
+/**
+ * Format a numeric value (decimal or fraction) to a string.
+ *
+ * @param value - The decimal or fraction value to format
+ * @param useVulgar - Whether to use Unicode vulgar fraction characters (default: true)
+ * @returns The formatted string representation
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * formatNumericValue({ type: "decimal", decimal: 1.5 }); // "1.5"
+ * formatNumericValue({ type: "fraction", num: 1, den: 2 }); // "½"
+ * formatNumericValue({ type: "fraction", num: 1, den: 2 }, false); // "1/2"
+ * formatNumericValue({ type: "fraction", num: 5, den: 4 }, true); // "1¼"
+ * ```
+ */
+declare function formatNumericValue(value: DecimalValue | FractionValue, useVulgar?: boolean): string;
+/**
+ * Format a single value (text, decimal, or fraction) to a string.
+ *
+ * @param value - The value to format
+ * @returns The formatted string representation
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * formatSingleValue({ type: "text", text: "a pinch" }); // "a pinch"
+ * formatSingleValue({ type: "decimal", decimal: 2 }); // "2"
+ * formatSingleValue({ type: "fraction", num: 3, den: 4 }); // "3/4"
+ * ```
+ */
+declare function formatSingleValue(value: TextValue | DecimalValue | FractionValue): string;
+/**
+ * Format a quantity (fixed value or range) to a string.
+ *
+ * @param quantity - The quantity to format
+ * @returns The formatted string representation
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * formatQuantity({ type: "fixed", value: { type: "decimal", decimal: 100 } }); // "100"
+ * formatQuantity({ type: "range", min: { type: "decimal", decimal: 1 }, max: { type: "decimal", decimal: 2 } }); // "1-2"
+ * ```
+ */
+declare function formatQuantity(quantity: FixedValue | Range): string;
+/**
+ * Format a unit to a string. Handles both plain string units and Unit objects.
+ *
+ * @param unit - The unit to format (string, Unit object, or undefined)
+ * @returns The formatted unit string, or empty string if undefined
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * formatUnit("g"); // "g"
+ * formatUnit({ name: "grams" }); // "grams"
+ * formatUnit(undefined); // ""
+ * ```
+ */
+declare function formatUnit(unit: string | Unit | undefined): string;
+/**
+ * Format a quantity with its unit to a string.
+ *
+ * @param quantity - The quantity to format
+ * @param unit - The unit to append (string, Unit object, or undefined)
+ * @returns The formatted string with quantity and unit
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * formatQuantityWithUnit({ type: "fixed", value: { type: "decimal", decimal: 100 } }, "g"); // "100 g"
+ * formatQuantityWithUnit({ type: "fixed", value: { type: "decimal", decimal: 2 } }, undefined); // "2"
+ * ```
+ */
+declare function formatQuantityWithUnit(quantity: FixedValue | Range | undefined, unit: string | Unit | undefined): string;
+/**
+ * Format a QuantityWithExtendedUnit to a string.
+ *
+ * @param item - The quantity with extended unit to format
+ * @returns The formatted string
+ * @category Helpers
+ */
+declare function formatExtendedQuantity(item: QuantityWithExtendedUnit): string;
+/**
+ * Format an IngredientItemQuantity with all its equivalents to a string.
+ *
+ * @param itemQuantity - The ingredient item quantity to format
+ * @param separator - The separator between primary and equivalent quantities (default: " | ")
+ * @returns The formatted string with all quantities
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * // For an ingredient like @flour{100%g|3.5%oz}
+ * formatItemQuantity(itemQuantity); // "100 g | 3.5 oz"
+ * formatItemQuantity(itemQuantity, " / "); // "100 g / 3.5 oz"
+ * ```
+ */
+declare function formatItemQuantity(itemQuantity: MaybeScalableQuantity, separator?: string): string;
+/**
+ * Check if an ingredient item is a grouped alternative (vs inline alternative).
+ *
+ * Grouped alternatives are ingredients that share a group key (e.g., `@|milk|...`)
+ * and are distributed across multiple tokens in the recipe.
+ *
+ * @param item - The ingredient item to check
+ * @returns true if this is a grouped alternative
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * for (const item of step.items) {
+ *   if (item.type === 'ingredient') {
+ *     if (isGroupedItem(item)) {
+ *       // Handle grouped alternative (e.g., show with strikethrough if not selected)
+ *     } else {
+ *       // Handle inline alternative (e.g., hide if not selected)
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function isGroupedItem(item: IngredientItem): boolean;
+/**
+ * Determines if a specific alternative in an IngredientItem is selected
+ * based on the applied choices.
+ *
+ * Use this in renderers to determine how an ingredient alternative should be displayed.
+ *
+ * @param recipe - The Recipe instance containing choices
+ * @param choices - The choices that have been made
+ * @param item - The IngredientItem to check
+ * @param alternativeIndex - The index within item.alternatives to check (for inline alternatives only)
+ * @returns true if this alternative is the selected one
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * const recipe = new Recipe(cooklangText);
+ * for (const item of step.items) {
+ *   if (item.type === 'ingredient') {
+ *     item.alternatives.forEach((alt, idx) => {
+ *       const isSelected = isAlternativeSelected(recipe, choices, item, idx);
+ *       // Render differently based on isSelected
+ *     });
+ *   }
+ * }
+ * ```
+ */
+declare function isAlternativeSelected(recipe: Recipe, choices: RecipeChoices, item: IngredientItem, alternativeIndex?: number): boolean;
+/**
+ * Determines if a section is active (should be displayed or processed) for a given variant.
+ *
+ * - Sections with no `variants` property are always active.
+ * - When no variant is selected (default), sections tagged `[*]` are active,
+ *   and sections tagged with named variants are not.
+ * - When a named variant is selected, sections whose `variants` array includes
+ *   that name are active.
+ *
+ * @param section - The Section to check
+ * @param variant - The active variant name, or `undefined`/`*` for the default variant
+ * @returns `true` if the section should be displayed
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * const recipe = new Recipe(cooklangText);
+ * for (const section of recipe.sections) {
+ *   if (isSectionActive(section, choices.variant)) {
+ *     // render section
+ *   }
+ * }
+ * ```
+ */
+declare function isSectionActive(section: Section, variant?: string): boolean;
+/**
+ * Determines if a step is active (should be displayed) for a given variant.
+ *
+ * - Steps with no `variants` property are always active.
+ * - When no variant is selected (default), steps tagged `[*]` are active,
+ *   and steps tagged with named variants are not.
+ * - When a named variant is selected, steps whose `variants` array includes
+ *   that name are active.
+ *
+ * @param step - The Step to check
+ * @param variant - The active variant name, or `undefined`/`*` for the default variant
+ * @returns `true` if the step should be displayed
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * for (const item of section.content) {
+ *   if (item.type === 'step' && isStepActive(item, choices.variant)) {
+ *     // render step
+ *   }
+ * }
+ * ```
+ */
+declare function isStepActive(step: Step, variant?: string): boolean;
+/**
+ * Returns the effective choices for a recipe given a variant selection.
+ *
+ * When a named variant is active, this scans ingredient alternatives whose
+ * `note` contains the variant name (case-insensitive substring match) and
+ * returns a `RecipeChoices` object with auto-selected alternatives.
+ *
+ * For inline alternatives: auto-selects the first alternative whose note
+ * matches the variant name.
+ *
+ * For grouped alternatives: auto-selects the first subgroup that has any
+ * alternative whose note matches the variant name.
+ *
+ * @param recipe - The Recipe instance
+ * @param variant - The active variant name, or `undefined`/`*` for defaults
+ * @returns A `RecipeChoices` with the `variant` set and auto-selected alternatives
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * const recipe = new Recipe(cooklangText);
+ * const choices = getEffectiveChoices(recipe, "vegan");
+ * const ingredients = recipe.getIngredientQuantities({ choices });
+ * ```
+ */
+declare function getEffectiveChoices(recipe: Recipe, variant?: string): RecipeChoices;
+
+/**
+ * Type guard to check if an ingredient quantity-like object is an AND group.
+ * *
+ * @param x - The quantity-like entry to check
+ * @returns true if this is an AND group (has `and` property)
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * for (const entry of ingredient.quantities) {
+ *   if (isAndGroup(entry)) {
+ *     // entry.and contains the list of quantities in the AND group
+ *   }
+ * }
+ * ```
+ */
+declare function isAndGroup(x: IngredientQuantityGroup | IngredientQuantityAndGroup): x is IngredientQuantityAndGroup;
+declare function isAndGroup(x: QuantityWithUnitLike | Group): x is AndGroup;
+/**
+ * Type guard to check if an ingredient quantity entry is a simple group.
+ *
+ * Simple groups have a single quantity with optional unit and equivalents.
+ *
+ * @param entry - The quantity entry to check
+ * @returns true if this is a simple group (has `quantity` property)
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * for (const entry of ingredient.quantities) {
+ *   if (isSimpleGroup(entry)) {
+ *     // entry.quantity is available
+ *     // entry.unit is available
+ *   }
+ * }
+ * ```
+ */
+declare function isSimpleGroup(entry: IngredientQuantityGroup | IngredientQuantityAndGroup): entry is IngredientQuantityGroup;
+/**
+ * Type guard to check if an ingredient quantity entry has alternatives.
+ *
+ * @param entry - The quantity entry to check
+ * @returns true if this entry has alternatives
+ * @category Helpers
+ *
+ * @example
+ * ```typescript
+ * for (const entry of ingredient.quantities) {
+ *   if (hasAlternatives(entry)) {
+ *     // entry.alternatives is available and non-empty
+ *     for (const subgroup of entry.alternatives) {
+ *       // Each subgroup is one "or" choice; items within are combined with "+"
+ *       for (const alt of subgroup) {
+ *         console.log(`Alternative ingredient index: ${alt.index}`);
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function hasAlternatives(entry: IngredientQuantityGroup | IngredientQuantityAndGroup): entry is (IngredientQuantityGroup | IngredientQuantityAndGroup) & {
+    alternatives: AlternativeIngredientRef[][];
+};
+
+/**
+ * Converts a quantity to the best unit in a target system.
+ * Returns the converted quantity, or undefined if the unit type is "other" or not convertible.
+ *
+ * @category Helpers
+ *
+ * @param quantity - The quantity to convert
+ * @param system - The target unit system
+ * @returns The converted quantity, or undefined if conversion not possible
+ */
+declare function convertQuantityToSystem(quantity: QuantityWithPlainUnit, system: SpecificUnitSystem): QuantityWithPlainUnit | undefined;
+declare function convertQuantityToSystem(quantity: QuantityWithExtendedUnit, system: SpecificUnitSystem): QuantityWithExtendedUnit | undefined;
+
 /**
  * Error thrown when trying to build a shopping cart without a product catalog
  * @category Errors
@@ -1270,4 +2081,4 @@ declare class NoShoppingListForCartError extends Error {
     constructor();
 }
 
-export { type AddedIngredient, type AddedRecipe, type AddedRecipeOptions, type AlternativeIngredientRef, type ArbitraryScalable, type ArbitraryScalableItem, type CartContent, type CartMatch, type CartMisMatch, type CategorizedIngredients, type Category, CategoryConfig, type CategoryIngredient, type ComputedIngredient, type Cookware, type CookwareFlag, type CookwareItem, type DecimalValue, type FixedNumericValue, type FixedValue, type FractionValue, type Ingredient, type IngredientAlternative, type IngredientExtras, type IngredientFlag, type IngredientItem, type IngredientItemQuantity, type IngredientQuantityAndGroup, type IngredientQuantityGroup, type MaybeNestedAndGroup, type MaybeNestedGroup, type MaybeNestedOrGroup, type Metadata, NoProductCatalogForCartError, type NoProductMatchErrorCode, NoShoppingListForCartError, type Note, type NoteItem, ProductCatalog, type ProductMatch, type ProductMisMatch, type ProductOption, type ProductOptionBase, type ProductOptionCore, type ProductSelection, type ProductSize, type QuantityBase, type QuantityWithExtendedUnit, type QuantityWithPlainUnit, type QuantityWithUnitDef, type QuantityWithUnitLike, type Range, Recipe, type RecipeAlternatives, type RecipeChoices, type RecipeWithFactor, type RecipeWithServings, Section, ShoppingCart, type ShoppingCartOptions, type ShoppingCartSummary, ShoppingList, type Step, type StepItem, type TextItem, type TextValue, type Timer, type TimerItem, type Unit, type UnitDefinition, type UnitDefinitionLike, type UnitSystem, type UnitType };
+export { type AddedIngredient, type AddedRecipe, type AddedRecipeOptions, type AlternativeIngredientRef, type AndGroup, type ArbitraryScalable, type ArbitraryScalableItem, type CartContent, type CartMatch, type CartMisMatch, type CategorizedIngredients, type Category, CategoryConfig, type CategoryIngredient, type Cookware, type CookwareFlag, type CookwareItem, type DecimalValue, type FixedNumericValue, type FixedValue, type FlatAndGroup, type FlatGroup, type FlatOrGroup, type FractionValue, type GetIngredientQuantitiesOptions, type Group, type Ingredient, type IngredientAlternative, type IngredientAlternativeBase, type IngredientExtras, type IngredientFlag, type IngredientItem, type IngredientQuantityAndGroup, type IngredientQuantityGroup, type MaybeNestedAndGroup, type MaybeNestedGroup, type MaybeNestedOrGroup, type MaybeScalableQuantity, type Metadata, type MetadataObject, type MetadataSource, type MetadataTime, type MetadataValue, NoProductCatalogForCartError, type NoProductMatchErrorCode, NoShoppingListForCartError, type Note, type NoteItem, type OrGroup, Pantry, type PantryItem, type PantryItemToml, type PantryOptions, ProductCatalog, type ProductMatch, type ProductMisMatch, type ProductOption, type ProductOptionBase, type ProductOptionCore, type ProductSelection, type ProductSize, type QuantityBase, type QuantityWithExtendedUnit, type QuantityWithPlainUnit, type QuantityWithUnitDef, type QuantityWithUnitLike, type Range, type RawQuantityGroup, Recipe, type RecipeAlternatives, type RecipeChoices, type RecipeWithFactor, type RecipeWithServings, Section, ShoppingCart, type ShoppingCartOptions, type ShoppingCartSummary, ShoppingList, type SpecificUnitSystem, type Step, type StepItem, type TextAttribute, type TextItem, type TextValue, type Timer, type TimerItem, type ToBaseBySystem, type Unit, type UnitDefinition, type UnitDefinitionLike, type UnitFractionConfig, type UnitSystem, type UnitType, type WithOptionalQuantity, type Yield, convertQuantityToSystem, formatExtendedQuantity, formatItemQuantity, formatNumericValue, formatQuantity, formatQuantityWithUnit, formatSingleValue, formatUnit, getEffectiveChoices, hasAlternatives, isAlternativeSelected, isAndGroup, isGroupedItem, isSectionActive, isSimpleGroup, isStepActive, renderFractionAsVulgar };