@stacklist-app/brandkit 1.2.2 → 1.2.4

package/README.md

@@ -43,6 +43,8 @@ A brandkit guide isn't just a page for people — `build` (and the standalone `e
 
 `build` also makes the data **discoverable from the deployed page**: it injects `<link rel="alternate" type="application/json" href="brand.json">` and embeds the brand inline as `<script type="application/json" id="brandkit-brand">`, so an agent that fetches the URL gets structured brand data with zero extra requests.
 
+And for a person who wants to hand the guide to their own agent, the sidebar shows a **"Using an AI agent?"** callout with a one-click copy-paste prompt — it carries absolute URLs to `brand.json` / `tokens.json` / `brand.md` and tells the agent to read those instead of scraping the page. Hide it with `brand.agentCallout: false`.
+
 A JSON Schema for `config.json` ships at [`config.schema.json`](config.schema.json) — point your editor's `$schema` at it for validation and autocomplete.
 
 ## Framework integrations
@@ -71,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"],
@@ -51,7 +52,8 @@
         "date": { "type": "string" },
         "guideLabel": { "type": "string", "description": "Renames the 'Web Style Guide' label in the header and footer." },
         "headerLogo": { "type": "string", "description": "Path to a logo image shown in the header instead of the text wordmark (use a light/reversed logo)." },
-        "sidebarLogo": { "type": "string", "description": "Path to a logo image shown at the top of the left menu instead of the brand name (use a dark logo)." }
+        "sidebarLogo": { "type": "string", "description": "Path to a logo image shown at the top of the left menu instead of the brand name (use a dark logo)." },
+        "agentCallout": { "type": "boolean", "description": "Show the 'Using an AI agent?' callout under the sidebar nav — a copy-paste prompt pointing an agent at the brand.json / tokens.json / brand.md exports. Defaults to true; set false to hide it." }
       }
     },
     "fonts": {

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);
 
@@ -123,6 +129,60 @@
       }).join('');
     }
 
+    /* ==============================================================
+       2b. Render agent callout — a paste-ready prompt that points an AI
+       agent at the machine-readable exports (brand.json / tokens.json /
+       brand.md) so it reads structured brand data instead of scraping the
+       rendered page. Opt out with brand.agentCallout === false.
+       ============================================================== */
+    function renderAgentCallout() {
+      var box = document.getElementById('agent-callout');
+      if (!box) return;
+      if (cfg.brand && cfg.brand.agentCallout === false) return;
+
+      // Resolve export URLs relative to this page exactly as a link would, so
+      // the pasted prompt carries absolute URLs the agent can fetch directly.
+      // 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) {
+        // 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;
+      }
+      var brandUrl, tokensUrl, mdUrl;
+      try {
+        brandUrl = exportUrl('brand.json');
+        tokensUrl = exportUrl('tokens.json');
+        mdUrl = exportUrl('brand.md');
+      } catch (_) {
+        brandUrl = 'brand.json'; tokensUrl = 'tokens.json'; mdUrl = 'brand.md';
+      }
+      // Strip control chars / newlines and collapse whitespace so a hostile
+      // brand name can't smuggle instructions into the paste-ready agent prompt.
+      var name = ((cfg.brand && (cfg.brand.displayName || cfg.brand.name)) || 'this brand')
+        .replace(/[\u0000-\u001F\u007F\u00AD\u200B-\u200F\u202A-\u202E\u2060-\u2069\uFEFF]/g, ' ').replace(/\s+/g, ' ').trim() || 'this brand';
+      var prompt =
+        'This page is a brandkit brand guide for ' + name + '. It publishes ' +
+        'machine-readable brand data — read these instead of scraping the page:\n\n' +
+        '- ' + brandUrl + ' — full structured brand: colors (roles + contrast), typography, voice, logos, spacing\n' +
+        '- ' + tokensUrl + ' — W3C design tokens (DTCG $type/$value), for code and design tooling\n' +
+        '- ' + mdUrl + ' — brand brief: how to stay on-brand\n\n' +
+        'Fetch them, then apply ' + name + "'s colors, type, and voice to what you're building.";
+
+      box.innerHTML =
+        '<div class="sidebar-agent-title">Using an AI agent?</div>' +
+        '<p class="sidebar-agent-desc">Paste this so it reads the brand data, not the page.</p>' +
+        '<button type="button" class="sidebar-agent-btn" id="agent-callout-btn">Copy agent prompt</button>';
+      // Set the payload via property (not an HTML attribute) so no font/brand
+      // value needs escaping and newlines survive intact.
+      var btn = box.querySelector('#agent-callout-btn');
+      if (btn) btn.dataset.copy = prompt;
+      box.hidden = false;
+    }
+
     /* ==============================================================
        3. Render colors
        ============================================================== */
@@ -686,6 +746,13 @@
           copyText(codeLine.dataset.copy);
           return;
         }
+
+        // Agent callout prompt
+        var agentBtn = e.target.closest('#agent-callout-btn');
+        if (agentBtn) {
+          copyText(agentBtn.dataset.copy);
+          return;
+        }
       });
     }
 
@@ -886,6 +953,7 @@
     bootstrap();
     renderShell();
     renderNav();
+    renderAgentCallout();
     renderSectionIntros();
     renderColors();
     renderGradients();

package/dist/index.html

@@ -14,6 +14,7 @@
   <nav class="sidebar">
     <div class="sidebar-brand">brandkit</div>
     <ul class="sidebar-nav" id="nav"></ul>
+    <div class="sidebar-agent" id="agent-callout" hidden></div>
   </nav>
 
   <!-- Main Content -->

package/dist/styles.css

@@ -129,11 +129,49 @@ body {
 .sidebar-nav a:hover { color: var(--ink); background: var(--cloud); }
 .sidebar-nav a.active { color: var(--accent-text); border-left-color: var(--accent-text); background: rgba(var(--accent-rgb), 0.04); font-weight: 500; }
 
+/* Agent callout — paste-ready prompt that points an AI agent at the exports */
+.sidebar-agent {
+  margin: 28px 16px 8px;
+  padding: 14px;
+  border: 1px solid var(--mist);
+  border-radius: 12px;
+  background: rgba(var(--accent-rgb), 0.04);
+}
+.sidebar-agent-title {
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--ink);
+  margin-bottom: 4px;
+}
+.sidebar-agent-desc {
+  font-size: 11px;
+  line-height: 1.4;
+  color: var(--slate);
+  margin: 0 0 10px;
+}
+.sidebar-agent-btn {
+  display: block;
+  width: 100%;
+  padding: 7px 10px;
+  font-size: 12px;
+  font-weight: 500;
+  font-family: inherit;
+  color: var(--primary-foreground);
+  background: var(--primary);
+  border: none;
+  border-radius: 8px;
+  cursor: pointer;
+  transition: filter 150ms ease;
+}
+.sidebar-agent-btn:hover { filter: brightness(0.9); }
+.sidebar-agent-btn:active { transform: translateY(1px); }
+.sidebar-agent-btn:focus-visible { outline: 2px solid var(--accent-text); outline-offset: 2px; }
+
 /* ── Sidebar Grouped Navigation ── */
 .nav-group {
   padding: 20px 24px 6px;
   font-family: var(--font-body), sans-serif;
-  font-size: 10px;
+  font-size: 12px;
   font-weight: 700;
   letter-spacing: 0.10em;
   text-transform: uppercase;

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.2",
+  "version": "1.2.4",
   "description": "Config-driven brand guide that bolts onto any website. Zero dependencies.",
   "main": "lib/resolve.js",
   "bin": {