@blamejs/blamejs-shop 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.3.x
 
+- v0.3.5 (2026-05-30) — **Shipping-label management in the admin console.** The admin console gains shipping-label tools. On an order, void a purchased label — with a reason — when it needs reprinting, alongside the existing mark-as-used action. A new Shipping labels section adds cross-order visibility: a status-filtered list, the mint queue of labels awaiting a broker, and a broker-spend report that totals label costs by carrier and currency over a date range. This is bookkeeping and reporting only — nothing in the storefront, cart, or checkout changes. **Added:** *Void a shipping label from the order* — Each purchased label on an order now offers a Void action with a reason, for when a label is reprinted at a different weight or carrier. Voiding is refused once a label has been used or already voided, or once it is past the carrier's void window. · *Shipping labels admin section* — A new Shipping labels section gives cross-order visibility: a status-filtered label list, the mint queue of labels awaiting a broker, and a broker-spend report totalling label cost grouped by carrier and currency over a date range.
+
+- v0.3.4 (2026-05-30) — **Sales-tax filings and remittance tracking in the admin console.** The admin console gains a Tax filings section for tracking sales-tax remittance across reporting periods. Open a filing period for a jurisdiction, compute the tax collected from completed orders in that window, then record the submission and the payment as you remit. Each filing carries a per-rate breakdown and an audit trail, and the list surfaces what's due soon or already overdue. A per-jurisdiction remittance report totals the tax owed across a date range. Every figure derives from completed orders — nothing in the storefront, cart, or checkout changes. **Added:** *Tax filings admin console* — A new Tax filings section tracks sales-tax remittance: open a filing period for a jurisdiction and reporting kind, compute the tax collected from completed orders in the window with a per-rate breakdown, then record submission and payment through the filing lifecycle. The list surfaces filings due soon or overdue, and a remittance report totals tax owed per jurisdiction across a date range. This is reporting only — it reads completed orders and changes nothing in checkout.
+
 - v0.3.3 (2026-05-30) — **Manage quantity-break (volume) pricing from the admin console.** The admin console gains a Quantity breaks section for creating and managing volume-pricing tier sets — buy-more-save-more rules scoped to a SKU, product, collection, vendor, category, or the whole store. Each set defines one or more quantity thresholds (e.g. buy 5, buy 10) with a percentage off, an amount off each unit, an amount off the line, or a fixed per-unit price, and can be marked exclusive or left to stack with others. A sample-price preview shows the discounted unit at each threshold before you commit, and sets archive and restore. The tiers take effect immediately on the product page, in the cart, and at checkout. **Added:** *Quantity Breaks admin console* — A new Quantity breaks section manages volume-pricing tier sets: create a set scoped to a SKU, product, collection, vendor, category, or globally; define one or more quantity thresholds with a percent-off, amount-off-each, amount-off-line, or fixed-per-unit discount; mark a set exclusive or let it stack. A sample-price preview shows the discounted unit at each threshold, and sets archive and restore. The tiers apply automatically on the product page, the cart, and at checkout.
 
 - v0.3.2 (2026-05-30) — **Creating a product lands you on its detail screen to finish setup.** Creating a product from the admin console now takes you straight to that product's detail screen — where you add a variant, set its price, and add stock — instead of returning you to the product list. A banner on the new product names the remaining steps to make it sellable. This removes the hunt-for-the-product-you-just-made step from the catalog setup flow. **Changed:** *Product create flows straight into editing* — Submitting the new-product form now redirects to the product's detail screen with a banner naming the next steps — add a variant with a SKU, set its price, and add stock — rather than bouncing back to the product list. Configuring a just-created product no longer requires finding it again first.

package/lib/admin.js

@@ -145,6 +145,11 @@ var _UPLOAD_IMAGE_CT = {
 // generic 413.
 var _UPLOAD_MAX_BYTES = b.constants.BYTES.mib(10);
 
+// Cap on the standalone shipping-labels list / pending-queue reads. Matches
+// the labels primitive's own MAX_PENDING_LIMIT so a console drain can never
+// ask for more than the primitive will return.
+var MAX_LABEL_LIST_LIMIT = 200;
+
 // ---- shared helpers -----------------------------------------------------
 
 function _parseEpochMs(str, label) {
@@ -438,6 +443,7 @@ function mount(router, deps) {
   var pickLists      = deps.pickLists      || null;  // warehouse pick-list console disabled when absent
   var shippingLabels = deps.shippingLabels || null;  // per-shipment carrier-label record disabled when absent
   var splitShipments = deps.splitShipments || null;  // order split-shipment planner disabled when absent
+  var salesTaxFilings = deps.salesTaxFilings || null; // sales-tax-filing remittance console disabled when absent
 
   // Which optional console sections are wired — gates their nav links so a
   // signed-in admin is never sent to a route that wasn't mounted. Passed
@@ -445,7 +451,7 @@ function mount(router, deps) {
   // `reports` is always present in the nav (read-only sales summary needs no
   // extra dep); its route mounts unconditionally and renders an unconfigured
   // notice when the salesReports primitive isn't wired.
-  var navAvailable = { returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, customerSurveys: !!deps.customerSurveys, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, autoDiscount: !!deps.autoDiscount, quantityDiscounts: !!deps.quantityDiscounts, pickLists: !!pickLists };
+  var navAvailable = { returns: !!returns, reviews: !!reviews, productQa: !!productQa, subscriptions: !!deps.subscriptions, webhooks: !!deps.webhooks, collections: !!deps.collections, customers: !!deps.customers, giftcards: !!deps.giftcards, announcementBar: !!deps.announcementBar, customerSurveys: !!deps.customerSurveys, businessHours: !!deps.businessHours, taxRates: !!deps.taxRates, shippingZones: !!deps.shippingZones, autoDiscount: !!deps.autoDiscount, quantityDiscounts: !!deps.quantityDiscounts, pickLists: !!pickLists, salesTaxFilings: !!salesTaxFilings, shippingLabels: !!shippingLabels };
 
   try { b.audit.registerNamespace(AUDIT_NAMESPACE); } catch (_e) { /* idempotent */ }
 
@@ -1670,6 +1676,46 @@ function mount(router, deps) {
         _redirect(res, "/admin/orders/" + enc + "?label=1");
       },
     ));
+
+    // Void a recorded label (broker void, within the 30-day window).
+    // purchased → voided. Mirrors the /used route: the primitive enforces
+    // the transition + window, a TypeError (bad id / missing reason) or a
+    // SHIPPING_LABELS_* coded error (wrong status / expired window) surfaces
+    // as a 400 on the JSON path and an `?err` notice on the browser path.
+    router.post("/admin/orders/:id/labels/:labelId/void", _pageOrApi(false,
+      W("order.shipment.label.void", async function (req, res) {
+        var body = req.body || {};
+        var out;
+        try {
+          out = await shippingLabels.voidLabel({ label_id: req.params.labelId, reason: body.reason });
+        } catch (e) {
+          if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message);
+          if (e && e.code && /SHIPPING_LABELS/.test(e.code)) return _problem(res, 400, "bad-request", e.message);
+          throw e;
+        }
+        _json(res, 200, out);
+        return { id: req.params.id };
+      }),
+      async function (req, res) {
+        var id = req.params.id;
+        var enc = encodeURIComponent(id);
+        var body = req.body || {};
+        try {
+          await shippingLabels.voidLabel({
+            label_id: req.params.labelId,
+            // A blank reason field reaches the primitive as undefined so the
+            // operator-facing "reason required" message surfaces, rather than
+            // the empty string slipping past the non-empty check.
+            reason: (body.reason && body.reason.length) ? body.reason : undefined,
+          });
+        } catch (e) {
+          if (!(e instanceof TypeError) && !(e && e.code && /SHIPPING_LABELS/.test(e.code))) throw e;
+          return _redirect(res, "/admin/orders/" + enc + "?err=1");
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".order.shipment.label.void", outcome: "success", metadata: { id: id, label_id: req.params.labelId } });
+        _redirect(res, "/admin/orders/" + enc + "?label=1");
+      },
+    ));
   }
 
   // Compose requestLabel + markPurchased into one recorded label. The
