@stacklist-app/brandkit 1.2.3 → 1.2.4

package/README.md

@@ -73,10 +73,26 @@ export default {
 
 **Next.js / plain HTML**: run `brandkit build brand` and serve the resulting directory as a static route.
 
+### Serving from a base path
+
+brandkit emits page-relative paths, which resolve only when the guide is served from the root or a **trailing-slash** directory URL (`/brand/`). If you serve it at `/brand` with **no** trailing slash — e.g. a Next.js rewrite that maps `/brand` to the built `/brand/index.html` — every relative path resolves against `/` instead, so `styles.css`, `engine.js`, and `config.json` all 404 and the guide renders an empty shell.
+
+Set `basePath` in `config.json` to fix this:
+
+```json
+{
+  "basePath": "/brand",
+  "brand": { "name": "Acme" }
+}
+```
+
+On `brandkit build`, the generated `index.html` then points its stylesheet, engine, and `brand.json` link at `${basePath}/…`, and the engine fetches `${basePath}/config.json` — so the guide loads fully whether or not the serving URL has a trailing slash. The value is normalized (leading slash added, trailing slash stripped). Omitting `basePath` keeps the original page-relative behavior, so existing setups are unaffected.
+
 ## Config
 
 `config.json` is the single source of truth. Top-level keys:
 
+- `basePath` — absolute path the guide is served from (e.g. `/brand`). Omit (or leave empty) when serving at the root or from a trailing-slash directory URL — output stays page-relative and unchanged. See [Serving from a base path](#serving-from-a-base-path).
 - `brand` — name, tagline, description, version, date; optional `guideLabel` (renames the "Web Style Guide" header/footer label), `headerLogo` and `sidebarLogo` (logo image paths that replace the text wordmark in the header and left menu)
 - `fonts` — display + body with Google Fonts import; each font takes an optional `fallback` web stand-in for brands whose official typeface isn't web-available (the rendered font stack becomes `'family', 'fallback', sans-serif`, while labels keep the clean family name)
 - `theme` — CSS variable map (colors, gradients, font vars)

package/config.schema.json

@@ -37,6 +37,7 @@
     }
   },
   "properties": {
+    "basePath": { "type": "string", "description": "Absolute base path the guide is served from (e.g. \"/brand\"). Empty = served at root / relative. Set this when serving from a non-trailing-slash URL (e.g. a framework rewrite)." },
     "brand": {
       "type": "object",
       "required": ["name"],

package/dist/engine.js

@@ -6,7 +6,13 @@
   /* ================================================================
      0. Load config
      ================================================================ */
-  var res = await fetch('./config.json');
+  // Base path the guide is served from. The build injects
+  // window.__BRANDKIT_BASE__ when config.basePath is set (e.g. "/brand"), so a
+  // guide served from a non-trailing-slash URL still resolves its assets.
+  // Default '.' keeps the original page-relative behavior (dev + root serving).
+  var BASE = (typeof window !== 'undefined' && window.__BRANDKIT_BASE__)
+    ? (String(window.__BRANDKIT_BASE__).replace(/\/+$/, '') || '.') : '.';
+  var res = await fetch(BASE + '/config.json');
   var config = await res.json();
   init(config);
 
@@ -139,7 +145,10 @@
       // Clear any userinfo so basic-auth creds in the page URL don't leak into
       // the copied prompt (a relative path already drops the page query/hash).
       function exportUrl(file) {
-        var u = new URL(file, location.href);
+        // When served from a base path, resolve against it so the prompt
+        // carries the real export URLs (page URL may have no trailing slash).
+        var ref = (BASE && BASE !== '.') ? BASE + '/' + file : file;
+        var u = new URL(ref, location.href);
         u.username = ''; u.password = '';
         return u.href;
       }

package/lib/template.js

@@ -42,6 +42,32 @@ function generateRootCSS(config) {
   return lines.join('\n');
 }
 
+/**
+ * Escape a string for safe interpolation inside a double-quoted HTML attribute.
+ * A legitimate URL path never contains these chars, so real basePaths pass
+ * through unchanged; a hostile value can't break out of the attribute.
+ */
+function escapeAttr(s) {
+  return String(s).replace(/&/g, '&').replace(/"/g, '"')
+    .replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+/**
+ * Normalize config.basePath into an absolute, no-trailing-slash prefix.
+ * "" / undefined / "/" → "" (served at root, page-relative — unchanged).
+ * "brand" or "/brand/" → "/brand".
+ */
+function normalizeBasePath(bp) {
+  if (!bp || typeof bp !== 'string') return '';
+  var s = bp.trim();
+  if (!s) return '';
+  // Exactly one leading slash: collapse "//brand" (a protocol-relative URL —
+  // browsers read it as a cross-origin host) and "brand" alike to "/brand".
+  s = '/' + s.replace(/^\/+/, '');
+  s = s.replace(/\/+$/, '');
+  return s;
+}
+
 /**
  * Generate a Google Fonts <link> tag from config.fonts.
  */
@@ -64,6 +90,11 @@ function generateFontsLink(config) {
  * Writes index.html and styles.css into the target directory.
  */
 function build(distDir, targetDir, config) {
+  // Absolute base path the guide is served from (e.g. "/brand"). Empty = root /
+  // page-relative, in which case nothing below is rewritten (byte-identical to
+  // the pre-basePath output). The "/" + file form (no trailing slash on basePath)
+  // is what lets a framework rewrite like /brand → /brand/index.html resolve.
+  var basePath = normalizeBasePath(config.basePath);
   // Build styles.css: append the config :root AFTER the stylesheet's default
   // tokens so brand overrides win the cascade (styles.css ships a baseline
   // :root; an earlier block would be overridden by it).
@@ -81,10 +112,34 @@ function build(distDir, targetDir, config) {
   var fontsLink = generateFontsLink(config);
   var brandName = (config.brand && config.brand.displayName) || 'Brand';
 
-  // Inject fonts link + a discovery <link> for the structured brand data
-  var headInject = (fontsLink ? fontsLink + '\n' : '') +
-    '<link rel="alternate" type="application/json" href="brand.json" title="Brand data">\n';
-  htmlTemplate = htmlTemplate.replace('</head>', headInject + '</head>');
+  // Inject fonts link + a discovery <link> for the structured brand data.
+  // When a basePath is set, prefix the brandkit-generated refs (stylesheet,
+  // engine, brand.json) so they resolve from a non-trailing-slash URL; also
+  // expose the base to the runtime engine via window.__BRANDKIT_BASE__.
+  // The Google Fonts link and author-supplied logo paths are left untouched.
+  // basePath is author-controlled config, so it's hardened before it lands in
+  // markup, each context with its own escaping:
+  //  - inline <script>: JSON.stringify + "<" → <, so a "</script>" in the
+  //    value can't break out of the script element (JS-string context).
+  //  - href/src attributes: HTML-attribute-escaped (basePathAttr), so a stray
+  //    quote can't break out of the attribute and inject a handler.
+  //  - all .replace() calls below use function replacers, so a "$" in the path
+  //    isn't interpreted as a $-replacement pattern.
+  var basePathLiteral = JSON.stringify(basePath).replace(/</g, '\\u003C');
+  var basePathAttr = escapeAttr(basePath);
+  var brandJsonHref = basePath ? basePathAttr + '/brand.json' : 'brand.json';
+  var headInject = (basePath ? '<script>window.__BRANDKIT_BASE__ = ' + basePathLiteral + ';</script>\n' : '') +
+    (fontsLink ? fontsLink + '\n' : '') +
+    '<link rel="alternate" type="application/json" href="' + brandJsonHref + '" title="Brand data">\n';
+  htmlTemplate = htmlTemplate.replace('</head>', function () { return headInject + '</head>'; });
+
+  if (basePath) {
+    // Tolerant of quote style / whitespace around "=" so a future reformat of
+    // the template doesn't silently no-op and ship broken (root-relative) refs.
+    htmlTemplate = htmlTemplate
+      .replace(/href\s*=\s*["']styles\.css["']/, function () { return 'href="' + basePathAttr + '/styles.css"'; })
+      .replace(/src\s*=\s*["']engine\.js["']/, function () { return 'src="' + basePathAttr + '/engine.js"'; });
+  }
 
   // Set title
   htmlTemplate = htmlTemplate.replace(
@@ -116,5 +171,6 @@ function build(distDir, targetDir, config) {
 module.exports = {
   generateRootCSS: generateRootCSS,
   generateFontsLink: generateFontsLink,
+  normalizeBasePath: normalizeBasePath,
   build: build
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stacklist-app/brandkit",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "description": "Config-driven brand guide that bolts onto any website. Zero dependencies.",
   "main": "lib/resolve.js",
   "bin": {