@blamejs/blamejs-shop 0.0.129 → 0.1.1

package/CHANGELOG.md

@@ -6,6 +6,12 @@ Pre-1.0 the surface is intentionally evolving — every release may
 change something operators depend on. Read each entry before
 upgrading across more than a few patches at a time.
 
+## v0.1.x
+
+- v0.1.1 (2026-05-25) — **Admin setup wizard + a browser-accessible admin console.** The admin is now reachable from a browser, not just the bearer-token JSON API. Sign in once at /admin by pasting the ADMIN_API_KEY and a sealed, /admin-scoped session cookie carries you through the guided setup wizard (shop name, contact email, default currency, support URL — saved to shop config) and the analytics dashboard. The shop name set in the wizard drives the storefront header, page titles, and the admin header. **Added:** *Browser admin sign-in* — `/admin` renders a sign-in form; pasting the ADMIN_API_KEY sets a sealed `shop_admin` session cookie (SameSite=Strict, scoped to /admin) so the rendered admin pages are reachable from a browser. The JSON API stays bearer-only; the dashboard accepts either the cookie or the bearer token. · *Setup wizard* — `/admin/setup` is a guided form for the shop's core identity — name, contact email, default currency, support URL — validated (ISO-4217 currency, RFC-shaped email, http(s) support URL) and saved to shop config. The landing nags until setup is complete; the shop name then drives the storefront and admin headers.
+
+- v0.1.0 (2026-05-25) — **Responsive cart + storefront cookie handling moved onto the framework primitive.** A storefront polish pass. The cart, order-confirmation, and account-history tables now reflow into stacked, labelled cards on phones and fit their column on wider screens — no more inner horizontal scroll. The quantity field reads clearly and accepts up to 99,999. The line actions (Update / Save for later / Remove) are compact with a clear hierarchy. Under the hood, all storefront cookie handling now composes the framework's cookie primitive (RFC 6265 parse/serialize plus vault-sealed read/write) instead of hand-built headers, and a malformed session cookie can no longer turn the cart — or any page that shows the cart count — into a 500. **Changed:** *Quantity field is readable and accepts up to 99,999* — The cart quantity input is wide enough to read a five-digit quantity, and the per-line maximum is raised to 99,999 (enforced on the server). · *Compact, clearly-ranked line actions* — Update is a small accent button, Save for later a quiet secondary, Remove a danger-tinted secondary — so the primary checkout call stays dominant. · *Cookie handling composes the framework primitive* — Session, authentication, WebAuthn-challenge, and payment cookies are all parsed and written through the framework cookie primitive (sealed read/write for the authenticated-session cookie), replacing hand-built Set-Cookie strings and manual header parsing. Cookie lifetimes are expressed through the framework's duration constants. **Fixed:** *Cart tables no longer scroll sideways* — The cart, order-confirmation, and account order-history tables reflow into one labelled card per row below 48rem and are sized to fit their column on wider layouts, so content is never trapped behind an inner horizontal scrollbar. · *Malformed session cookie no longer 500s the storefront* — A `shop_sid` cookie carrying a value that isn't a well-formed session id now reads as "no session" instead of reaching the cart lookup (which rejected it and surfaced a 500 on every page that renders the cart count). · *Account dashboard controls wrap on narrow screens* — The row of account actions (Wishlist / Saved for later / Recently viewed / Addresses / Returns / Sign out) now wraps instead of overflowing the viewport on a phone.
+
 ## v0.0.x
 
 - v0.0.129 (2026-05-25) — **Recently viewed — a signed-in customer's browse history at /account/recently-viewed.** Signed-in customers now have a browse history. Opening a product page records the view against the customer's account, and `/account/recently-viewed` lists those products newest-first as a grid, with a one-tap Clear history control. Recording is best-effort and never blocks the product page; archived products drop out of the grid; the page is login-gated like the rest of the account area. **Added:** *Recently viewed account page* — `GET /account/recently-viewed` renders the customer's most-recently-opened products newest-first, reusing the standard product card (image, title, price, link to the PDP). A `POST /account/recently-viewed/clear` control wipes the history. Linked from the account dashboard. · *Server-side view recording* — A signed-in customer's product-page visit records the view against their account — no client script. Recording is drop-silent: a write failure never breaks the product page. The history de-dupes per product and is capped per customer.

package/README.md

