Bambu Filament Manager

Bambu Filament Manager is a local-first Mac-friendly filament dashboard built with plain HTML, CSS, and vanilla JavaScript. It tracks a normalized Bambu Lab catalog, your owned inventory, usage logs, wishlist items, and low-stock alerts without needing a backend or build step.

Project Structure

bambu-filament-manager/
  index.html
  styles/
    app.css
  scripts/
    app.js
    data-store.js
    render.js
    filters.js
    modals.js
    seed-catalog.js
  data/
    bambu_catalog.json
    inventory.json
    usage_log.json
  README.md

Run Locally on Mac

Option 1: Open it directly

Double-click [index.html](/Users/anthonylarosa/CODEX/Bambu Filament Dashboard/bambu-filament-manager/index.html).

When opened this way, browsers usually block automatic fetch() access to local JSON files. The app still works because it falls back to:

1. Bundled starter data from [seed-catalog.js](/Users/anthonylarosa/CODEX/Bambu Filament Dashboard/bambu-filament-manager/scripts/seed-catalog.js)
2. Your saved browser edits in localStorage

Option 2: Run a tiny local server

From [bambu-filament-manager](/Users/anthonylarosa/CODEX/Bambu Filament Dashboard/bambu-filament-manager):

python3 -m http.server 8000

Then open http://localhost:8000.

This mode lets the app automatically load the editable JSON files in [data/bambu_catalog.json](/Users/anthonylarosa/CODEX/Bambu Filament Dashboard/bambu-filament-manager/data/bambu_catalog.json), [data/inventory.json](/Users/anthonylarosa/CODEX/Bambu Filament Dashboard/bambu-filament-manager/data/inventory.json), and [data/usage_log.json](/Users/anthonylarosa/CODEX/Bambu Filament Dashboard/bambu-filament-manager/data/usage_log.json).

How the Data Works

The app uses three separate datasets:

1. Catalog data in [data/bambu_catalog.json](/Users/anthonylarosa/CODEX/Bambu Filament Dashboard/bambu-filament-manager/data/bambu_catalog.json)
2. Owned inventory data in [data/inventory.json](/Users/anthonylarosa/CODEX/Bambu Filament Dashboard/bambu-filament-manager/data/inventory.json)
3. Usage history in [data/usage_log.json](/Users/anthonylarosa/CODEX/Bambu Filament Dashboard/bambu-filament-manager/data/usage_log.json)

On startup:

1. The app loads each dataset from localStorage first if you already edited something in the browser.
2. If there is no browser-saved data, it loads from the JSON files when served over http://localhost.
3. If the app is opened directly from disk, it falls back to the starter data bundled in [scripts/seed-catalog.js](/Users/anthonylarosa/CODEX/Bambu Filament Dashboard/bambu-filament-manager/scripts/seed-catalog.js).

Editing Catalog Data

Open [data/bambu_catalog.json](/Users/anthonylarosa/CODEX/Bambu Filament Dashboard/bambu-filament-manager/data/bambu_catalog.json) in any text editor and add another object to the array.

Example:

{
  "id": "pla-matte-ice-blue",
  "brand": "Bambu Lab",
  "family": "pla",
  "material": "PLA Matte",
  "color": "Ice Blue",
  "hex": "#9CCBEA",
  "swatch": "#9CCBEA",
  "bambuCode": "11601",
  "productUrl": "https://us.store.bambulab.com/products/pla-matte",
  "reorderLabel": "Ice Blue (11601)",
  "amsCompatible": true,
  "active": true
}

Rules that keep the data clean:

1. id should stay unique and lowercase with hyphens.
2. family should group related materials like pla, petg, tpu, asa, abs, support, or engineering.
3. swatch can be the same as hex for normal colors.
4. bambuCode should only be added when it is clearly supported by official product data.
5. productUrl should point to the official Bambu family product page when available.
6. Keep catalogId values in inventory and usage entries matched to an existing catalog id.

Official Catalog Sources

This catalog pass was built from official Bambu sources first:

1. The official filament collection page on the Bambu US Store for which filament families are currently listed
2. Official Bambu store product pages that expose hex code tables for current colors
3. Official Bambu support material comparison content for support-filament color availability

The catalog intentionally avoids adding fake placeholder colors for materials where the current official page was visible but the exact live color list was not clearly exposed in the available official sources.

How to Add New Bambu Colors

You have two easy paths.

Path 1: Edit the JSON directly

Add a new entry to [data/bambu_catalog.json](/Users/anthonylarosa/CODEX/Bambu Filament Dashboard/bambu-filament-manager/data/bambu_catalog.json), then refresh the browser.

Path 2: Use the helper seed workflow

[scripts/seed-catalog.js](/Users/anthonylarosa/CODEX/Bambu Filament Dashboard/bambu-filament-manager/scripts/seed-catalog.js) includes helper functions:

