@kolkrabbi/kol-shell 0.41.0 → 0.43.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.41.0",
+  "version": "0.43.0",
   "private": false,
   "description": "KOL application shell — fixed 48px NavRail + AppShell layout root, PageShell/PageHeader scaffolds, ContentFilters catalog organism, GridCard, SettingsScaffold, WalkthroughPanel, ShortcutsOverlay. App chrome (kol-framework owns site chrome). Nav items, content, shortcuts and settings are consumer-injected. Sits above @kolkrabbi/kol-{theme,component,framework}.",
   "license": "MIT",
@@ -14,16 +14,16 @@
   "peerDependencies": {
     "@kolkrabbi/kol-component": ">=0.174.0",
     "@kolkrabbi/kol-icons": ">=0.16.0",
-    "@kolkrabbi/kol-theme": ">=0.84.0",
+    "@kolkrabbi/kol-theme": ">=0.135.0",
     "gsap": "^3.13.0",
     "react": "^18.3.0 || ^19.0.0",
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.174.0",
-    "@kolkrabbi/kol-framework": "^0.37.0",
+    "@kolkrabbi/kol-component": "^0.176.0",
+    "@kolkrabbi/kol-framework": "^0.41.0",
     "@kolkrabbi/kol-icons": "^0.25.0",
-    "@kolkrabbi/kol-theme": "^0.132.1"
+    "@kolkrabbi/kol-theme": "^0.135.0"
   },
   "files": [
     "src",

package/src/CatalogPage.jsx

@@ -18,7 +18,7 @@ import WalkthroughPanel from './WalkthroughPanel.jsx'
  *
  * Semantics are the consumer's: what RECENT / SAVED mean, what an item is,
  * what a click does. `toCard(item, { view, layout })` → `{ key, title, detail,
- * media, actions, onClick, href, onNavigate, expanded, expandedContent, fit }` is
+ * media, actions, onClick, href, onNavigate, expanded, expandedContent, fit, ratio }` is
  * the whole contract — `expanded` / `expandedContent` reach `ContentCard catalog`'s
  * 2×2 cell (ShellHomeSystemMonitorGaps, kol-monitor 2026-08-27) — and the page
  * HIDES the cell's three neighbours itself (CatalogPageMonitorParity: the
@@ -27,7 +27,10 @@ import WalkthroughPanel from './WalkthroughPanel.jsx'
  * instead of reflowing around the expanded card); `fit` (`cover` default | `natural` | `compact`) is the
  * card's media fit, PER CARD because one catalog mixes photographs (cover) and
  * diagrams (natural) — CatalogPageCardFit, kol-monitor: a rack preview wider
- * than the card lost its left rail to `cover`. Anything `ContentFilters` takes that the page has no
+ * than the card lost its left rail to `cover`; `ratio` (catalogpage-card-ratio, kol-client-olina
+ * 2026-09-03) is the card's aspect, PER CARD for the same reason — one page renders the same artwork
+ * at 1:1, 4:5 and 9:16 side by side, and a deck is a 16:9 stage — unset falling through to the
+ * variant's A4, so nothing existing moves. Anything `ContentFilters` takes that the page has no
  * prop for goes through `filtersProps` — `mutuallyExclusiveFilters` was the gap.
  *
  * @param {Object}   header        PageHeader props — `{ title, subtitle, size, voice, eyebrow }`
@@ -42,6 +45,9 @@ import WalkthroughPanel from './WalkthroughPanel.jsx'
  * @param {string}   defaultLayout 'grid' (default) | 'list'
  * @param {{steps: Array, open: boolean, iconComponent?: ElementType}} walkthrough  the panel over the catalog
  * @param {ReactNode} actions      the bottom row's buttons
+ * @param {'bleed'|'capped'} width   the page's TIER, forwarded to PageShell (two-page-scaffolds-one-job, 2026-09-03):
+ *                                 `bleed` (default) fills the window — the app tier; `capped` centres on the
+ *                                 framework container — the site tier, so a brand book adopting this page keeps its geometry
  * @param {ElementType} iconComponent  icon renderer seam for ContentFilters
  * @param {boolean}  showCountOnlyWhenFiltering  (default true)
  * @param {Object}   filtersProps  spread onto ContentFilters last — e.g. `{ mutuallyExclusiveFilters: ['category', 'u_label'] }`
@@ -67,6 +73,7 @@ function computeHiddenSet(items, expandedIdx) {
 
 export default function CatalogPage({
   header,
+  width = 'bleed',
   items = [],
   toCard,
   filtersTitle,
@@ -89,7 +96,7 @@ export default function CatalogPage({
 }) {
   const open = walkthrough?.open === true
   return (
-    <PageShell className={className} style={{ overflow: 'hidden', ...style }}>
+    <PageShell width={width} className={className} style={{ overflow: 'hidden', ...style }}>
       {header && <PageHeader {...header} />}
       <div style={{ flex: 1, position: 'relative' }}>
         {open && <WalkthroughPanel steps={walkthrough.steps} iconComponent={walkthrough.iconComponent} />}
@@ -131,7 +138,7 @@ export default function CatalogPage({
                 const key = c.key ?? item.key ?? item.id ?? item.name ?? i
                 return layout === 'list'
                   ? <ContentRow key={key} variant="catalog" title={c.title} detail={c.detail} actions={c.actions} onClick={c.onClick} href={c.href} onNavigate={c.onNavigate} />
-                  : <ContentCard key={key} variant="catalog" fit={c.fit ?? 'cover'} title={c.title} detail={c.detail} media={c.media} actions={c.actions} onClick={c.onClick} href={c.href} onNavigate={c.onNavigate} expanded={c.expanded} expandedContent={c.expandedContent} />
+                  : <ContentCard key={key} variant="catalog" fit={c.fit ?? 'cover'} ratio={c.ratio} title={c.title} detail={c.detail} media={c.media} actions={c.actions} onClick={c.onClick} href={c.href} onNavigate={c.onNavigate} expanded={c.expanded} expandedContent={c.expandedContent} />
               })}
             </div>
             )

package/src/PageShell.jsx

@@ -6,8 +6,19 @@
  * `mode="fixed"`: height 100vh, overflow hidden — pair with a `flex:1
  * overflow:auto` body (the settings idiom; SettingsScaffold does this).
  *
- * Gutter is `--kol-shell-page-pad` (kol-theme). `PageBleed` breaks it for
- * full-width embeds (monitor's rack bleed).
+ * Gutter is `--kol-shell-page-pad` (kol-theme) — since theme 0.135.0 an alias
+ * of `--kol-pad-section-x`, the ONE page-content ladder every `.kol-page`
+ * wears (two-page-scaffolds-one-job, kol-client-olina 2026-09-03: two ladders
+ * for one job agreed only at 48). `PageBleed` breaks it for full-width embeds
+ * (monitor's rack bleed).
+ *
+ * THE GEOMETRY IS A CLASS — `.kol-shell-page` (+ `--fixed`, `--capped`), in
+ * kol-components-shell.css — so a consumer has a selector to reach; inline is
+ * the `style` prop only. `width` is the TIER: `bleed` (default) fills the
+ * window, the app tier; `capped` takes the framework container ladder and
+ * centres, the site tier — the one real difference between this and a
+ * `.kol-page`, and a prop so a site adopting the shipped catalog page does
+ * not silently get app geometry.
  *
  * `scrollbar-gutter: stable` on both modes (PageShellScrollbarGutter,
  * kol-monitor 2026-08-28 — user: "Create is the odd one out"). A page's content
@@ -39,40 +50,31 @@
  * `AppShell pageWash`, a transparent wash over the shell's primary back —
  * the lightness steps up and the structure stays visible, which an opaque
  * surface swap would hide. The ink stays `text-auto` (surface-on-primary).
+ * ONE OWNER PER PIXEL (2026-09-03): the variable means what is LEFT to paint.
+ * kol-shell's `AppShell` hands the wash down for this to paint; kol-framework's
+ * `PageLayout` paints it on its own plane and hands down `transparent`, so a
+ * PageShell inside it does not paint it again (it used to — two 0.02 layers).
+ *
+ * @param {'scroll'|'fixed'} mode   scroll (default) | fixed — see above
+ * @param {'bleed'|'capped'} width  bleed (default, the app tier) | capped (the site tier — `--kol-container-max`, centred)
+ * @param {string}  className
+ * @param {object}  style           inline — the one thing that stays inline
  */
-export default function PageShell({ mode = 'scroll', className = '', style, children }) {
-  const modeStyle =
-    mode === 'fixed'
-      ? { height: '100vh', overflow: 'hidden' }
-      : { minHeight: '100vh' }
+export default function PageShell({ mode = 'scroll', width = 'bleed', className = '', style, children }) {
   return (
     <div
-      className={`text-auto ${className}`.trim()}
-      style={{
-        background: 'var(--kol-shell-page-wash, var(--kol-surface-primary))',
-        padding: 'var(--kol-shell-page-pad)',
-        scrollbarGutter: 'stable',
-        display: 'flex',
-        flexDirection: 'column',
-        ...modeStyle,
-        ...style,
-      }}
+      className={`kol-shell-page${mode === 'fixed' ? ' kol-shell-page--fixed' : ''}${width === 'capped' ? ' kol-shell-page--capped' : ''} text-auto ${className}`.trim()}
+      style={style}
     >
       {children}
     </div>
   )
 }
 
-/** Full-bleed slot — cancels PageShell's horizontal gutter. */
+/** Full-bleed slot — cancels PageShell's horizontal gutter (`.kol-shell-page-bleed`). */
 export function PageBleed({ style, children }) {
   return (
-    <div
-      style={{
-        marginLeft: 'calc(var(--kol-shell-page-pad) * -1)',
-        marginRight: 'calc(var(--kol-shell-page-pad) * -1)',
-        ...style,
-      }}
-    >
+    <div className="kol-shell-page-bleed" style={style}>
       {children}
     </div>
   )