@@ -72,7 +72,7 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 | **`lib/collections.js`** | Curated + smart product groupings. `GET /collections` lists the shop's active collections; `GET /collections/:slug` renders the grid — manual collections list hand-picked members, smart collections evaluate stored rules against the active catalog and apply the collection's sort strategy. Each product resolves fresh, so archived products drop out. Public, no sign-in; a bad or unknown slug is a 404 (never a 500). Linked from the footer on every page. |
 | **`lib/subscriptions.js`** | Stripe-backed recurring billing — `subscription_plans` (interval / amount / trial) + `subscriptions` (mirrors Stripe's object byte-for-byte). `subscriptions.create` POSTs to Stripe via the payment dep, then persists the returned object locally. `handleStripeEvent` replays `customer.subscription.*` events into the local row so the shop has an authoritative view without round-tripping. |
 | **`lib/newsletter.js`** | Operator-collected email broadcast list — `signup({ email, source })` composes `b.guardEmail` for shape validation, `b.crypto.namespaceHash` for the dedup key, and `INSERT OR IGNORE` for idempotency. Storefront POST `/newsletter` route renders a designed thank-you card with separate copy for the `new` vs `dedup` branches. |
-| **`lib/admin.js`** | Bearer-token-gated CRUD over catalog + orders + refunds + bulk CSV import + subscription plans + review moderation + return moderation. Token compared via `b.crypto.timingSafeEqual`. Errors as RFC 9457 problem documents via `b.problemDetails`. Audit emission on every mutation. |
+| **`lib/admin.js`** | Bearer-token-gated CRUD over catalog + orders + refunds + bulk CSV import + subscription plans + review moderation + return moderation. Token compared via `b.crypto.timingSafeEqual`. Errors as RFC 9457 problem documents via `b.problemDetails`. Audit emission on every mutation. Also serves a **browser admin console**: sign in at `/admin` by pasting the API key (sealed `shop_admin` session cookie, SameSite=Strict, /admin-scoped), a guided **setup wizard** at `/admin/setup` that writes shop identity to config, and the analytics dashboard — all reachable by the cookie or the bearer token. |
 | **`lib/catalog-import.js`** | Bulk CSV import — `POST /admin/catalog/import` accepts a `text/csv` body, parses via `b.csv`, content-safety-filters every cell through `b.guardCsv` (formula-injection / bidi / control / dangerous-function denylist), validates exact header order, de-dupes rows by `product_slug`, returns per-row errors without aborting. Default 1 MiB / 10000 rows caps. |
 | **`lib/theme.js`** | File-backed templates with fallback chain. Operators register a named theme under `<themesDir>/<name>/*.html` and the storefront dispatches every renderer through it. `assetUrl(path)` resolves to `/assets/themes/<name>/<path>`. The shipped `default` theme is the fallback. |
 

package/lib/admin.js

@@ -84,10 +84,9 @@ function _parseLimit(str, label, max, fallback) {
 
 // ---- HTML escape + dashboard layout ------------------------------------
 
-var HTML_ESCAPE_MAP = { "&": "&amp;", "<": "&lt;", ">": "&gt;", "\"": "&quot;", "'": "&#39;" };
 function _htmlEscape(s) {
   if (s == null) return "";
-  return String(s).replace(/[&<>"']/g, function (c) { return HTML_ESCAPE_MAP[c]; });
+  return _b().template.escapeHtml(String(s));
 }
 
 // ---- bearer auth --------------------------------------------------------
@@ -106,6 +105,53 @@ function _authOk(token, expected) {
   return _b().crypto.timingSafeEqual(token, expected);
 }
 
+// ---- admin browser session (sealed cookie) ------------------------------
+//
+// The JSON API (R/W wrappers) is bearer-token only — that's the contract
+// for machine clients. The server-rendered admin pages (landing, setup
+// wizard, dashboard) additionally accept a sealed `shop_admin` cookie so
+// an operator can sign in from a browser by pasting the same token once.
+// The cookie composes the framework cookie primitive (vault-sealed
+// read/write) — scoped to /admin, SameSite=Strict, HttpOnly + Secure.
+var ADMIN_COOKIE_NAME = "shop_admin";
+
+var _adminJarMemo = null;
+function _adminJar() {
+  if (!_adminJarMemo) {
+    _adminJarMemo = _b().cookies.create({
+      vault:    _b().vault,
+      defaults: { httpOnly: true, secure: true, sameSite: "Strict", path: "/admin" },
+    });
+  }
+  return _adminJarMemo;
+}
+
+function _setAdminCookie(res) {
+  _adminJar().writeSealed(res, ADMIN_COOKIE_NAME, JSON.stringify({
+    admin: true,
+    exp:   Date.now() + _b().constants.TIME.hours(12),
+  }), { expires: new Date(Date.now() + _b().constants.TIME.hours(12)) });
+}
+function _clearAdminCookie(res) {
+  _adminJar().clear(res, ADMIN_COOKIE_NAME);
+}
+function _adminCookieValid(req) {
+  var raw = _adminJar().readSealed(req, ADMIN_COOKIE_NAME);
+  if (raw === null) return false;
+  var env;
+  try { env = JSON.parse(raw); } catch (_e) { return false; }
+  return !!(env && env.admin === true && env.exp && env.exp > Date.now());
+}
+
+// HTML-page auth: a valid admin cookie OR the bearer token (so existing
+// tooling that sends the header still reaches the dashboard). Never
+// throws — a missing vault surfaces as "not authed" so the caller can
+// render the login form rather than 500.
+function _htmlAuthed(req, expectedToken) {
+  if (_authOk(_readBearer(req), expectedToken)) return true;
+  try { return _adminCookieValid(req); } catch (_e) { return false; }
+}
+
 function _problem(res, status, code, detail) {
   return _b().problemDetails.send(res, {
     type:   "/problems/" + code,
@@ -115,6 +161,21 @@ function _problem(res, status, code, detail) {
   });
 }
 
+function _sendHtml(res, status, html) {
+  res.status(status);
+  if (res.setHeader) {
+    res.setHeader("content-type", "text/html; charset=utf-8");
+    res.setHeader("x-robots-tag", "noindex, nofollow");
+  }
+  if (res.end) res.end(html); else res.send(html);
+}
+
+function _redirect(res, location) {
+  res.status(303);
+  if (res.setHeader) res.setHeader("location", location);
+  if (res.end) res.end(); else res.send("");
+}
+
 function _wrap(handler, opts) {
   // Every admin handler routes through this wrapper: bearer-token
   // gate, error-to-problem-details translation, audit write on the
@@ -814,24 +875,26 @@ function mount(router, deps) {
       _json(res, 200, { rows: rows });
     }));
 
-    router.get("/admin/dashboard", R(async function (req, res) {
+    // HTML page — accepts the admin browser cookie OR the bearer token,
+    // so it's reachable both from a signed-in browser and from tooling.
+    router.get("/admin/dashboard", async function (req, res) {
+      if (!_htmlAuthed(req, expectedToken)) {
+        return _sendHtml(res, 200, renderAdminLogin({ shop_name: deps.shop_name }));
+      }
       var url     = req.url ? new URL(req.url, "http://localhost") : null;
       var w       = _parseWindow(url);
       var summary = await analytics.summary(w);
       var byDay   = await analytics.revenueByDay(w);
       var top     = await analytics.topSKUs(Object.assign({}, w, { limit: 10 }));
       var recent  = await analytics.recentOrders({ limit: 20 });
-      var html    = renderDashboard({
+      _sendHtml(res, 200, renderDashboard({
         summary:    summary,
         by_day:     byDay,
         top_skus:   top,
         recent:     recent,
         shop_name:  (deps.shop_name || "blamejs.shop"),
-      });
-      res.status(200);
-      if (res.setHeader) res.setHeader("content-type", "text/html; charset=utf-8");
-      if (res.end) res.end(html); else res.send(html);
-    }));
+      }));
+    });
   }
 
   // ---- subscriptions --------------------------------------------------
@@ -901,6 +964,112 @@ function mount(router, deps) {
     }));
   }
 