@@ -1712,6 +1758,206 @@ function mount(router, deps) {
     });
   }
 
+  // ---- shipping labels (standalone back-office console) ---------------
+  //
+  // A cross-order view of the carrier-label store, separate from the
+  // per-shipment panel on the order detail. Three screens, each composing
+  // a labels-primitive read:
+  //   - /admin/shipping-labels         — a status-filtered list. The
+  //       primitive exposes a list read per backable status: `pending`
+  //       (pendingLabels) and `voided` (voidedInWindow over a date range).
+  //       There is no cross-order list for purchased/used labels — those
+  //       are reached from their order detail — so the filter offers the
+  //       two engine-backed views, defaulting to pending.
+  //   - /admin/shipping-labels/costs   — broker-spend report grouped by
+  //       broker + currency over a date range (costsByPeriod).
+  //   - /admin/shipping-labels/pending — the mint queue (pendingLabels,
+  //       capped at 200) the operator's broker worker drains.
+  // Mounted only when the labels primitive is wired. Every HTML handler
+  // parses its from/to/carrier query params defensively: a malformed value
+  // re-renders the page with a correction notice (never a 500). The bearer
+  // JSON contract returns the same composed payload.
+  if (shippingLabels) {
+    // Resolve a {from, to} epoch-ms window from the query string, accepting
+    // either raw epoch-ms (from/to — machine clients) or calendar dates
+    // (from-date/to-date — the browser date inputs). `to-date` is the
+    // inclusive end day, advanced to the next UTC midnight. Throws TypeError
+    // on a malformed value; defaults to the trailing 30 days. Mirrors the
+    // reports window resolver so both report surfaces parse identically.
+    function _labelWindow(url) {
+      var from = _parseEpochMs(url && url.searchParams.get("from"), "from");
+      var to   = _parseEpochMs(url && url.searchParams.get("to"),   "to");
+      if (from == null) from = _parseDateParam(url && url.searchParams.get("from-date"), "from");
+      if (to == null) {
+        var toDate = _parseDateParam(url && url.searchParams.get("to-date"), "to");
+        if (toDate != null) to = toDate + b.constants.TIME.days(1);
+      }
+      var now = Date.now();
+      return {
+        to:   to   == null ? now : to,
+        from: from == null ? (now - b.constants.TIME.days(30)) : from,
+      };
+    }
+
+    // The status filter on the standalone list — only the values the
+    // primitive exposes a cross-order list read for.
+    function _labelStatusParam(url) {
+      var raw = url && url.searchParams.get("status");
+      if (raw == null || raw === "") return "pending";
+      if (raw !== "pending" && raw !== "voided") {
+        throw new TypeError("admin: status must be one of pending, voided");
+      }
+      return raw;
+    }
+
+    // Optional carrier filter for the costs report. Validated against the
+    // primitive's frozen enum so a bad value is a notice, not a 500.
+    function _labelCarrierParam(url) {
+      var raw = url && url.searchParams.get("carrier");
+      if (raw == null || raw === "") return null;
+      if (shippingLabels.CARRIERS.indexOf(raw) === -1) {
+        throw new TypeError("admin: carrier must be one of " + shippingLabels.CARRIERS.join(", "));
+      }
+      return raw;
+    }
+
+    // Compose the list payload for the chosen status. `pending` drains the
+    // queue (limit 200, ignoring the window — a pending label has no
+    // purchased/voided timestamp to range on); `voided` ranges voided_at
+    // over the window.
+    async function _labelListPayload(status, win) {
+      if (status === "voided") {
+        var voided = await shippingLabels.voidedInWindow({ from: win.from, to: win.to });
+        return { status: "voided", from: win.from, to: win.to, labels: voided };
+      }
+      var pending = await shippingLabels.pendingLabels({ limit: MAX_LABEL_LIST_LIMIT });
+      return { status: "pending", from: win.from, to: win.to, labels: pending };
+    }
+
+    router.get("/admin/shipping-labels", _pageOrApi(true,
+      R(async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var status, win;
+        try { status = _labelStatusParam(url); win = _labelWindow(url); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        var payload;
+        try { payload = await _labelListPayload(status, win); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 200, payload);
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var status = "pending", notice = null;
+        var win = { to: Date.now(), from: Date.now() - b.constants.TIME.days(30) };
+        try { status = _labelStatusParam(url); win = _labelWindow(url); }
+        catch (e) {
+          if (!(e instanceof TypeError)) throw e;
+          notice = e.message.replace(/^admin:\s*/, "");
+        }
+        var payload;
+        try { payload = await _labelListPayload(status, win); }
+        catch (e2) {
+          if (!(e2 instanceof TypeError)) throw e2;
+          // A bad range that slipped past the param parse (primitive
+          // re-validates from < to) → fall back to the default window.
+          win = { to: Date.now(), from: Date.now() - b.constants.TIME.days(30) };
+          notice = e2.message.replace(/^shipping-labels:\s*/, "");
+          payload = await _labelListPayload(status, win);
+        }
+        _sendHtml(res, 200, renderAdminShippingLabels({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          payload: payload, notice: notice,
+        }));
+      },
+    ));
+
+    router.get("/admin/shipping-labels/pending", _pageOrApi(true,
+      R(async function (req, res) {
+        var rows;
+        try { rows = await shippingLabels.pendingLabels({ limit: MAX_LABEL_LIST_LIMIT }); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 200, { limit: MAX_LABEL_LIST_LIMIT, labels: rows });
+      }),
+      async function (req, res) {
+        var rows = [], notice = null;
+        try { rows = await shippingLabels.pendingLabels({ limit: MAX_LABEL_LIST_LIMIT }); }
+        catch (e) {
+          if (!(e instanceof TypeError)) throw e;
+          notice = e.message.replace(/^shipping-labels:\s*/, "");
+        }
+        _sendHtml(res, 200, renderAdminShippingLabelsPending({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          labels: rows, notice: notice,
+        }));
+      },
+    ));
+
+    router.get("/admin/shipping-labels/costs", _pageOrApi(true,
+      R(async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var win, carrier;
+        try { win = _labelWindow(url); carrier = _labelCarrierParam(url); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        var report;
+        try { report = await _labelCostsReport(win, carrier); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 200, report);
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var notice = null, carrier = null;
+        var win = { to: Date.now(), from: Date.now() - b.constants.TIME.days(30) };
+        try { win = _labelWindow(url); carrier = _labelCarrierParam(url); }
+        catch (e) {
+          if (!(e instanceof TypeError)) throw e;
+          notice = e.message.replace(/^admin:\s*/, "");
+        }
+        var report;
+        try { report = await _labelCostsReport(win, carrier); }
+        catch (e2) {
+          if (!(e2 instanceof TypeError)) throw e2;
+          win = { to: Date.now(), from: Date.now() - b.constants.TIME.days(30) };
+          carrier = null;
+          notice = e2.message.replace(/^shipping-labels:\s*/, "");
+          report = await _labelCostsReport(win, carrier);
+        }
+        _sendHtml(res, 200, renderAdminShippingLabelCosts({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          report: report, carriers: shippingLabels.CARRIERS, notice: notice,
+        }));
+      },
+    ));
+  }
+
+  // Compose the broker-spend report: the per-(broker, currency) aggregate
+  // from costsByPeriod plus a per-currency rollup of the gross spend +
+  // label count across the window. `_strictMinorInt`-safe — the primitive
+  // already returns integer minor units; the rollup only sums them.
+  async function _labelCostsReport(win, carrier) {
+    var opts2 = { from: win.from, to: win.to };
+    if (carrier) opts2.carrier = carrier;
+    var rows = await shippingLabels.costsByPeriod(opts2);
+    var byCurrency = {};
+    for (var i = 0; i < rows.length; i += 1) {
+      var r = rows[i];
+      var cur = r.currency || "USD";
+      if (!byCurrency[cur]) byCurrency[cur] = { currency: cur, total_minor: 0, label_count: 0 };
+      // costsByPeriod coerces these to plain numbers already; treat them as
+      // integer minor units (admin never renders raw broker prose here).
+      byCurrency[cur].total_minor += _strictMinorInt(r.total_minor, "shippingLabels", "total_minor");
+      byCurrency[cur].label_count += _strictMinorInt(r.label_count, "shippingLabels", "label_count");
+    }
+    var totals = Object.keys(byCurrency).map(function (k) { return byCurrency[k]; });
+    totals.sort(function (a, c) { return a.currency < c.currency ? -1 : a.currency > c.currency ? 1 : 0; });
+    return {
+      from:     win.from,
+      to:       win.to,
+      carrier:  carrier || null,
+      by_broker: rows,
+      totals:    totals,
+    };
+  }
+
   // ---- split shipments (order-detail planner) -------------------------
   //
   // Splits one order into N parcels: ship some lines now, the rest later.
@@ -4582,6 +4828,252 @@ function mount(router, deps) {
     ));
   }
 
