Library

Three layers stacked from the page header down:

• Top action — + IMPORT OIL in the page-header actions row (for hand-entering an oil that isn't in any vendor catalog yet).
• Filter row — All Houses chips on the left, Search… input on the right.
• Selection bar — appears when there are unowned oils visible: Select all N unowned, an owned-count, and a Clear selection button after you've selected anything.
• Card grid — 1 / 2 / 3 / 4-up depending on viewport. Each card is a single oil.
• Sticky save bar — slides up from the bottom whenever you have pending adds or removals. Houses the qty-input toggle + Save / Remove / Clear actions.

1. 1

   Open Library → Oils

   Sidebar → Oil Library (URL: /library/oils). Open to every tier; the per-tier oil cap (10 / 25 / 100 / ∞) gates how many you can save.

2. 2

   Pick a house (vendor)

   Top filter chips. All Houses is the default; click any vendor name (e.g., CandleScience, The Flaming Candle) to scope the grid to that house only. Each house has its own brand color, applied to that vendor's card backgrounds — useful for visually scanning a mixed grid.

3. 3

   Search by name OR note

   The search box matches against both the oil name AND its top / middle / base notes. So typing tobacco surfaces every oil that has “tobacco” in its notes, even when it's not in the name (e.g., a “Library at Dusk” oil that lists tobacco as a top note).

   TIP

   Search and house filter compose. Pick a house first to narrow the grid, then search inside it — useful when you're comparing similar SKUs across vendors.
4. 4

   Read the cards

   Each card is laid out top → bottom:

   • Name + vendor name — color-coded by house. If the manufacturer (the actual perfumer / sub-brand) differs from the listing vendor, that name shows below in mute text.
   • Note breakdown — top / middle / base notes laid out by category. On mobile, tap to expand; desktop shows them inline.
   • Application tags — CANDLE, WAX MELT, SOAP if the vendor publishes safety data for that use.
   • Spec tags — PHTHALATE-FREE when the vendor certifies it.
   • State badges — IN LIBRARY when you own it; WILL REMOVE when marked for removal but not yet saved.

Click anywhere on a card to open the full detail modal. It's the same modal whether you're browsing or already own the oil — just the bottom action button switches between Add to My Library and Remove from Library.

Sections you'll see (only the ones with data render):

• Header — name, vendor (linked to the source PDP), manufacturer if different.
• Notes — color-coded blocks: yellow top notes, rose middle notes, amber base notes.
• Price tiers — every size the vendor sells (1 oz / 4 oz / 16 oz / 1 lb / etc.) with both per-oz and total price columns. Sorted ascending by size.
• Details — flashpoint (°F), vanillin %, soy performance (1–3 stars), phthalate-free yes/no, Prop 65 required / not required.
• Applications — for each of candle / wax melt / bar soap: a SAFE/UNSAFE pill plus the vendor's recommended usage min–max range.
• Documents — direct links to the IFRA Certificate, Safety Data Sheet (SDS), and Allergen Statement when published. Open in a new tab.

1. 1

   Open the card

   Click the card to open the detail modal. (Or click the empty selection slot on the card to add it without opening details — more on that below.)

2. 2

   Click Add to My Library

   Big hazard-orange button at the bottom of the modal. Adds the oil to user_libraries for your account immediately, with an oz quantity of 0.

3. 3

   Set the quantity later

   The card flips to IN LIBRARY. To set the actual ounces you own, head to Inventory → Owned Oils — that's the qty-management surface. Or use the bulk flow below to set quantities at add-time.

The bulk flow is the fastest way to seed your library after signup, or restock after a big order.

1. 1

   Select the oils

   Click the small selection slot on each card to mark it (the slot is the small box on the card, separate from the body — clicking the body opens the detail modal). Or use Select all N unowned at the top of the grid to mark every unowned card visible at the current filter.

   TIP

   Filter by house first, then click Select all unowned to grab everything from one vendor. Useful when stocking up after a CandleScience order.
2. 2

   Sticky save bar appears

   The bottom of the page now shows a save bar: count of items, a toggle for the qty inputs, and a Save button.

3. 3

   (Optional) Click Add quantities

   Toggles a per-oil oz input row for every selected oil. Type the ounces you own. Skip any row to save it with 0 oz (you can update later from Inventory).

4. 4

   Save

   Click Save. All selected oils land in your library at once with their entered (or 0) quantities. The selection clears.

1. 1

   Mark for removal

   Click an owned card to open the detail modal → Remove from Library. The card flips to WILL REMOVE (it's pending, not committed). To unmark, click the card again → Keep in Library.

2. 2

   Bulk-mark by clicking owned cards

   Same selection mechanic as the add flow, but on owned cards instead.

3. 3

   Confirm via the save bar

   The save bar shows “N to remove”. Click Remove to commit, or Clear to abandon all the pending removals.

If a vendor we don't scrape (or a one-off custom blend you commissioned) sells an oil you want to use:

1. 1

   Click + IMPORT OIL in the page-header actions

   Top-right of the Library page. Opens the import dialog.

2. 2

   Fill in the basics

   Name, vendor, notes (top / middle / base), and any pricing or safety info you have. None of the document fields are required — leave them blank if you don't have an SDS link.

3. 3

   Save

   The oil lands in the catalog AND your library at the same time. It's tagged with a manual-entry source so the daily scrape job won't overwrite it.

The Oil Engine handles two related problems: cross-house duplicates (the same oil sold by two vendors under similar names) and discontinued-oil swaps (vendor pulled the SKU; here's a replacement). It runs automatically after library changes and can also be triggered manually from the Inventory page's RUN ENGINE button.

Cross-house duplicates

When BLNDR detects two library entries that look like the same underlying oil sold by different houses:

1. 1

   The Oil Engine modal opens

   Auto-fired when the dupe detector finds a candidate post-library-add. You can also trigger it manually with RUN ENGINE on Inventory.

2. 2

   Review the suspected pairs

   Each pair shows: name match score, family match, side-by-side notes, and per-house $/lb pricing.

3. 3

   Choose

   • SAME OIL — KEEP BOTH — dismiss for 90 days. Useful when you're intentionally hedging vendors.
   • SAME OIL — CONSOLIDATE — merge into the cheaper house's entry; the duplicate is removed.
   • DIFFERENT OIL — dismiss permanently. Lands in duplicate_dismissals so the engine never asks again.

Discontinued-oil swap

Houses discontinue oils. BLNDR catches it on the next scrape and flags your library row.

1. 1

   Spot the DISC badge

   Discontinued owned-rows show a hazard-stripe border + DISCONTINUED · N oz left badge in the Inventory page.

2. 2

   Click SWAP

   Opens the Oil Engine with auto-suggested replacements:

   • Same name across houses always wins — Gingerbread → Gingerbread, regardless of note overlap.
   • Falls back to note-similarity when no exact name match exists.
   • Manual search if the auto-picks miss.
   • $/lb shown on every candidate at your preferred buy size.
3. 3

   Confirm the swap

   The discontinued row gets a swapped → [target] badge. Your recipes that referenced the old oil get an entry in recipe_history and the ingredient row swaps in place.

4. 4

   Use up remaining stock

   The discontinued row stays so you can pour through it. When stock hits 0, a REMOVE button surfaces. Click to remove the library link (catalog row stays).