+  // ---- admin web pages (browser session + setup wizard) ---------------
+  //
+  // The operator signs in by pasting the ADMIN_API_KEY once; that sets a
+  // sealed, SameSite=Strict, /admin-scoped cookie so the rendered pages
+  // (landing, dashboard, setup) are reachable from a browser. The JSON
+  // API stays bearer-only. POST routes follow the storefront's
+  // form-POST pattern (SameSite cookie + the app-level origin /
+  // fetch-metadata guards), no separate CSRF token field.
+
+  async function _setupComplete() {
+    if (!config) return false;
+    try { return (await config.get("setup.completed", false)) === true; }
+    catch (_e) { return false; }
+  }
+
+  router.get("/admin", async function (req, res) {
+    if (!_htmlAuthed(req, expectedToken)) {
+      return _sendHtml(res, 200, renderAdminLogin({ shop_name: deps.shop_name }));
+    }
+    _sendHtml(res, 200, renderAdminLanding({
+      shop_name:      deps.shop_name,
+      setup_complete: await _setupComplete(),
+    }));
+  });
+
+  router.post("/admin/login", async function (req, res) {
+    var body  = req.body || {};
+    var token = typeof body.token === "string" ? body.token : "";
+    if (!_authOk(token, expectedToken)) {
+      return _sendHtml(res, 401, renderAdminLogin({ shop_name: deps.shop_name, error: true }));
+    }
+    try { _setAdminCookie(res); }
+    catch (e) {
+      // Sealed cookies need an initialized vault — surface 503 rather
+      // than 500 so the operator knows to configure VAULT_PASSPHRASE.
+      if (e && e.code === "vault/not-initialized") {
+        return _sendHtml(res, 503, renderAdminLogin({ shop_name: deps.shop_name }));
+      }
+      throw e;
+    }
+    _redirect(res, (await _setupComplete()) ? "/admin" : "/admin/setup");
+  });
+
+  router.post("/admin/logout", async function (_req, res) {
+    _clearAdminCookie(res);
+    _redirect(res, "/admin");
+  });
+
+  if (config) {
+    router.get("/admin/setup", async function (req, res) {
+      if (!_htmlAuthed(req, expectedToken)) return _redirect(res, "/admin");
+      var url   = req.url ? new URL(req.url, "http://localhost") : null;
+      var saved = !!(url && url.searchParams.get("saved"));
+      var values = {};
+      try {
+        values.shop_name     = await config.get("shop.name", deps.shop_name || "");
+        values.contact_email = await config.get("shop.contact_email", "");
+        values.currency      = await config.get("shop.currency", "");
+        values.support_url   = await config.get("shop.support_url", "");
+      } catch (_e) { /* unconfigured — render an empty form */ }
+      _sendHtml(res, 200, renderAdminSetup({ shop_name: deps.shop_name, values: values, saved: saved }));
+    });
+
+    router.post("/admin/setup", async function (req, res) {
+      if (!_htmlAuthed(req, expectedToken)) return _redirect(res, "/admin");
+      var body = req.body || {};
+      var values = {
+        shop_name:     (typeof body.shop_name === "string"     ? body.shop_name     : "").trim(),
+        contact_email: (typeof body.contact_email === "string" ? body.contact_email : "").trim(),
+        currency:      (typeof body.currency === "string"      ? body.currency      : "").trim().toUpperCase(),
+        support_url:   (typeof body.support_url === "string"   ? body.support_url   : "").trim(),
+      };
+      // Defensive request-shape reader: bad input re-renders the form
+      // with a notice (400), never a 500.
+      var notice = null;
+      if (!values.shop_name) notice = "Shop name is required.";
+      else if (values.shop_name.length > 80) notice = "Shop name is too long (max 80 characters).";
+      else if (values.currency && !/^[A-Z]{3}$/.test(values.currency)) notice = "Currency must be a 3-letter ISO 4217 code (e.g. USD).";
+      else if (values.contact_email) {
+        var emailReport = _b().guardEmail.validate(values.contact_email, { profile: "strict" });
+        if (!emailReport || emailReport.ok === false) notice = "That contact email doesn't look valid.";
+      }
+      if (!notice && values.support_url) {
+        var u = _b().safeUrl.parse(values.support_url);
+        if (!u || (u.protocol !== "https:" && u.protocol !== "http:")) notice = "Support URL must be a valid http(s) URL.";
+      }
+      if (notice) {
+        return _sendHtml(res, 400, renderAdminSetup({ shop_name: deps.shop_name, values: values, notice: notice }));
+      }
+      try {
+        await config.put("shop.name", values.shop_name);
+        if (values.contact_email) await config.put("shop.contact_email", values.contact_email);
+        if (values.currency)      await config.put("shop.currency", values.currency);
+        if (values.support_url)   await config.put("shop.support_url", values.support_url);
+        await config.put("setup.completed", true);
+      } catch (e) {
+        return _sendHtml(res, 500, renderAdminSetup({
+          shop_name: deps.shop_name, values: values,
+          notice: "Couldn't save — " + ((e && e.message) || "please try again."),
+        }));
+      }
+      _b().audit.safeEmit({ action: AUDIT_NAMESPACE + ".setup.save", outcome: "success", metadata: {} });
+      _redirect(res, "/admin/setup?saved=1");
+    });
+  }
+
   // ---- ping (auth check) ----------------------------------------------
 
   router.get("/admin/ping", R(async function (_req, res) {
@@ -963,6 +1132,25 @@ var DASHBOARD_LAYOUT =
   "    .empty { color:var(--mute); font-style:italic; padding:1rem 0; text-align:center; }\n" +
   "    .meta { color:var(--mute); font-size:.85rem; margin-bottom:1rem; }\n" +
   "    .order-id { font-family:ui-monospace, SFMono-Regular, Menlo, monospace; font-size:.78rem; color:var(--ink-2); }\n" +
+  "    .form-field { display:block; margin-bottom:1.1rem; }\n" +
+  "    .form-field span { display:block; font-size:.78rem; text-transform:uppercase; letter-spacing:.05em; color:var(--mute); font-weight:600; margin-bottom:.35rem; }\n" +
+  "    .form-field input { width:100%; max-width:28rem; padding:.6rem .75rem; border:1px solid var(--hair); border-radius:6px; font:inherit; }\n" +
+  "    .form-field input:focus { outline:2px solid var(--accent); outline-offset:1px; border-color:var(--accent); }\n" +
+  "    .form-field small { display:block; color:var(--mute); font-size:.78rem; margin-top:.3rem; }\n" +
+  "    .btn { display:inline-flex; align-items:center; gap:.4rem; background:var(--accent); color:var(--paper); border:1px solid var(--accent); padding:.6rem 1.1rem; border-radius:6px; font-family:'Montserrat',sans-serif; font-weight:700; font-size:.82rem; letter-spacing:.04em; text-transform:uppercase; text-decoration:none; cursor:pointer; }\n" +
+  "    .btn:hover { background:var(--accent-d); border-color:var(--accent-d); }\n" +
+  "    .btn--ghost { background:transparent; color:var(--ink); border-color:var(--ink); }\n" +
+  "    .btn--ghost:hover { background:var(--ink); color:var(--paper); }\n" +
+  "    .nav-cards { display:grid; grid-template-columns:repeat(auto-fit,minmax(14rem,1fr)); gap:1rem; }\n" +
+  "    .nav-card { display:block; background:var(--paper); border:1px solid var(--hair); border-radius:8px; padding:1.4rem; text-decoration:none; color:var(--ink); }\n" +
+  "    .nav-card:hover { border-color:var(--accent); box-shadow:0 8px 20px -12px rgba(0,0,0,.25); }\n" +
+  "    .nav-card h3 { margin:0 0 .35rem; font-size:1.05rem; }\n" +
+  "    .nav-card p { margin:0; color:var(--mute); font-size:.88rem; }\n" +
+  "    .banner { padding:.9rem 1.1rem; border-radius:8px; margin-bottom:1.5rem; font-size:.92rem; }\n" +
+  "    .banner--warn { background:#fff8e1; border:1px solid #f1e1a8; color:#7a5d0f; }\n" +
+  "    .banner--ok { background:#e9f5ec; border:1px solid #bfe1c9; color:#1f6b3a; }\n" +
+  "    .banner--err { background:#fff1eb; border:1px solid #f6c5af; color:var(--accent-d); }\n" +
+  "    .actions-row { display:flex; gap:.75rem; flex-wrap:wrap; align-items:center; margin-top:1.5rem; }\n" +
   "  </style>\n" +
   "</head>\n" +
   "<body>\n" +
@@ -1113,8 +1301,86 @@ function _statCard(label, value, accent) {
          "<div class=\"value" + (accent ? " accent" : "") + "\">" + _htmlEscape(value) + "</div></div>";
 }
 
+// ---- admin web pages (login / landing / setup wizard) -------------------
+
+function _renderAdminShell(shopName, subtitle, bodyHtml) {
+  return _renderTemplate(DASHBOARD_LAYOUT, {
+    shop_name:    shopName || "blamejs.shop",
+    window_label: subtitle || "",
+    body:         "RAW_BODY",
+  }).replace("RAW_BODY", bodyHtml);
+}
+
+function renderAdminLogin(opts) {
+  opts = opts || {};
+  var err = opts.error
+    ? "<div class=\"banner banner--err\">That key didn't match. Check the ADMIN_API_KEY this deployment was started with.</div>"
+    : "";
+  var body =
+    "<section style=\"max-width:30rem;\">" +
+      "<h2>Sign in</h2>" + err +
+      "<form method=\"post\" action=\"/admin/login\">" +
+        "<label class=\"form-field\"><span>Admin API key</span>" +
+          "<input type=\"password\" name=\"token\" autocomplete=\"off\" autofocus required>" +
+          "<small>Paste the ADMIN_API_KEY this deployment was started with.</small>" +
+        "</label>" +
+        "<button type=\"submit\" class=\"btn\">Sign in</button>" +
+      "</form>" +
+    "</section>";
+  return _renderAdminShell(opts.shop_name, "Sign in", body);
+}
+
+function renderAdminLanding(opts) {
+  opts = opts || {};
+  var setupBanner = opts.setup_complete
+    ? ""
+    : "<div class=\"banner banner--warn\">Your shop isn't set up yet. <a href=\"/admin/setup\">Finish setup &rarr;</a></div>";
+  var body =
+    "<section>" + setupBanner +
+      "<h2>Admin</h2>" +
+      "<div class=\"nav-cards\">" +
+        "<a class=\"nav-card\" href=\"/admin/setup\"><h3>Setup wizard</h3><p>Shop identity, currency, and contact details.</p></a>" +
+        "<a class=\"nav-card\" href=\"/admin/dashboard\"><h3>Dashboard</h3><p>Sales, revenue, and recent orders at a glance.</p></a>" +
+      "</div>" +
+      "<div class=\"actions-row\"><form method=\"post\" action=\"/admin/logout\"><button type=\"submit\" class=\"btn btn--ghost\">Sign out</button></form></div>" +
+    "</section>";
+  return _renderAdminShell(opts.shop_name, "", body);
+}
+
+function _setupField(label, name, value, type, hint, extra) {
+  return "<label class=\"form-field\"><span>" + _htmlEscape(label) + "</span>" +
+    "<input type=\"" + (type || "text") + "\" name=\"" + _htmlEscape(name) + "\" value=\"" + _htmlEscape(value || "") + "\"" + (extra || "") + ">" +
+    (hint ? "<small>" + _htmlEscape(hint) + "</small>" : "") +
+    "</label>";
+}
+
+function renderAdminSetup(opts) {
+  opts = opts || {};
+  var v = opts.values || {};
+  var saved  = opts.saved  ? "<div class=\"banner banner--ok\">Saved. Your shop details are live.</div>" : "";
+  var notice = opts.notice ? "<div class=\"banner banner--err\">" + _htmlEscape(opts.notice) + "</div>" : "";
+  var body =
+    "<section style=\"max-width:34rem;\">" +
+      "<h2>Shop setup</h2>" +
+      "<p class=\"meta\">Set the basics customers see across the storefront. You can change these any time.</p>" +
+      saved + notice +
+      "<form method=\"post\" action=\"/admin/setup\">" +
+        _setupField("Shop name", "shop_name", v.shop_name, "text", "Shown in the header, page titles, and emails.", " maxlength=\"80\" required") +
+        _setupField("Contact email", "contact_email", v.contact_email, "email", "Where customer replies and operational mail land.", " maxlength=\"160\"") +
+        _setupField("Default currency", "currency", v.currency, "text", "3-letter ISO 4217 code (e.g. USD, EUR, GBP).", " maxlength=\"3\" style=\"text-transform:uppercase;max-width:8rem;\"") +
+        _setupField("Support URL", "support_url", v.support_url, "url", "Linked from the storefront footer (help centre, contact page).", " maxlength=\"300\"") +
+        "<div class=\"actions-row\"><button type=\"submit\" class=\"btn\">Save shop details</button>" +
+          "<a class=\"btn btn--ghost\" href=\"/admin\">Back</a></div>" +
+      "</form>" +
+    "</section>";
+  return _renderAdminShell(opts.shop_name, "Setup", body);
+}
+
 module.exports = {
   mount:           mount,
   AUDIT_NAMESPACE: AUDIT_NAMESPACE,
   renderDashboard: renderDashboard,
+  renderAdminLogin:   renderAdminLogin,
+  renderAdminLanding: renderAdminLanding,
+  renderAdminSetup:   renderAdminSetup,
 };

package/lib/affiliates.js

@@ -135,6 +135,7 @@ function _b() {
   if (!bShop) bShop = require("./index");
   return bShop.framework;
 }
+var C = _b().constants;
 
 // ---- validators ---------------------------------------------------------
 
@@ -677,10 +678,10 @@ function create(opts) {
         throw paused;
       }
 
-      // Dedupe within one calendar minute (60000 ms). A refresh in
+      // Dedupe within one calendar minute. A refresh in
       // the same minute collapses to a single visit; later traffic
       // gets its own row so funnel-stats stay coherent.
-      var dedupeWindow = 60000;
+      var dedupeWindow = C.TIME.minutes(1);
       var existing = await query(
         "SELECT id FROM affiliate_visits " +
         "WHERE visitor_session_id_hash = ?1 AND code = ?2 AND occurred_at >= ?3 " +
@@ -741,7 +742,7 @@ function create(opts) {
       );
       for (var i = 0; i < r.rows.length; i += 1) {
         var row = r.rows[i];
-        var windowMs = Number(row.attribution_window_days) * 24 * 3600 * 1000;
+        var windowMs = Number(row.attribution_window_days) * C.TIME.days(1);
         if (now - Number(row.occurred_at) <= windowMs) {
           return {
             visit_id:     row.visit_id,

package/lib/analytics.js

@@ -92,9 +92,10 @@ function _b() {
   if (!bShop) bShop = require("./index");
   return bShop.framework;
 }
+var C = _b().constants;
 
-var ONE_YEAR_MS = 365 * 24 * 60 * 60 * 1000;
-var DEFAULT_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
+var ONE_YEAR_MS = C.TIME.days(365);
+var DEFAULT_WINDOW_MS = C.TIME.days(30);
 
 // ---- validators ---------------------------------------------------------
 

package/lib/api-keys.js

@@ -76,7 +76,7 @@ var TOKEN_BYTE_LEN          = 32;
 var TOKEN_PLAINTEXT_LEN     = 43;
 var TOKEN_PLAINTEXT_RE      = /^[A-Za-z0-9_-]{43}$/;
 
-var ROTATION_GRACE_MS       = 24 * 60 * 60 * 1000;
+var ROTATION_GRACE_MS       = _b().constants.TIME.days(1);
 
 var OWNER_TYPES             = ["operator", "app", "affiliate", "tenant"];
 var STATUSES                = ["active", "rotated", "revoked", "expired"];

package/lib/assembly-instructions.js

@@ -110,6 +110,7 @@ function _b() {
   if (!bShop) bShop = require("./index");
   return bShop.framework;
 }
+var C = _b().constants;
 
 // ---- constants ----------------------------------------------------------
 
@@ -126,7 +127,7 @@ var MAX_LIMIT         = 500;
 var DEFAULT_LIMIT     = 50;
 var MAX_DAYS          = 3650;
 var SESSION_NAMESPACE = "assembly-instructions-session";
-var DAY_MS            = 24 * 60 * 60 * 1000;
+var DAY_MS            = C.TIME.days(1);
 
 // ---- monotonic clock ----------------------------------------------------
 //

package/lib/auto-replenish.js

@@ -91,6 +91,7 @@ function _b() {
   if (!bShop) bShop = require("./index");
   return bShop.framework;
 }
+var C = _b().constants;
 
 // ---- constants ----------------------------------------------------------
 
@@ -110,9 +111,9 @@ var MAX_LIMIT           = 500;
 // again. Stored as constants so tests can read them when constructing
 // "tick just-after-last-run" scenarios.
 var SCHEDULE_INTERVAL_MS = Object.freeze({
-  hourly: 60 * 60 * 1000,
-  daily:  24 * 60 * 60 * 1000,
-  weekly: 7 * 24 * 60 * 60 * 1000,
+  hourly: C.TIME.hours(1),
+  daily:  C.TIME.days(1),
+  weekly: C.TIME.days(7),
 });
 
 // ---- monotonic clock ----------------------------------------------------

package/lib/backorder.js

@@ -82,13 +82,14 @@ function _b() {
   if (!bShop) bShop = require("./index");
   return bShop.framework;
 }
+var C = _b().constants;
 
 // ---- constants ----------------------------------------------------------
 
 var SKU_RE          = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 var MAX_MESSAGE_LEN = 280;
 var MAX_REASON_LEN  = 280;
-var WEEK_MS         = 7 * 24 * 60 * 60 * 1000;
+var WEEK_MS         = C.TIME.days(7);
 
 var BACKORDER_STATUSES = Object.freeze(["pending", "fulfilled", "cancelled"]);
 

package/lib/business-hours.js

@@ -69,6 +69,13 @@
  * @related   shop.deliveryEstimate
  */
 
+var bShop;
+function _b() {
+  if (!bShop) bShop = require("./index");
+  return bShop.framework;
+}
+var C = _b().constants;
+
 var MAX_SLUG_LEN     = 64;
 var SLUG_RE          = /^[a-z0-9][a-z0-9_-]{0,63}$/;
 
@@ -81,7 +88,7 @@ var YMD_RE           = /^\d{4}-\d{2}-\d{2}$/;
 var MAX_WEEKLY_HOURS = 64;       // 7 days x 8 split-shifts each is more than any real schedule needs
 var MAX_NAME_LEN     = 200;
 
-var DAY_MS           = 24 * 60 * 60 * 1000;
+var DAY_MS           = C.TIME.days(1);
 var SEARCH_DAYS      = 366 * 2;  // worst-case "find next open" walk — 2 calendar years of closures
 
 // ---- validators ---------------------------------------------------------

package/lib/carrier-accounts.js

@@ -99,7 +99,7 @@ var CARRIERS = Object.freeze([
 
 var STATUSES = Object.freeze(["active", "disabled", "rotating"]);
 
-var ROTATION_GRACE_MS = 24 * 60 * 60 * 1000;
+var ROTATION_GRACE_MS = _b().constants.TIME.days(1);
 
 var NS_ACCOUNT_NUMBER = "carrier-account-account-number";
 var NS_API_KEY        = "carrier-account-api-key";

package/lib/carrier-rates.js

@@ -70,7 +70,7 @@ var DEFAULT_RECENT_LIMIT  = 25;
 var MAX_RECENT_LIMIT      = 200;
 
 var MAX_DIMENSION_MM      = 5000;       // 5 m — generous, catches absurd input
-var MAX_WEIGHT_GRAMS      = 1000 * 1000; // 1 t — generous, catches absurd input
+var MAX_WEIGHT_GRAMS      = 1000 * 1000; // allow:raw-time-literal — grams, not a duration (1 t — generous, catches absurd input)
 
 // Lazy framework handle — matches the pattern every other shop
 // primitive uses; avoids the require cycle that would arise from

package/lib/cart-abandonment.js

@@ -53,6 +53,7 @@ function _b() {
   if (!bShop) bShop = require("./index");
   return bShop.framework;
 }
+var C = _b().constants;
 
 // ---- constants ----------------------------------------------------------
 
@@ -71,8 +72,8 @@ var SKIP_REASONS = Object.freeze([
   "opted-out",
 ]);
 
-var DEFAULT_IDLE_THRESHOLD_MS = 24 * 60 * 60 * 1000;          // 24h
-var DEFAULT_MAX_AGE_MS        = 30 * 24 * 60 * 60 * 1000;     // 30d
+var DEFAULT_IDLE_THRESHOLD_MS = C.TIME.days(1);              // 24h
+var DEFAULT_MAX_AGE_MS        = C.TIME.days(30);             // 30d
 var DEFAULT_MAX_CARTS         = 500;
 var MAX_MAX_CARTS             = 5000;
 

package/lib/cart-bulk-ops.js

@@ -64,6 +64,7 @@ function _b() {
   if (!bShop) bShop = require("./index");
   return bShop.framework;
 }
+var C = _b().constants;
 
 var SLUG_RE     = /^[a-z0-9](?:[a-z0-9-]{0,198}[a-z0-9])?$/;
 var SKU_RE      = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
@@ -530,7 +531,7 @@ function create(opts) {
         var groupKey = groupOrder[gi];
         var childId = _b().uuid.v7();
         var childSession = "sess_" + _b().uuid.v7().replace(/-/g, "").slice(0, 24);
-        var childExpires = ts + 24 * 60 * 60 * 1000;
+        var childExpires = ts + C.TIME.days(1);
         await query(
           "INSERT INTO carts (id, session_id, customer_id, currency, status, created_at, updated_at, expires_at) " +
           "VALUES (?1, ?2, ?3, ?4, 'active', ?5, ?5, ?6)",

package/lib/cart-recovery.js

@@ -30,9 +30,9 @@
  *       slug:  "default-recovery",
  *       title: "Default 3-step recovery",
  *       steps: [
- *         { step_index: 0, offset_ms:  1 * 3600 * 1000, kind: "reminder"    },
- *         { step_index: 1, offset_ms: 24 * 3600 * 1000, kind: "discount"    },
- *         { step_index: 2, offset_ms: 72 * 3600 * 1000, kind: "last_chance" },
+ *         { step_index: 0, offset_ms: C.TIME.hours(1),  kind: "reminder"    },
+ *         { step_index: 1, offset_ms: C.TIME.hours(24), kind: "discount"    },
+ *         { step_index: 2, offset_ms: C.TIME.hours(72), kind: "last_chance" },
  *       ],
  *     });
  *
@@ -115,6 +115,7 @@ function _b() {
   if (!bShop) bShop = require("./index");
   return bShop.framework;
 }
+var C = _b().constants;
 
 // ---- constants ----------------------------------------------------------
 
@@ -732,7 +733,7 @@ function create(opts) {
             "UPDATE cart_recovery_enrollments SET " +
             "next_step_at = ?1, updated_at = ?2 " +
             "WHERE id = ?3 AND status = 'enrolled'",
-            [now + 3600 * 1000, now, enr.id],
+            [now + C.TIME.hours(1), now, enr.id],
           );
         } else {
           // Clean send. Advance.

package/lib/cart.js

@@ -29,10 +29,14 @@ function _b() {
   if (!bShop) bShop = require("./index");
   return bShop.framework;
 }
+// Framework constants (C.TIME / C.BYTES duration + byte helpers). The
+// index entry point exposes `framework` before the require cascade, so
+// resolving this at module-eval is safe.
+var C = _b().constants;
 
 var CART_STATUSES   = Object.freeze(["active", "abandoned", "converted"]);
-var DEFAULT_TTL_MS  = 30 * 24 * 60 * 60 * 1000;   // 30 days
-var MAX_QTY         = 9999;
+var DEFAULT_TTL_MS  = C.TIME.days(30);
+var MAX_QTY         = 99999;
 var SESSION_ID_RE   = /^[A-Za-z0-9_-]{16,64}$/;   // shape-only; sealed-cookie origin
 var CURRENCY_RE     = /^[A-Z]{3}$/;
 

package/lib/catalog-drafts.js

@@ -104,7 +104,7 @@ var MAX_LIST_LIMIT   = 200;
 var MAX_TAG_LEN      = 64;
 var MAX_CHANGES_PER_DRAFT = 5000;
 
-var ROLLBACK_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+var ROLLBACK_WINDOW_MS = _b().constants.TIME.days(7);
 
 // Slug shape matches the project's recurring slug convention used
 // across coupon-stacking / refund-policy / customer-segments — alnum

package/lib/click-and-collect.js

@@ -97,6 +97,7 @@ function _b() {
   if (!bShop) bShop = require("./index");
   return bShop.framework;
 }
+var C = _b().constants;
 
 // ---- constants ----------------------------------------------------------
 
@@ -107,8 +108,8 @@ var MAX_NAME_LEN        = 200;
 var MAX_REASON_LEN      = 280;
 var MAX_SIGNATURE_LEN   = 8192;
 var MAX_LIST_LIMIT      = 200;
-var HOUR_MS             = 3600 * 1000;
-var NO_SHOW_ESCALATE_MS = 7 * 24 * 60 * 60 * 1000;
+var HOUR_MS             = C.TIME.hours(1);
+var NO_SHOW_ESCALATE_MS = C.TIME.days(7);
 var SIGNATURE_NAMESPACE = "click-and-collect-signature";
 
 var PICKUP_STATUSES = Object.freeze([