1. slugify(...)
2. catalogEntry(...)
3. buildCatalogFromPairs(...)
4. dedupeCatalog(...)
5. sortCatalog(...)
6. createGradientSwatch(...)
7. productUrlByMaterial
8. bambuCodeByMaterial

That file is meant to stay beginner-friendly. The recommended maintenance flow is:

1. Add or update colors in [scripts/seed-catalog.js](/Users/anthonylarosa/CODEX/Bambu Filament Dashboard/bambu-filament-manager/scripts/seed-catalog.js)
2. Keep each material grouped in its own buildCatalogFromPairs(...) block
3. Let the helper dedupe and sort the final catalog
4. Regenerate [data/bambu_catalog.json](/Users/anthonylarosa/CODEX/Bambu Filament Dashboard/bambu-filament-manager/data/bambu_catalog.json) from the seed file

Example regeneration command:

node <<'NODE'
const fs = require('fs');
const vm = require('vm');
const context = { window: {} };
vm.createContext(context);
vm.runInContext(fs.readFileSync('./scripts/seed-catalog.js', 'utf8'), context);
fs.writeFileSync('./data/bambu_catalog.json', JSON.stringify(context.window.BambuSeeds.catalog, null, 2) + '\n');
NODE

Example helper usage:

var newPlaMatteColors = window.BambuSeeds.helpers.buildCatalogFromPairs(
  "PLA Matte",
  "pla",
  true,
  [
    { id: "pla-matte-cloud-white", color: "Cloud White", hex: "#F2F4F4" },
    { id: "pla-matte-forest-green", color: "Forest Green", hex: "#53684A" }
  ]
);

Inventory Editing

Each filament card supports:

1. Editing owned status
2. Total rolls and open rolls
3. Remaining percentage
4. Low-stock threshold
5. Notes
6. Wishlist toggling
7. Usage logging

Low-stock state turns on automatically when:

remainingPct <= lowThreshold

Saving and Backing Up Local Data

The UI includes three useful data actions:

1. Normal app edits auto-save to browser localStorage immediately after they succeed. That includes inventory edits, usage logs, wishlist toggles, quick add-to-inventory flows, clear-entry actions, imports, and reset.
2. Import JSON loads one or more JSON files and stores them into browser localStorage.
3. Save JSON Files writes JSON files into a folder if your browser supports the File System Access API. If not, it falls back to downloads.
4. Download Backup downloads one combined backup file containing the catalog, inventory, and usage datasets together.

Import JSON now supports both:

1. Separate files such as bambu_catalog.json, inventory.json, and usage_log.json
2. The combined backup file created by Download Backup

The importer also validates cross-references so inventory and usage entries cannot point to catalog IDs that do not exist.

For a manual backup, also copy these files somewhere safe:

1. [data/bambu_catalog.json](/Users/anthonylarosa/CODEX/Bambu Filament Dashboard/bambu-filament-manager/data/bambu_catalog.json)
2. [data/inventory.json](/Users/anthonylarosa/CODEX/Bambu Filament Dashboard/bambu-filament-manager/data/inventory.json)
3. [data/usage_log.json](/Users/anthonylarosa/CODEX/Bambu Filament Dashboard/bambu-filament-manager/data/usage_log.json)

If you have browser-only edits you want to preserve, use the in-app Download Backup button before clearing browser storage.

QA and Behavior Notes

This project is set up so that:

1. Clicking a card opens the inventory editor
2. Clicking Edit Inventory or Log Usage goes directly to the matching modal action
3. Invalid modal data stays open instead of silently closing
4. Usage totals, latest usage context, and low-stock state update after every successful auto-save
5. Reset only clears browser-saved overrides and then reloads JSON or bundled seed data

Starter Catalog Notes

The starter catalog currently includes:

1. Every filament you listed as currently owned
2. A much larger official-source-driven Bambu catalog with normalized ids
3. Official support materials and engineering materials where current colors could be verified
4. A seed-helper structure that is much easier to extend later

Beginner-Friendly File Guide

Use these files for the most common changes:

1. [data/bambu_catalog.json](/Users/anthonylarosa/CODEX/Bambu Filament Dashboard/bambu-filament-manager/data/bambu_catalog.json) for materials and colors
2. [data/inventory.json](/Users/anthonylarosa/CODEX/Bambu Filament Dashboard/bambu-filament-manager/data/inventory.json) for what you own
3. [data/usage_log.json](/Users/anthonylarosa/CODEX/Bambu Filament Dashboard/bambu-filament-manager/data/usage_log.json) for print history
4. [styles/app.css](/Users/anthonylarosa/CODEX/Bambu Filament Dashboard/bambu-filament-manager/styles/app.css) for visual styling
5. [scripts/app.js](/Users/anthonylarosa/CODEX/Bambu Filament Dashboard/bambu-filament-manager/scripts/app.js) for app behavior

Notes About Local-Only Apps

Because this app has no backend:

1. Editing a card saves to browser storage immediately.
2. A different browser profile will have different local changes.
3. JSON files on disk do not update automatically unless you use Save JSON Files or downloaded backups.