+  // ---- sales tax filings ----------------------------------------------
+  //
+  // Post-checkout remittance bookkeeping. Each row aggregates completed
+  // orders that fell inside a filing window for one jurisdiction, then
+  // walks the lifecycle the authority expects: draft → computed (the
+  // aggregation snapshot) → submitted (filed) → paid (remittance cleared),
+  // with an amend path for a correction. The console never touches cart /
+  // checkout / order pricing — it reads orders the storefront already
+  // wrote. A missing sales_tax_filings table only surfaces when a route
+  // reads it (degrades to a notice), never at boot.
+  if (salesTaxFilings) {
+    // Translate a create form / JSON body into a defineFilingPeriod input.
+    // The four window fields are epoch-ms; strict integer parsing so a
+    // typo is a 400, never a silent zero.
+    function _filingPeriodInput(body) {
+      return {
+        jurisdiction: typeof body.jurisdiction === "string" ? body.jurisdiction.trim().toUpperCase() : body.jurisdiction,
+        kind:         typeof body.kind === "string" ? body.kind.trim() : body.kind,
+        period_start: _strictMinorInt(body.period_start, "salesTaxFilings", "period_start (epoch-ms)"),
+        period_end:   _strictMinorInt(body.period_end,   "salesTaxFilings", "period_end (epoch-ms)"),
+        due_date:     _strictMinorInt(body.due_date,     "salesTaxFilings", "due_date (epoch-ms)"),
+      };
+    }
+
+    // Build the list-screen model: the filtered filings, the upcoming-due
+    // strip, and the filter values echoed back into the form. A malformed
+    // filter (bad jurisdiction / status) throws TypeError in the primitive
+    // — map it to an empty list so the page renders the notice, never 500.
+    async function _filingsForBrowser(filter) {
+      try { return await salesTaxFilings.listFilings(filter); }
+      catch (e) { if (e instanceof TypeError) return []; throw e; }
+    }
+    async function _upcomingForBrowser() {
+      try { return await salesTaxFilings.upcomingDue({ days_ahead: 30 }); }
+      catch (e) { if (e instanceof TypeError) return []; throw e; }
+    }
+
+    router.get("/admin/tax-filings", _pageOrApi(true,
+      R(async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var filter = {};
+        var j = url && url.searchParams.get("jurisdiction");
+        var s = url && url.searchParams.get("status");
+        if (j) filter.jurisdiction = String(j).trim().toUpperCase();
+        if (s) filter.status = String(s).trim();
+        var rows;
+        try { rows = await salesTaxFilings.listFilings(filter); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 200, { rows: rows });
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var j = url && url.searchParams.get("jurisdiction");
+        var s = url && url.searchParams.get("status");
+        var jurisdiction = j ? String(j).trim().toUpperCase() : null;
+        var status       = s ? String(s).trim() : null;
+        var filter = {};
+        if (jurisdiction) filter.jurisdiction = jurisdiction;
+        if (status)       filter.status = status;
+        var rows     = await _filingsForBrowser(filter);
+        var upcoming = await _upcomingForBrowser();
+        _sendHtml(res, 200, renderAdminTaxFilings({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          filings: rows, upcoming: upcoming,
+          jurisdiction: jurisdiction, status_filter: status,
+          kinds: salesTaxFilings.KINDS, statuses: salesTaxFilings.STATUSES,
+          created:  url && url.searchParams.get("created"),
+          notice:   (url && url.searchParams.get("err")) ? "That action couldn't be completed for the filing." : null,
+        }));
+      },
+    ));
+
+    // Open a filing period → draft row. A duplicate (jurisdiction, kind,
+    // period_start) is refused by the primitive's UNIQUE index; surface it
+    // as a 400 notice rather than a 500.
+    router.post("/admin/tax-filings", _pageOrApi(false,
+      W("tax_filing.create", async function (req, res) {
+        var filing;
+        try { filing = await salesTaxFilings.defineFilingPeriod(_filingPeriodInput(req.body || {})); }
+        catch (e) {
+          if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message);
+          if (e.code === "SALES_TAX_FILING_DUPLICATE") return _problem(res, 409, "filing-duplicate", e.message);
+          throw e;
+        }
+        _json(res, 201, filing);
+        return { id: filing.id };
+      }),
+      async function (req, res) {
+        var filing;
+        try { filing = await salesTaxFilings.defineFilingPeriod(_filingPeriodInput(req.body || {})); }
+        catch (e) {
+          if (!(e instanceof TypeError) && e.code !== "SALES_TAX_FILING_DUPLICATE") throw e;
+          var rows     = await _filingsForBrowser({});
+          var upcoming = await _upcomingForBrowser();
+          return _sendHtml(res, 400, renderAdminTaxFilings({
+            shop_name: deps.shop_name, nav_available: navAvailable,
+            filings: rows, upcoming: upcoming,
+            kinds: salesTaxFilings.KINDS, statuses: salesTaxFilings.STATUSES,
+            notice: (e && e.message || "").replace(/^salesTaxFilings[.:]\s*/, ""),
+          }));
+        }
+        b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".tax_filing.create", outcome: "success", metadata: { id: filing.id } });
+        _redirect(res, "/admin/tax-filings/" + encodeURIComponent(filing.id) + "?created=1");
+      },
+    ));
+
+    // Per-jurisdiction remittance report over a [from, to] window. GET so
+    // the window lives in the URL (bookmarkable). A bad / missing range is
+    // a notice on the list page, not a 500.
+    router.get("/admin/tax-filings/report", _pageOrApi(true,
+      R(async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var j = url && url.searchParams.get("jurisdiction");
+        if (!j) return _problem(res, 400, "bad-request", "jurisdiction required");
+        var from = _parseEpochMs(url && url.searchParams.get("from"), "from");
+        var to   = _parseEpochMs(url && url.searchParams.get("to"),   "to");
+        if (from == null || to == null) return _problem(res, 400, "bad-request", "from and to (epoch-ms) required");
+        var report;
+        try { report = await salesTaxFilings.auditReportForJurisdiction({ jurisdiction: String(j).trim().toUpperCase(), from: from, to: to }); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message); throw e; }
+        _json(res, 200, report);
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var j = url && url.searchParams.get("jurisdiction");
+        var jurisdiction = j ? String(j).trim().toUpperCase() : null;
+        // Parse the window defensively — a present-but-malformed epoch throws
+        // TypeError; treat it as unset so the window notice guides the operator
+        // (a bad range is a notice on this page, never a 500).
+        var from = null, to = null;
+        try {
+          from = _parseEpochMs(url && url.searchParams.get("from"), "from");
+          to   = _parseEpochMs(url && url.searchParams.get("to"),   "to");
+        } catch (e) { if (!(e instanceof TypeError)) throw e; }
+        var report = null, notice = null;
+        if (!jurisdiction) {
+          notice = "Enter a jurisdiction and a window to run a remittance report.";
+        } else if (from == null || to == null) {
+          notice = "Enter both a from and a to date (epoch-ms) for the report window.";
+        } else {
+          try { report = await salesTaxFilings.auditReportForJurisdiction({ jurisdiction: jurisdiction, from: from, to: to }); }
+          catch (e) { if (!(e instanceof TypeError)) throw e; notice = (e.message || "").replace(/^salesTaxFilings[.:]\s*/, ""); }
+        }
+        _sendHtml(res, 200, renderAdminTaxFilingReport({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          report: report, jurisdiction: jurisdiction, notice: notice,
+        }));
+      },
+    ));
+
+    async function _filingDetailModel(id) {
+      return await salesTaxFilings.getFiling(id);
+    }
+
+    router.get("/admin/tax-filings/:id", _pageOrApi(true,
+      R(async function (req, res) {
+        var filing;
+        try { filing = await _filingDetailModel(req.params.id); }
+        catch (e) { if (e instanceof TypeError) return _problem(res, 404, "filing-not-found", e.message); throw e; }
+        if (!filing) return _problem(res, 404, "filing-not-found");
+        _json(res, 200, filing);
+      }),
+      async function (req, res) {
+        var url = req.url ? new URL(req.url, "http://localhost") : null;
+        var filing;
+        try { filing = await _filingDetailModel(req.params.id); }
+        catch (e) { if (!(e instanceof TypeError)) throw e; filing = null; }
+        if (!filing) return _sendHtml(res, 404, renderAdminTaxFilings({
+          shop_name: deps.shop_name, nav_available: navAvailable,
+          filings: [], upcoming: [], kinds: salesTaxFilings.KINDS, statuses: salesTaxFilings.STATUSES,
+          notice: "Filing not found.",
+        }));
+        _sendHtml(res, 200, renderAdminTaxFiling({
+          shop_name: deps.shop_name, nav_available: navAvailable, filing: filing,
+          computed: url && url.searchParams.get("computed"),
+          created:  url && url.searchParams.get("created"),
+          submitted: url && url.searchParams.get("submitted"),
+          paid:     url && url.searchParams.get("paid"),
+          amended:  url && url.searchParams.get("amended"),
+          notice:   (url && url.searchParams.get("err"))
+            ? String(url.searchParams.get("err_msg") || "That action couldn't be completed for the filing.")
+            : null,
+        }));
+      },
+    ));
+
+    // Lifecycle transitions — each is a browser POST that PRGs back to the
+    // detail. A bad transition (wrong status) or bad input is a ?err notice
+    // on the detail page, never a 500. The bearer JSON contract returns the
+    // updated filing (or a problem document).
+    function _filingActionRoute(suffix, audit, okParam, run) {
+      router.post("/admin/tax-filings/:id/" + suffix, _pageOrApi(false,
+        W("tax_filing." + audit, async function (req, res) {
+          var filing;
+          try { filing = await run(req.params.id, req.body || {}); }
+          catch (e) {
+            if (e instanceof TypeError) return _problem(res, 400, "bad-request", e.message);
+            if (e.code === "SALES_TAX_FILING_NOT_FOUND") return _problem(res, 404, "filing-not-found", e.message);
+            if (e.code === "SALES_TAX_FILING_BAD_TRANSITION") return _problem(res, 409, "filing-bad-transition", e.message);
+            throw e;
+          }
+          _json(res, 200, filing);
+          return { id: filing.id };
+        }),
+        async function (req, res) {
+          var enc = encodeURIComponent(req.params.id);
+          try {
+            await run(req.params.id, req.body || {});
+          } catch (e) {
+            if (!(e instanceof TypeError) &&
+                e.code !== "SALES_TAX_FILING_NOT_FOUND" &&
+                e.code !== "SALES_TAX_FILING_BAD_TRANSITION") throw e;
+            var msg = (e && e.message || "").replace(/^salesTaxFilings[.:]\s*/, "");
+            return _redirect(res, "/admin/tax-filings/" + enc + "?err=1&err_msg=" + encodeURIComponent(msg));
+          }
+          b.audit.safeEmit({ action: AUDIT_NAMESPACE + ".tax_filing." + audit, outcome: "success", metadata: { id: req.params.id } });
+          _redirect(res, "/admin/tax-filings/" + enc + "?" + okParam + "=1");
+        },
+      ));
+    }
+
+    _filingActionRoute("compute", "compute", "computed", function (id) {
+      return salesTaxFilings.computeFiling({ filing_id: id });
+    });
+    _filingActionRoute("submit", "submit", "submitted", function (id, body) {
+      return salesTaxFilings.recordSubmission({
+        filing_id:      id,
+        submission_ref: typeof body.submission_ref === "string" ? body.submission_ref.trim() : body.submission_ref,
+        submitted_by:   typeof body.submitted_by === "string" ? body.submitted_by.trim() : body.submitted_by,
+      });
+    });
+    _filingActionRoute("pay", "pay", "paid", function (id, body) {
+      return salesTaxFilings.recordPayment({
+        filing_id:     id,
+        payment_minor: _strictMinorInt(body.payment_minor, "salesTaxFilings", "payment_minor"),
+        payment_ref:   typeof body.payment_ref === "string" ? body.payment_ref.trim() : body.payment_ref,
+      });
+    });
+    _filingActionRoute("amend", "amend", "amended", function (id, body) {
+      return salesTaxFilings.markAmended({
+        filing_id: id,
+        reason:    typeof body.reason === "string" ? body.reason.trim() : body.reason,
+      });
+    });
+  }
+
   // Read a jurisdiction's rate history for the browser list. A null /
   // unset jurisdiction yields an empty list (the page shows the picker
   // form). A malformed jurisdiction throws TypeError in the primitive —
