@kolkrabbi/kol-framework 0.48.0 → 0.50.0

package/kol-framework.css

@@ -101,9 +101,12 @@ body {
      deliberately tighter: chrome is not page content. The shell header and the
      shell content frame both read this, so they cannot disagree; before it,
      the header carried bare Tailwind steps and the frame carried the page ramp.
-     FLAT, not stepped — one value at every width, on the user's word.
+     ONE STEP (user ruling 2026-10-02, the phone pass): on a phone it is the
+     page ladder's 20, so the header, the frame and a page all stand on one
+     edge — it was 24 at every width, which put a phone page 4px off the
+     ladder. 24 returns at 768, where the 2026-07-31 ruling was made.
      Do NOT reach for this on page containers — that is --kol-pad-section-x. */
-  --kol-pad-chrome-x: var(--kol-spacing-6);
+  --kol-pad-chrome-x: var(--kol-spacing-5);
 
   /* Stepped page / section / band padding tokens.
      Used by chrome (topnav, sidenav) and landing bands. Scaled at 768 / 1024
@@ -117,6 +120,7 @@ body {
 
 @media (min-width: 768px) {
   :root {
+    --kol-pad-chrome-x:  var(--kol-spacing-6);
     --kol-pad-page-x:    32px;
     --kol-pad-page-y:    96px;
     --kol-pad-section-x: 32px;

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@kolkrabbi/kol-framework",
-  "version": "0.48.0",
-  "description": "KOL app shell — sidenav, layout, theme toggle, footer, heroes + brand color layer. SideNav takes nav data as props so the tree stays app-local.",
+  "version": "0.50.0",
+  "description": "Site shell and page layout",
   "license": "MIT",
   "type": "module",
   "main": "./src/index.js",
   "module": "./src/index.js",
   "exports": {
     ".": "./src/index.js",
+    "./vite": "./src/vite.js",
     "./src/*": "./src/*",
     "./kol-framework.css": "./kol-framework.css",
     "./kol-brand-color.css": "./kol-brand-color.css"
@@ -21,8 +22,8 @@
     "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.230.0",
-    "@kolkrabbi/kol-icons": "^0.30.0"
+    "@kolkrabbi/kol-component": "^0.266.0",
+    "@kolkrabbi/kol-icons": "^0.39.0"
   },
   "files": [
     "src",

package/src/PageHero.jsx

@@ -2,7 +2,7 @@ import { Link } from 'react-router-dom'
 import { SectionText } from '@kolkrabbi/kol-component'
 
 /**
- * PageHero — the page's opening band: label · title · lede, with an optional
+ * PageHero — A page's opening band. the page's opening band: label · title · lede, with an optional
  * mark beside the text and an optional back link above it.
  *
  * ONE HERO (page-family-is-not-a-set, kol-client-olina 2026-09-03; user, on

package/src/PageLayout.jsx

@@ -24,7 +24,7 @@ export const ShellTocCollapsedContext = createContext(null)
  * (sidenav-rail-hairline, 2026-08-26): `background`, `hairline`, `isActive`,
  * `onNavigate` … the next rail option needs no AppShell release. */
 /**
- * PageLayout — the brand-book page layout: the `.kol-brand-layout` grid with
+ * PageLayout — The brand-book page layout. the brand-book page layout: the `.kol-brand-layout` grid with
  * the sidenav in its first track, the page plane in the second, the mobile
  * drawer + hamburger, the modal provider and the optional TOC rail.
  *

package/src/ThemeToggle.jsx

@@ -3,7 +3,7 @@ import { Tooltip } from '@kolkrabbi/kol-component'
 import { useTheme } from './theme.js'
 
 /**
- * Theme toggle — two-position glyph-roll button (the approved 2-variant spec).
+ * Theme toggle — Switch between light and dark. Two-position glyph-roll button (the approved 2-variant spec).
  *
  * Clicking cycles **light ↔ dark**. `system` is not a position — see the
  * ruling above MODE_LABEL. Alt- or shift-click clears the choice and hands the

package/src/index.js

@@ -17,6 +17,8 @@ export { useDragResize } from '@kolkrabbi/kol-component'
 export { default as ShellHeader, HEADER_ICON } from './ShellHeader.jsx'
 export { default as ThemeToggle } from './ThemeToggle.jsx'
 export { useTheme, applyTheme, getInitialTheme, THEME_STORAGE_KEY, THEME_BOOT_SCRIPT } from './theme.js'
+/* the app loader's runtime half — the build half is `loaderApp()` in `@kolkrabbi/kol-framework/vite` */
+export { hideLoaderApp } from './loaderApp.js'
 export { default as Layout } from './Layout.jsx'
 export { default as PageSection } from './PageSection.jsx'
 export { default as PortalFooter } from './PortalFooter.jsx'

package/src/loaderApp.js

@@ -0,0 +1,14 @@
+/**
+ * hideLoaderApp — the app loader's other half (`loaderApp()` in `@kolkrabbi/kol-framework/vite` writes it into
+ * index.html). Call it once React has committed: two frames later the loader fades (240 ms, none under reduced
+ * motion — the CSS drops the transition) and leaves the DOM. Safe to call when there is no loader.
+ */
+export function hideLoaderApp() {
+  if (typeof document === 'undefined') return
+  const el = document.getElementById('kol-loader-app')
+  if (!el) return
+  requestAnimationFrame(() => requestAnimationFrame(() => {
+    el.classList.add('is-done')
+    setTimeout(() => { el.remove(); document.getElementById('kol-loader-app-css')?.remove() }, 300)
+  }))
+}

package/src/vite.js

@@ -0,0 +1,71 @@
+/**
+ * Vite plugins for KOL apps — Node-side, no React (import from `@kolkrabbi/kol-framework/vite` in vite.config).
+ *
+ * devFavicon — THE DEV TAB IS TELLABLE AT A GLANCE (2026-10-17 — user: "I need to be able to tell which tabs
+ * are localhost dev and which are production"). On the dev server the favicon becomes a solid tile with the
+ * app's letters; a build never sees it (`apply: 'serve'`). It REPLACES the page's icon link: fxr appended a
+ * second one and browsers pick their own (Firefox kept prod's), mirror swapped it at runtime after load.
+ * Each app picks its letters and ground once — the table lives in 16-app-anatomy.md § Dev favicon.
+ *
+ * @param {Object} [opts]
+ * @param {string} [opts.label='DEV']   1–3 letters, fitted to the tile
+ * @param {string} [opts.ground='#7C5CFF']  the tile's colour — unique per app
+ * @param {string} [opts.ink='#FFFFFF']
+ */
+export function devFavicon({ label = 'DEV', ground = '#7C5CFF', ink = '#FFFFFF' } = {}) {
+  const text = String(label).slice(0, 3).toUpperCase()
+  const size = text.length === 1 ? 28 : text.length === 2 ? 20 : 15
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="6" fill="${ground}"/>`
+    + `<text x="16" y="${(16 + size * 0.36).toFixed(1)}" text-anchor="middle" font-family="Arial Black, Arial, sans-serif" font-weight="900" font-size="${size}"`
+    + `${text.length > 1 ? ' textLength="28" lengthAdjust="spacingAndGlyphs"' : ''} fill="${ink}">${text}</text></svg>`
+  const link = `<link rel="icon" type="image/svg+xml" href="data:image/svg+xml,${encodeURIComponent(svg)}">`
+  return {
+    name: 'kol-dev-favicon',
+    apply: 'serve',
+    transformIndexHtml(html) {
+      return /<link rel="icon"[^>]*>/.test(html) ? html.replace(/<link rel="icon"[^>]*>/, link) : html.replace('</head>', `${link}</head>`)
+    },
+  }
+}
+
+/**
+ * loaderApp — THE APP LOADER, OWNED ONCE (AppLoader, kol-monitor 2026-10-17 — user: *"shouldnt that loader just be
+ * owned in DS and consumed by the fxr monitor and mirror? with custom graphic input as prop?"*). The app's mark
+ * centred on the theme's ground, pulsing while the bundle downloads. It has to be static HTML in `index.html` —
+ * a React component would only appear after the wait it covers — so this plugin writes it there: fxr's loader,
+ * once, with the graphic as an option. Call `hideLoaderApp()` (kol-framework) after the first commit.
+ *
+ * Ground and ink follow the stored `data-theme`, else the system (run `THEME_BOOT_SCRIPT` before it, as every
+ * KOL app does). Reduced motion: no pulse, no fade.
+ *
+ * @param {Object} opts
+ * @param {string} opts.graphic   an SVG — the markup itself, or a path (relative to the app root) to an .svg file;
+ *                                draw it in `currentColor` so it takes the ground's ink
+ * @param {number} [opts.size=64] the mark's edge in px
+ */
+export function loaderApp({ graphic, size = 64 } = {}) {
+  let root = process.cwd()
+  const css = `#kol-loader-app{position:fixed;inset:0;z-index:2147483647;display:grid;place-items:center;background:#FAFAFA;color:#0E0E11;transition:opacity 240ms ease}`
+    + `@media (prefers-color-scheme: dark){:root:not([data-theme="light"]) #kol-loader-app{background:#121215;color:#FFFFFF}}`
+    + `:root[data-theme="dark"] #kol-loader-app{background:#121215;color:#FFFFFF}`
+    + `#kol-loader-app svg{width:${size}px;height:${size}px;animation:kol-loader-app-pulse 1.6s ease-in-out infinite}`
+    + `#kol-loader-app.is-done{opacity:0;pointer-events:none}`
+    + `@keyframes kol-loader-app-pulse{50%{opacity:.35}}`
+    + `@media (prefers-reduced-motion: reduce){#kol-loader-app svg{animation:none}#kol-loader-app{transition:none}}`
+  return {
+    name: 'kol-loader-app',
+    configResolved(config) { root = config.root },
+    async transformIndexHtml(html) {
+      let svg = String(graphic ?? '').trim()
+      if (svg && !svg.startsWith('<')) {
+        const { readFile } = await import('node:fs/promises')
+        const { resolve } = await import('node:path')
+        svg = (await readFile(resolve(root, svg), 'utf8')).trim()
+      }
+      svg = svg.replace(/<\?xml[^>]*>/, '').replace(/<!--[\s\S]*?-->/g, '')
+      return html
+        .replace('</head>', `<style id="kol-loader-app-css">${css}</style></head>`)
+        .replace(/<body([^>]*)>/, `<body$1><div id="kol-loader-app" aria-hidden="true">${svg}</div>`)
+    },
+  }
+}