@@ -5645,7 +6137,9 @@ var ADMIN_NAV_ITEMS = [
   { key: "discounts",    href: "/admin/discounts",    label: "Discounts",    requires: "autoDiscount" },
   { key: "quantity-discounts", href: "/admin/quantity-discounts", label: "Quantity breaks", requires: "quantityDiscounts" },
   { key: "tax",          href: "/admin/tax-rates",    label: "Tax",          requires: "taxRates" },
+  { key: "tax-filings",  href: "/admin/tax-filings",  label: "Tax filings",  requires: "salesTaxFilings" },
   { key: "shipping",     href: "/admin/shipping",     label: "Shipping",     requires: "shippingZones" },
+  { key: "shipping-labels", href: "/admin/shipping-labels", label: "Shipping labels", requires: "shippingLabels" },
   { key: "pick-lists",   href: "/admin/pick-lists",   label: "Pick lists",   requires: "pickLists" },
   { key: "announcements", href: "/admin/announcements", label: "Announcements", requires: "announcementBar" },
   { key: "surveys",      href: "/admin/surveys",      label: "Surveys",      requires: "customerSurveys" },
@@ -6048,6 +6542,173 @@ function renderAdminReports(opts) {
   return _renderAdminShell(opts.shop_name, "Reports", body, "reports", opts.nav_available);
 }
 
+// A single shipping-label row for the standalone cross-order tables. Shows
+// carrier + service, tracking number, cost (via pricing.format from the
+// label's own minor units + currency), the broker it came from, its status
+// pill, and a link to the broker's label URL. Read-only — lifecycle actions
+// (mark used / void) live on the order detail where the shipment context is.
+function _shippingLabelRow(l) {
+  var costCell = (l.cost_minor != null && l.currency)
+    ? _htmlEscape(pricing.format(l.cost_minor, l.currency))
+    : "<span class=\"meta\">—</span>";
+  var trackCell = l.tracking_number
+    ? "<code class=\"order-id\">" + _htmlEscape(String(l.tracking_number)) + "</code>"
+    : "<span class=\"meta\">—</span>";
+  var urlCell = l.label_url
+    ? "<a class=\"order-id\" href=\"" + _htmlEscape(String(l.label_url)) + "\" rel=\"noopener nofollow\" target=\"_blank\">Open ↗</a>"
+    : "<span class=\"meta\">—</span>";
+  var viaCell = l.purchased_via
+    ? _htmlEscape(String(l.purchased_via))
+    : "<span class=\"meta\">—</span>";
+  return "<tr>" +
+    "<td>" + _htmlEscape(String(l.carrier)) + " <span class=\"meta\">" + _htmlEscape(String(l.service_level || "")) + "</span></td>" +
+    "<td>" + trackCell + "</td>" +
+    "<td class=\"num\">" + costCell + "</td>" +
+    "<td>" + viaCell + "</td>" +
+    "<td><span class=\"status-pill " + _htmlEscape(String(l.status)) + "\">" + _htmlEscape(String(l.status)) + "</span></td>" +
+    "<td>" + urlCell + "</td>" +
+    "<td>" + _htmlEscape(_fmtDate(l.created_at)) + "</td>" +
+  "</tr>";
+}
+
+// Sub-nav shared by the three standalone shipping-label screens — the
+// list, the broker-spend report, and the mint queue.
+function _shippingLabelSubnav(active) {
+  var tabs = [
+    ["list",    "/admin/shipping-labels",         "All labels"],
+    ["pending", "/admin/shipping-labels/pending", "Mint queue"],
+    ["costs",   "/admin/shipping-labels/costs",   "Broker spend"],
+  ];
+  return "<div class=\"order-filters\">" + tabs.map(function (t) {
+    return "<a class=\"chip" + (active === t[0] ? " chip--on" : "") + "\" href=\"" + t[1] + "\">" + _htmlEscape(t[2]) + "</a>";
+  }).join("") + "</div>";
+}
+
+// Standalone cross-order label list. The primitive exposes a list read for
+// two statuses — pending (the mint queue) and voided (over a date range) —
+// so the status filter offers those two. Purchased + used labels are
+// reached from their order's detail panel, not browsed cross-order. A date
+// range narrows the voided view (ignored for pending, which has no
+// purchased/voided timestamp to range on).
+function renderAdminShippingLabels(opts) {
+  opts = opts || {};
+  var payload = opts.payload || { status: "pending", labels: [], from: Date.now(), to: Date.now() };
+  var notice = opts.notice ? "<div class=\"banner banner--warn\">" + _htmlEscape(opts.notice) + "</div>" : "";
+  var labels = payload.labels || [];
+  var status = payload.status || "pending";
+
+  var statuses = [["pending", "Pending"], ["voided", "Voided"]];
+  var chips = "<div class=\"order-filters\">" + statuses.map(function (s) {
+    return "<a class=\"chip" + (status === s[0] ? " chip--on" : "") + "\" href=\"/admin/shipping-labels?status=" + encodeURIComponent(s[0]) + "\">" + _htmlEscape(s[1]) + "</a>";
+  }).join("") + "</div>";
+
+  // Date-range form only narrows the voided view (GET so the window lives in
+  // the URL). For pending it's still shown for consistency but the window is
+  // not applied.
+  var fromVal = _dateInputValue(payload.from);
+  var toVal   = _dateInputValue((payload.to || Date.now()) - b.constants.TIME.days(1));
+  var rangeForm =
+    "<form method=\"get\" action=\"/admin/shipping-labels\" class=\"order-filters\">" +
+      "<input type=\"hidden\" name=\"status\" value=\"" + _htmlEscape(status) + "\">" +
+      "<label class=\"form-field\"><span>From</span><input type=\"date\" name=\"from-date\" value=\"" + _htmlEscape(fromVal) + "\"></label>" +
+      "<label class=\"form-field\"><span>To</span><input type=\"date\" name=\"to-date\" value=\"" + _htmlEscape(toVal) + "\"></label>" +
+      "<button class=\"btn\" type=\"submit\">Apply</button>" +
+    "</form>";
+
+  var rows = labels.map(_shippingLabelRow).join("");
+  var table = labels.length
+    ? "<div class=\"panel\"><table><thead><tr><th scope=\"col\">Carrier</th><th scope=\"col\">Tracking</th><th scope=\"col\" class=\"num\">Cost</th><th scope=\"col\">Broker</th><th scope=\"col\">Status</th><th scope=\"col\">Label</th><th scope=\"col\">Created</th></tr></thead><tbody>" + rows + "</tbody></table></div>"
+    : "<p class=\"empty\">No " + _htmlEscape(status) + " labels" + (status === "voided" ? " in this window" : "") + ".</p>";
+
+  var body =
+    "<section><h2>Shipping labels</h2>" + notice +
+      _shippingLabelSubnav("list") +
+      chips +
+      (status === "voided" ? rangeForm : "") +
+      table +
+    "</section>";
+  return _renderAdminShell(opts.shop_name, "Shipping labels", body, "shipping-labels", opts.nav_available);
+}
+
+// The mint queue: pending labels awaiting a broker mint, oldest first. The
+// operator's broker worker drains this (requestLabel wrote each row;
+// markPurchased clears it). Read-only console view of the same queue.
+function renderAdminShippingLabelsPending(opts) {
+  opts = opts || {};
+  var labels = opts.labels || [];
+  var notice = opts.notice ? "<div class=\"banner banner--warn\">" + _htmlEscape(opts.notice) + "</div>" : "";
+  var rows = labels.map(_shippingLabelRow).join("");
+  var table = labels.length
+    ? "<div class=\"panel\"><table><thead><tr><th scope=\"col\">Carrier</th><th scope=\"col\">Tracking</th><th scope=\"col\" class=\"num\">Cost</th><th scope=\"col\">Broker</th><th scope=\"col\">Status</th><th scope=\"col\">Label</th><th scope=\"col\">Created</th></tr></thead><tbody>" + rows + "</tbody></table></div>"
+    : "<p class=\"empty\">No labels awaiting a broker mint.</p>";
+  var body =
+    "<section><h2>Shipping labels</h2>" + notice +
+      _shippingLabelSubnav("pending") +
+      "<p class=\"meta\">Pending labels awaiting a broker mint, oldest first (up to " + String(MAX_LABEL_LIST_LIMIT) + ").</p>" +
+      table +
+    "</section>";
+  return _renderAdminShell(opts.shop_name, "Shipping labels", body, "shipping-labels", opts.nav_available);
+}
+
+// Broker-spend report: gross label spend + label count grouped by broker +
+// currency over a date range, with an optional carrier filter and a
+// per-currency headline rollup. Money formats through the same pricing
+// helper the order + reports pages use.
+function renderAdminShippingLabelCosts(opts) {
+  opts = opts || {};
+  var report = opts.report || { from: Date.now(), to: Date.now(), by_broker: [], totals: [], carrier: null };
+  var carriers = opts.carriers || [];
+  var notice = opts.notice ? "<div class=\"banner banner--warn\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  var fromVal = _dateInputValue(report.from);
+  var toVal   = _dateInputValue(report.to - b.constants.TIME.days(1));
+  var carrierOpts = "<option value=\"\">All carriers</option>" + carriers.map(function (c) {
+    return "<option value=\"" + _htmlEscape(c) + "\"" + (report.carrier === c ? " selected" : "") + ">" + _htmlEscape(c) + "</option>";
+  }).join("");
+  var rangeForm =
+    "<form method=\"get\" action=\"/admin/shipping-labels/costs\" class=\"order-filters\">" +
+      "<label class=\"form-field\"><span>From</span><input type=\"date\" name=\"from-date\" value=\"" + _htmlEscape(fromVal) + "\"></label>" +
+      "<label class=\"form-field\"><span>To</span><input type=\"date\" name=\"to-date\" value=\"" + _htmlEscape(toVal) + "\"></label>" +
+      "<label class=\"form-field\"><span>Carrier</span><select name=\"carrier\">" + carrierOpts + "</select></label>" +
+      "<button class=\"btn\" type=\"submit\">Apply</button>" +
+    "</form>";
+
+  // Per-currency headline cards — total gross spend + label count.
+  var totals = report.totals || [];
+  var statsBlock = totals.length
+    ? "<section><h2>Total spend</h2><div class=\"stat-grid\">" + totals.map(function (t) {
+        return _statCard("Spend (" + t.currency + ")", pricing.format(t.total_minor, t.currency)) +
+          _statCard("Labels (" + t.currency + ")", String(t.label_count));
+      }).join("") + "</div></section>"
+    : "<section><h2>Total spend</h2><p class=\"empty\">No labels purchased in this window.</p></section>";
+
+  var byBroker = report.by_broker || [];
+  var brokerRows = byBroker.length
+    ? byBroker.map(function (r) {
+        return "<tr>" +
+          "<td>" + _htmlEscape(String(r.purchased_via)) + "</td>" +
+          "<td>" + _htmlEscape(String(r.currency)) + "</td>" +
+          "<td class=\"num\">" + _htmlEscape(String(r.label_count)) + "</td>" +
+          "<td class=\"num\">" + _htmlEscape(pricing.format(r.total_minor, r.currency)) + "</td>" +
+        "</tr>";
+      }).join("")
+    : "<tr><td colspan=\"4\" class=\"empty\">No labels purchased in this window.</td></tr>";
+  var brokerBlock =
+    "<section><h2>By broker</h2><div class=\"panel\">" +
+      "<table><thead><tr><th scope=\"col\">Broker</th><th scope=\"col\">Currency</th><th scope=\"col\" class=\"num\">Labels</th><th scope=\"col\" class=\"num\">Spend</th></tr></thead><tbody>" + brokerRows + "</tbody></table>" +
+    "</div></section>";
+
+  var body =
+    "<section><h2>Shipping labels</h2>" + notice +
+      _shippingLabelSubnav("costs") +
+      "<p class=\"meta\">Window: " + _htmlEscape(_fmtDate(report.from)) + " → " + _htmlEscape(_fmtDate(report.to)) +
+        (report.carrier ? " · carrier " + _htmlEscape(String(report.carrier)) : "") + "</p>" +
+      rangeForm +
+    "</section>" +
+    statsBlock + brokerBlock;
+  return _renderAdminShell(opts.shop_name, "Shipping labels", body, "shipping-labels", opts.nav_available);
+}
+
 function renderAdminOrder(opts) {
   opts = opts || {};
   var o = opts.order;
@@ -6258,17 +6919,26 @@ function _orderLabelPanel(orderId, shipment, carriers, packageTypes, purchasedVi
     var urlCell = l.label_url
       ? "<a class=\"order-id\" href=\"" + _htmlEscape(String(l.label_url)) + "\" rel=\"noopener nofollow\" target=\"_blank\">Open ↗</a>"
       : "<span class=\"meta\">—</span>";
-    var usedForm = (l.status === "purchased")
-      ? "<form method=\"post\" action=\"/admin/orders/" + _htmlEscape(orderId) + "/labels/" + _htmlEscape(l.id) + "/used\" class=\"form-inline\">" +
-          "<button class=\"btn btn--ghost\" type=\"submit\">Mark used</button></form>"
-      : "<span class=\"meta\">—</span>";
+    // A purchased label can be marked used (handed to the carrier) OR voided
+    // (broker void, within the 30-day window). The void form carries a
+    // required reason input so the operator records WHY before the POST; the
+    // primitive refuses a blank/expired void with a 400 → notice.
+    var actionCell = "<span class=\"meta\">—</span>";
+    if (l.status === "purchased") {
+      actionCell =
+        "<form method=\"post\" action=\"/admin/orders/" + _htmlEscape(orderId) + "/labels/" + _htmlEscape(l.id) + "/used\" class=\"form-inline\">" +
+          "<button class=\"btn btn--ghost\" type=\"submit\">Mark used</button></form> " +
+        "<form method=\"post\" action=\"/admin/orders/" + _htmlEscape(orderId) + "/labels/" + _htmlEscape(l.id) + "/void\" class=\"form-inline\">" +
+          "<input type=\"text\" name=\"reason\" placeholder=\"Void reason\" maxlength=\"512\" aria-label=\"Void reason\" required>" +
+          "<button class=\"btn btn--danger\" type=\"submit\">Void</button></form>";
+    }
     return "<tr>" +
       "<td>" + _htmlEscape(String(l.carrier)) + " <span class=\"meta\">" + _htmlEscape(String(l.service_level || "")) + "</span></td>" +
       "<td>" + trackCell + "</td>" +
       "<td class=\"num\">" + costCell + "</td>" +
       "<td><span class=\"status-pill " + _htmlEscape(l.status) + "\">" + _htmlEscape(l.status) + "</span></td>" +
       "<td>" + urlCell + "</td>" +
-      "<td>" + usedForm + "</td>" +
+      "<td>" + actionCell + "</td>" +
     "</tr>";
   }).join("");
   var labelsTable = labels.length
@@ -7166,6 +7836,280 @@ function renderAdminTaxRates(opts) {
   return _renderAdminShell(opts.shop_name, "Tax rates", body, "tax", opts.nav_available);
 }
 
+// Money for the filings screens. A filing aggregates orders that may span
+// currencies, so the row stores raw minor-unit totals with no single
+// currency column. Display them through the same pricing formatter the rest
+// of the console uses, in the operator's display currency (defaults to USD)
+// — the number is the reconciliation figure regardless of the symbol.
+var TAX_FILING_DISPLAY_CURRENCY = "USD";
+function _filingMoney(minor) {
+  return pricing.format(Number(minor) || 0, TAX_FILING_DISPLAY_CURRENCY);
+}
+
+// Sales-tax-filings list screen — open filings (filterable by jurisdiction
+// + status), an upcoming-due strip, and the open-a-period form. Read-heavy:
+// the lifecycle actions live on each filing's detail page.
+function renderAdminTaxFilings(opts) {
+  opts = opts || {};
+  var filings  = opts.filings  || [];
+  var upcoming = opts.upcoming || [];
+  var kinds    = opts.kinds    || ["monthly", "quarterly", "annual"];
+  var statuses = opts.statuses || ["draft", "computed", "submitted", "paid", "amended"];
+  var jurisdiction = opts.jurisdiction || "";
+  var statusFilter = opts.status_filter || "";
+  var created = opts.created ? "<div class=\"banner banner--ok\">Filing period opened.</div>" : "";
+  var notice  = opts.notice  ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+
+  // Status pill class reuse: map filing status onto the order pill palette so
+  // the visual language matches the rest of the console.
+  function _statusPill(s) {
+    var cls = s === "paid" ? "paid"
+            : s === "submitted" ? "shipped"
+            : s === "computed" ? "fulfilling"
+            : s === "amended" ? "cancelled"
+            : "pending";
+    return "<span class=\"status-pill " + cls + "\">" + _htmlEscape(s) + "</span>";
+  }
+
+  // Filter form — jurisdiction text + status select. GET so the filter
+  // lives in the URL.
+  var statusOpts = [{ value: "", label: "All statuses" }].concat(statuses.map(function (s) { return { value: s, label: s }; }));
+  var filterForm =
+    "<form method=\"get\" action=\"/admin/tax-filings\" class=\"order-filters\">" +
+      "<label class=\"form-field\"><span>Jurisdiction</span>" +
+        "<input type=\"text\" name=\"jurisdiction\" value=\"" + _htmlEscape(jurisdiction) + "\" placeholder=\"US or US-CA\" maxlength=\"6\" class=\"input-code\"></label>" +
+      _selectField("Status", "status", statusOpts, statusFilter, "", "") +
+      "<button class=\"btn\" type=\"submit\">Filter</button>" +
+      "<a class=\"btn btn--ghost\" href=\"/admin/tax-filings\">Clear</a>" +
+    "</form>";
+
+  // Due/overdue strip — open filings due within the next 30 days OR already
+  // past their due date (upcomingDue filters due_date <= now+30d, no lower bound).
+  var dueRows = upcoming.map(function (f) {
+    return "<tr>" +
+      "<td><a class=\"order-id\" href=\"/admin/tax-filings/" + _htmlEscape(f.id) + "\">" + _htmlEscape(f.jurisdiction) + "</a></td>" +
+      "<td>" + _htmlEscape(f.kind) + "</td>" +
+      "<td>" + _statusPill(f.status) + "</td>" +
+      "<td>" + _htmlEscape(_fmtDate(f.due_date)) + "</td>" +
+      "</tr>";
+  }).join("");
+  var dueBlock = upcoming.length
+    ? "<section><h2>Due soon or overdue</h2><div class=\"panel\">" +
+        "<table><thead><tr><th scope=\"col\">Jurisdiction</th><th scope=\"col\">Period</th><th scope=\"col\">Status</th><th scope=\"col\">Due</th></tr></thead><tbody>" + dueRows + "</tbody></table>" +
+      "</div></section>"
+    : "";
+
+  // Filings table.
+  var rows = filings.map(function (f) {
+    return "<tr>" +
+      "<td><a class=\"order-id\" href=\"/admin/tax-filings/" + _htmlEscape(f.id) + "\">" + _htmlEscape(f.jurisdiction) + "</a></td>" +
+      "<td>" + _htmlEscape(f.kind) + "</td>" +
+      "<td>" + _htmlEscape(_fmtDate(f.period_start)) + " → " + _htmlEscape(_fmtDate(f.period_end)) + "</td>" +
+      "<td>" + _htmlEscape(_fmtDate(f.due_date)) + "</td>" +
+      "<td>" + _statusPill(f.status) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(_filingMoney(f.tax_collected_minor)) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(_filingMoney(f.tax_owed_minor)) + "</td>" +
+      "</tr>";
+  }).join("");
+  var table = filings.length
+    ? "<div class=\"panel\"><table><thead><tr><th scope=\"col\">Jurisdiction</th><th scope=\"col\">Kind</th><th scope=\"col\">Period</th><th scope=\"col\">Due</th><th scope=\"col\">Status</th><th scope=\"col\" class=\"num\">Collected</th><th scope=\"col\" class=\"num\">Owed</th></tr></thead><tbody>" + rows + "</tbody></table></div>"
+    : "<p class=\"empty\">No filings" + (jurisdiction ? " for " + _htmlEscape(jurisdiction) : "") + " yet. Open a period below.</p>";
+
+  // Open-a-period form.
+  var kindOpts = kinds.map(function (k) { return { value: k, label: k }; });
+  var createForm =
+    "<div class=\"panel mt mw-34\">" +
+      "<h3 class=\"subhead\">Open a filing period</h3>" +
+      "<form method=\"post\" action=\"/admin/tax-filings\">" +
+        _setupField("Jurisdiction", "jurisdiction", "", "text", "ISO 3166-1 country, optionally -subdivision (e.g. US, US-CA, DE-BY).", " maxlength=\"6\" class=\"input-code\" required") +
+        _selectField("Kind", "kind", kindOpts, "quarterly", "Filing cadence the authority expects.", " required") +
+        _setupField("Period start (epoch-ms)", "period_start", "", "number", "First instant of the filing window.", " min=\"0\" required") +
+        _setupField("Period end (epoch-ms)", "period_end", "", "number", "Exclusive end of the window (must be after start).", " min=\"0\" required") +
+        _setupField("Due date (epoch-ms)", "due_date", "", "number", "When the filing is due (must be on or after the period end).", " min=\"0\" required") +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Open period</button></div>" +
+      "</form>" +
+    "</div>";
+
+  // Report shortcut.
+  var reportForm =
+    "<div class=\"panel mt mw-34\">" +
+      "<h3 class=\"subhead\">Remittance report</h3>" +
+      "<form method=\"get\" action=\"/admin/tax-filings/report\">" +
+        _setupField("Jurisdiction", "jurisdiction", jurisdiction, "text", "Roll up every filing whose period intersects the window.", " maxlength=\"6\" class=\"input-code\" required") +
+        _setupField("From (epoch-ms)", "from", "", "number", "Window start.", " min=\"0\" required") +
+        _setupField("To (epoch-ms)", "to", "", "number", "Window end.", " min=\"0\" required") +
+        "<div class=\"actions-row\"><button class=\"btn btn--ghost\" type=\"submit\">Run report</button></div>" +
+      "</form>" +
+    "</div>";
+
+  var body =
+    "<section><h2>Sales tax filings</h2>" + created + notice + filterForm + table + "</section>" +
+    dueBlock +
+    "<section><div class=\"two-col\">" + createForm + reportForm + "</div></section>";
+  return _renderAdminShell(opts.shop_name, "Tax filings", body, "tax-filings", opts.nav_available);
+}
+
+// Sales-tax-filing detail — the snapshot totals, the per-rate breakdown, the
+// audit trail, and the lifecycle action forms gated on the filing's status.
+function renderAdminTaxFiling(opts) {
+  opts = opts || {};
+  var f = opts.filing;
+  var banners =
+    (opts.created   ? "<div class=\"banner banner--ok\">Filing period opened.</div>" : "") +
+    (opts.computed  ? "<div class=\"banner banner--ok\">Snapshot computed.</div>" : "") +
+    (opts.submitted ? "<div class=\"banner banner--ok\">Submission recorded.</div>" : "") +
+    (opts.paid      ? "<div class=\"banner banner--ok\">Payment recorded.</div>" : "") +
+    (opts.amended   ? "<div class=\"banner banner--ok\">Filing amended.</div>" : "") +
+    (opts.notice    ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "");
+  if (!f) {
+    return _renderAdminShell(opts.shop_name, "Filing", "<section><h2>Filing</h2>" + banners + "<p class=\"empty\">Filing not found.</p></section>", "tax-filings", opts.nav_available);
+  }
+  var enc = encodeURIComponent(f.id);
+
+  var meta =
+    "<section><h2>" + _htmlEscape(f.jurisdiction) + " · " + _htmlEscape(f.kind) + "</h2>" + banners +
+      "<p class=\"meta\">Window: " + _htmlEscape(_fmtDate(f.period_start)) + " → " + _htmlEscape(_fmtDate(f.period_end)) +
+        " · Due " + _htmlEscape(_fmtDate(f.due_date)) +
+        " · Status <span class=\"status-pill " + _htmlEscape(f.status) + "\">" + _htmlEscape(f.status) + "</span></p>" +
+    "</section>";
+
+  var stats =
+    "<section><h2>Snapshot</h2><div class=\"stat-grid\">" +
+      _statCard("Gross revenue", _filingMoney(f.gross_revenue_minor)) +
+      _statCard("Taxable revenue", _filingMoney(f.taxable_revenue_minor)) +
+      _statCard("Exempt revenue", _filingMoney(f.exempt_revenue_minor)) +
+      _statCard("Tax collected", _filingMoney(f.tax_collected_minor)) +
+      _statCard("Tax owed", _filingMoney(f.tax_owed_minor), true) +
+    "</div>" +
+    (f.computed_at == null ? "<p class=\"meta\">Not computed yet — run the snapshot to aggregate orders in the window.</p>"
+                           : "<p class=\"meta\">Computed " + _htmlEscape(_fmtDate(f.computed_at)) + ".</p>") +
+    "</section>";
+
+  // Per-rate breakdown table — one row per rate bucket the snapshot produced.
+  var breakdown = f.by_rate_breakdown || {};
+  var bkeys = Object.keys(breakdown);
+  var breakdownRows = bkeys.map(function (k) {
+    var bkt = breakdown[k] || {};
+    var label = k === "__none__" ? "no rate matched"
+              : k === "__exempt__" ? "exempt"
+              : k === "__unknown__" ? "unknown rate"
+              : _fmtBps(k);
+    return "<tr>" +
+      "<td>" + _htmlEscape(label) + (k === "__none__" || k === "__exempt__" || k === "__unknown__" ? "" : " <span class=\"meta\">(" + _htmlEscape(String(k)) + " bps)</span>") + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(String(bkt.order_count == null ? 0 : bkt.order_count)) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(_filingMoney(bkt.taxable_minor)) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(_filingMoney(bkt.tax_minor)) + "</td>" +
+      "</tr>";
+  }).join("");
+  var breakdownBlock = bkeys.length
+    ? "<section><h2>By rate</h2><div class=\"panel\"><table><thead><tr><th scope=\"col\">Rate</th><th scope=\"col\" class=\"num\">Orders</th><th scope=\"col\" class=\"num\">Taxable</th><th scope=\"col\" class=\"num\">Tax</th></tr></thead><tbody>" + breakdownRows + "</tbody></table></div></section>"
+    : "";
+
+  // Audit trail — submission + payment + amendment columns once recorded.
+  var trail = "";
+  if (f.submission_ref || f.payment_ref || f.amended_reason) {
+    var trailRows = "";
+    if (f.submission_ref) {
+      trailRows += "<tr><td>Submitted</td><td>" + _htmlEscape(f.submission_ref) +
+        (f.submitted_by ? " <span class=\"meta\">by " + _htmlEscape(f.submitted_by) + "</span>" : "") +
+        (f.submitted_at != null ? " <span class=\"meta\">" + _htmlEscape(_fmtDate(f.submitted_at)) + "</span>" : "") + "</td></tr>";
+    }
+    if (f.payment_ref || f.payment_minor != null) {
+      trailRows += "<tr><td>Paid</td><td>" + _htmlEscape(_filingMoney(f.payment_minor)) +
+        (f.payment_ref ? " <span class=\"meta\">ref " + _htmlEscape(f.payment_ref) + "</span>" : "") +
+        (f.paid_at != null ? " <span class=\"meta\">" + _htmlEscape(_fmtDate(f.paid_at)) + "</span>" : "") + "</td></tr>";
+    }
+    if (f.amended_reason) {
+      trailRows += "<tr><td>Amended</td><td>" + _htmlEscape(f.amended_reason) +
+        (f.amended_at != null ? " <span class=\"meta\">" + _htmlEscape(_fmtDate(f.amended_at)) + "</span>" : "") + "</td></tr>";
+    }
+    trail = "<section><h2>Audit trail</h2><div class=\"panel\"><table><tbody>" + trailRows + "</tbody></table></div></section>";
+  }
+
+  // Lifecycle actions — gated on the FSM. draft → compute; computed →
+  // submit or amend; submitted → pay or amend; paid → amend.
+  var actions = "";
+  if (f.status === "draft" || f.status === "computed") {
+    actions +=
+      "<form method=\"post\" action=\"/admin/tax-filings/" + enc + "/compute\" class=\"form-inline\">" +
+        "<button class=\"btn\" type=\"submit\">" + (f.status === "computed" ? "Recompute snapshot" : "Compute snapshot") + "</button>" +
+      "</form>";
+  }
+  if (f.status === "computed") {
+    actions +=
+      "<form method=\"post\" action=\"/admin/tax-filings/" + enc + "/submit\" class=\"stack\">" +
+        _setupField("Submission reference", "submission_ref", "", "text", "The authority's confirmation number (e.g. DR-123-456).", " maxlength=\"200\" required") +
+        _setupField("Submitted by", "submitted_by", "", "text", "Who filed it.", " maxlength=\"200\" required") +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Record submission</button></div>" +
+      "</form>";
+  }
+  if (f.status === "submitted") {
+    actions +=
+      "<form method=\"post\" action=\"/admin/tax-filings/" + enc + "/pay\" class=\"stack\">" +
+        _setupField("Payment (minor units)", "payment_minor", "", "number", "Remitted amount in minor units — may be a partial / installment payment.", " min=\"0\" required") +
+        _setupField("Payment reference", "payment_ref", "", "text", "The authority's payment confirmation.", " maxlength=\"200\" required") +
+        "<div class=\"actions-row\"><button class=\"btn\" type=\"submit\">Record payment</button></div>" +
+      "</form>";
+  }
+  if (f.status === "computed" || f.status === "submitted" || f.status === "paid") {
+    actions +=
+      "<form method=\"post\" action=\"/admin/tax-filings/" + enc + "/amend\" class=\"stack\">" +
+        _setupField("Amendment reason", "reason", "", "text", "Why this filing is being corrected. The snapshot stays for the audit trail.", " maxlength=\"1000\" required") +
+        "<div class=\"actions-row\"><button class=\"btn btn--danger\" type=\"submit\">Mark amended</button></div>" +
+      "</form>";
+  }
+  var actionsBlock = actions
+    ? "<section><h2>Actions</h2><div class=\"panel\">" + actions + "</div></section>"
+    : "<section><h2>Actions</h2><p class=\"meta\">This filing is in a terminal state; re-open the period after amending to file again.</p></section>";
+
+  var back = "<p class=\"mt\"><a class=\"btn btn--ghost\" href=\"/admin/tax-filings\">Back to filings</a></p>";
+  return _renderAdminShell(opts.shop_name, "Filing", meta + stats + breakdownBlock + trail + actionsBlock + back, "tax-filings", opts.nav_available);
+}
+
+// Per-jurisdiction remittance report — the totals across every filing whose
+// period intersects the window. Read-only.
+function renderAdminTaxFilingReport(opts) {
+  opts = opts || {};
+  var report = opts.report;
+  var notice = opts.notice ? "<div class=\"banner banner--warn\">" + _htmlEscape(opts.notice) + "</div>" : "";
+  if (!report) {
+    return _renderAdminShell(opts.shop_name, "Remittance report",
+      "<section><h2>Remittance report</h2>" + notice +
+      "<p class=\"mt\"><a class=\"btn btn--ghost\" href=\"/admin/tax-filings\">Back to filings</a></p></section>",
+      "tax-filings", opts.nav_available);
+  }
+  var stats =
+    "<div class=\"stat-grid\">" +
+      _statCard("Filings", String(report.filing_count)) +
+      _statCard("Gross revenue", _filingMoney(report.total_gross_revenue_minor)) +
+      _statCard("Taxable revenue", _filingMoney(report.total_taxable_revenue_minor)) +
+      _statCard("Exempt revenue", _filingMoney(report.total_exempt_revenue_minor)) +
+      _statCard("Tax collected", _filingMoney(report.total_tax_collected_minor)) +
+      _statCard("Tax owed", _filingMoney(report.total_tax_owed_minor), true) +
+      _statCard("Tax paid", _filingMoney(report.total_tax_paid_minor)) +
+    "</div>";
+  var rows = (report.filings || []).map(function (f) {
+    return "<tr>" +
+      "<td><a class=\"order-id\" href=\"/admin/tax-filings/" + _htmlEscape(f.id) + "\">" + _htmlEscape(f.kind) + "</a></td>" +
+      "<td>" + _htmlEscape(_fmtDate(f.period_start)) + " → " + _htmlEscape(_fmtDate(f.period_end)) + "</td>" +
+      "<td><span class=\"status-pill " + _htmlEscape(f.status) + "\">" + _htmlEscape(f.status) + "</span></td>" +
+      "<td class=\"num\">" + _htmlEscape(_filingMoney(f.tax_collected_minor)) + "</td>" +
+      "<td class=\"num\">" + _htmlEscape(_filingMoney(f.tax_owed_minor)) + "</td>" +
+      "</tr>";
+  }).join("");
+  var table = (report.filings || []).length
+    ? "<div class=\"panel\"><table><thead><tr><th scope=\"col\">Period</th><th scope=\"col\">Window</th><th scope=\"col\">Status</th><th scope=\"col\" class=\"num\">Collected</th><th scope=\"col\" class=\"num\">Owed</th></tr></thead><tbody>" + rows + "</tbody></table></div>"
+    : "<p class=\"empty\">No filings intersect this window.</p>";
+
+  var body =
+    "<section><h2>Remittance report · " + _htmlEscape(report.jurisdiction) + "</h2>" + notice +
+      "<p class=\"meta\">Window: " + _htmlEscape(_fmtDate(report.from)) + " → " + _htmlEscape(_fmtDate(report.to)) + "</p>" +
+      stats + table +
+      "<p class=\"mt\"><a class=\"btn btn--ghost\" href=\"/admin/tax-filings\">Back to filings</a></p>" +
+    "</section>";
+  return _renderAdminShell(opts.shop_name, "Remittance report", body, "tax-filings", opts.nav_available);
+}
+
 function renderAdminShipping(opts) {
   opts = opts || {};
   var rows = opts.zones || [];

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.3.3",
+  "version": "0.3.5",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-1SIn6oAf1DjECbRfKENZasdKHJiywGdXR58wn0hsFGcdVHzUmvfgMkEz5ANIAZJ3",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Open-source framework built on blamejs. Vendored stack, zero npm runtime deps, PQC-first crypto, security-on by default.",
   "main": "lib/index.js",
   "scripts": {