@kolkrabbi/kol-component 0.228.0 → 0.230.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.228.0",
+  "version": "0.230.0",
   "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
   "license": "MIT",
   "type": "module",
@@ -25,7 +25,8 @@
     "embla-carousel-react": "^8.6.0",
     "pdfjs-dist": "^6.3.289",
     "react-syntax-highlighter": "^16.1.1",
-    "@kolkrabbi/kol-markdown": "^0.1.0"
+    "@kolkrabbi/kol-search": "^0.2.0",
+    "@kolkrabbi/kol-markdown": "^0.1.2"
   },
   "peerDependencies": {
     "@kolkrabbi/kol-icons": ">=0.22.0",
@@ -36,7 +37,7 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-icons": "^0.29.0"
+    "@kolkrabbi/kol-icons": "^0.29.1"
   },
   "files": [
     "src",

package/src/atoms/ActionButton.jsx

@@ -146,7 +146,7 @@ export default function ActionButton({
     const rest = restRef.current
     const on = onRef.current
     /* no confirmIcon = ONE glyph, and the state is carried by the class alone
-     * (a fill, a colour). Nothing to crossfade. */
+     * (a fill, a color). Nothing to crossfade. */
     if (!rest || !on) return undefined
 
     if (first.current) {

package/src/atoms/Button.jsx

@@ -18,7 +18,7 @@ import { glyphSize } from '../hooks/glyphLadders.js'
  * @param {string} props.iconRight - Icon name to display on the right
  * @param {string} props.iconLeftHover - Icon to show on hover (left position)
  * @param {string} props.iconRightHover - Icon to show on hover (right position)
- * @param {'primary'|'secondary'|'inverted'|'outline'|'ghost'|'grey'|'sunken'} props.tone - the ground (`secondary` = the page surface, `inverted` = the text colour as fill — what `variant="secondary"` paints) (tone-is-the-ground-axis, 2026-09-03) — wins over `variant` on the same element; unset = inherit the wrapper's. `sunken` = the control set's dark well + fg-96 ink (ControlToneSunken); `inverse` aliased
+ * @param {'primary'|'secondary'|'inverted'|'outline'|'ghost'|'grey'|'sunken'} props.tone - the ground (`secondary` = the page surface, `inverted` = the text color as fill — what `variant="secondary"` paints) (tone-is-the-ground-axis, 2026-09-03) — wins over `variant` on the same element; unset = inherit the wrapper's. `sunken` = the control set's dark well + fg-96 ink (ControlToneSunken); `inverse` aliased
  * @param {string} props.iconOnly - Icon name for icon-only button
  * @param {string} props.iconOnlyHover - Icon to show on hover (icon-only)
  * @param {boolean} props.animateIcon - Disable default hover states to focus on icon animation
@@ -81,8 +81,14 @@ const Button = ({
    * grey) or its own bundle (nav · danger · accent); `nav` is ghost's chrome
    * rung, oq-80 ink + aria-current — it had lived in the theme with no
    * component able to emit it, the direct cause of the four-container header. */
+  /* An UNKNOWN variant is a typo, not a request for the inverted fill — it fell back to
+   * `kol-btn-secondary` (the text color as fill) until 2026-09-29, so a misspelt variant
+   * shipped inverted. It now stamps nothing, like an unset variant: the wrapper's tone,
+   * else primary — and says so in dev. */
   const KNOWN = ['primary', 'secondary', 'accent', 'outline', 'ghost', 'nav', 'danger', 'grey']
-  const variantClass = !resolvedVariant ? '' : KNOWN.includes(resolvedVariant) ? `kol-btn-${resolvedVariant}` : 'kol-btn-secondary'
+  const known = !resolvedVariant || KNOWN.includes(resolvedVariant)
+  if (!known && import.meta.env.DEV) console.warn(`Button: unknown variant "${resolvedVariant}" — rendering the inherited tone (primary)`)
+  const variantClass = resolvedVariant && known ? `kol-btn-${resolvedVariant}` : ''
 
   // Add size class — pairs the padding rule with its mono type class.
   const sizeClass = size === 'sm'

package/src/atoms/IconFrame.jsx

@@ -22,7 +22,7 @@ import { toneClass } from '../utilities/tone.js'
  * frame's own classes declare the same background, foreground and geometry and
  * simply have no state rules to inherit.
  *
- * `variant` borrows the kol-btn COLOUR SET verbatim so the frame sits in the
+ * `variant` borrows the kol-btn COLOR SET verbatim so the frame sits in the
  * same visual system as real buttons; `primary` and `secondary` are inverse
  * pairs that flip with the theme, so light/dark comes free from the tokens with
  * no per-theme props.

package/src/atoms/Input.jsx

@@ -158,8 +158,9 @@ export default function Input({
    * or <label> at the same kol-mono-N — Chromium computes input height
    * from the font's ascender+descender (font-metric), not strictly from
    * CSS line-height. Result: kol-control-sm ends up 26.5px instead of 26.
-   * h-4 / h-[18px] / h-[22px] match the kol-mono-12 / -14 / -16 line-heights. */
-  const heightCls = size === 'xs' ? 'h-3' : size === 'sm' ? 'h-4' : size === 'md' ? 'h-[18px]' : 'h-[22px]'
+   * h-4 / h-[18px] / h-[22px] match the kol-mono-12 / -14 / -16 line-heights; on touch every size is
+   * the 16 / 22 rung (D5, 2026-09-29 — see SearchInput) */
+  const heightCls = `${size === 'xs' ? 'h-3' : size === 'sm' ? 'h-4' : size === 'md' ? 'h-[18px]' : 'h-[22px]'} pointer-coarse:h-[22px]`
 
   const inputCls = [
     'min-w-0 bg-transparent border-none outline-none text-auto',

package/src/atoms/SizeOrDownload.jsx

@@ -21,7 +21,7 @@ import { Icon } from '@kolkrabbi/kol-icons'
  * click, and this one is inside the link rather than being it.
  *
  * Both hover parts ink on the OPACITY scale (`text-oq-80`), not an `fg-*` role:
- * a stroke glyph on a flat fg colour reads wrong against the plate, and oq is
+ * a stroke glyph on a flat fg color reads wrong against the plate, and oq is
  * what the rest of the chrome uses.
  *
  * ONE type class throughout — kol-mono-12. helper-12 is line-height 1 against

package/src/atoms/Tag.jsx

@@ -18,7 +18,7 @@ const ICON_SIZES = { xs: 8, sm: 10, md: 12, lg: 14 }
  *     `:hover` rule between them, on `.tag-control`. Every other path rendered
  *     dead.
  *   - `color` was a SECOND axis that silently swapped the base class from
- *     `tag-control` to `tag tag--{color}` — so passing a colour cost you the
+ *     `tag-control` to `tag tag--{color}` — so passing a color cost you the
  *     interaction state, invisibly. That is what shipped a solid blue pill you
  *     could not hover.
  *   - `variant="solid"` and a `solid` boolean did the same job.
@@ -28,8 +28,8 @@ const ICON_SIZES = { xs: 8, sm: 10, md: 12, lg: 14 }
  *
  * Now it is Pill's vocabulary — `primary` (filled) · `secondary` (outlined) ·
  * `inverse` — one size scale, ONE class scheme (`kol-tag--*`), and every
- * variant carries hover + active. Colour is not a prop: a chip's look is its
- * variant, exactly as it is on Pill and Button. Tag colour BY TAXONOMY returns
+ * variant carries hover + active. Color is not a prop: a chip's look is its
+ * variant, exactly as it is on Pill and Button. Tag color BY TAXONOMY returns
  * later as its own decision, on top of the variants rather than instead of them.
  *
  * @param {ReactNode} children   label content

package/src/hooks/colorMath.js

@@ -116,7 +116,7 @@ export function harmonyColors(hue, harmony, { saturation = 100, lightness = 50 }
  * package's `colors` payload was half-ignorable).
  *
  * A slot that is `locked`, empty, or has no hex is passed through untouched —
- * locking a colour is the one instruction a re-hue must not overrule.
+ * locking a color is the one instruction a re-hue must not overrule.
  *
  * @param {number} hue base hue, 0–360
  * @param {string|object} harmony harmony id or object

package/src/index.js

@@ -22,14 +22,14 @@ export { default as AssetPlaceholder } from './utilities/AssetPlaceholder.jsx'
 export { default as Avatar } from './atoms/Avatar.jsx'
 export { default as Badge } from './atoms/Badge.jsx'
 export { default as Button } from './atoms/Button.jsx'
-export { default as CloseButton } from './utilities/CloseButton.jsx'
+export { default as CloseButton } from './atoms/CloseButton.jsx'
 export { default as ActionButton } from './atoms/ActionButton.jsx'
 export { default as FileIcon } from './atoms/FileIcon.jsx'
 export { default as SizeOrDownload } from './atoms/SizeOrDownload.jsx'
 export { default as SortHeader } from './atoms/SortHeader.jsx'
 export { default as SortControls } from './molecules/SortControls.jsx'
 export { default as CopyButton } from './molecules/CopyButton.jsx'
-export { default as CurveOverlay } from './atoms/CurveOverlay.jsx'
+export { default as CurveOverlay } from './utilities/CurveOverlay.jsx'
 export { default as Divider } from './atoms/Divider.jsx'
 export { default as DocsToc } from './molecules/DocsToc.jsx'
 export { default as DropdownTagFilter } from './molecules/DropdownTagFilter.jsx'
@@ -49,7 +49,7 @@ export { default as LabeledControl } from './molecules/LabeledControl.jsx'
 export { default as OverlayGlassPanel } from './utilities/OverlayGlassPanel.jsx'
 export { default as Pill } from './atoms/Pill.jsx'
 export { usePopover, PopoverPanel, Tooltip } from './utilities/Popover.jsx'
-export { default as ContextMenu, useContextMenu } from './utilities/ContextMenu.jsx'
+export { default as ContextMenu, useContextMenu } from './molecules/ContextMenu.jsx'
 export { default as ProsePreview } from './utilities/ProsePreview.jsx'
 export { default as QuantityInput } from './molecules/QuantityInput.jsx'
 export { default as RotaryDial } from './atoms/RotaryDial.jsx'
@@ -73,8 +73,8 @@ export { default as InspectorRail } from './molecules/InspectorRail.jsx'
 /* SelectionOverlay's two siblings — same 1080-virtual contract, same zoom
  * division (editor-panels-the-held-specs B2). `pathMath` is their geometry,
  * exported because the editor engine re-exports it rather than keep a copy. */
-export { default as PathNodeOverlay } from './atoms/PathNodeOverlay.jsx'
-export { default as CropOverlay } from './atoms/CropOverlay.jsx'
+export { default as PathNodeOverlay } from './utilities/PathNodeOverlay.jsx'
+export { default as CropOverlay } from './utilities/CropOverlay.jsx'
 export { default as LayerStack, AddLayerButton, BLEND_MODES } from './organisms/LayerStack.jsx'
 export { TYPE_LABELS, BOOL_OP_LABELS, SHAPE_KIND_LABELS, labelForLayer, rowLabelForLayer, findLayerDeep } from './hooks/layerTree.js'
 export { default as TimelineDock, sampleTrack, TIMELINE_EASINGS } from './organisms/TimelineDock.jsx'
@@ -88,7 +88,7 @@ export { default as ButtonGroup } from './utilities/ButtonGroup.jsx'
 /* monorepo sets (P6–P10) — molecule members */
 export { default as AlignmentGrid } from './molecules/AlignmentGrid.jsx'
 export { default as ImageBlock } from './molecules/ImageBlock.jsx'
-export { default as SelectionOverlay } from './atoms/SelectionOverlay.jsx'
+export { default as SelectionOverlay } from './utilities/SelectionOverlay.jsx'
 export { default as VideoBlock, getEmbedUrl } from './molecules/VideoBlock.jsx'
 export { default as SectionCardItem, default as CardFeatureItem } from './molecules/SectionCardItem.jsx'
 export { default as CodeBlock } from './molecules/CodeBlock.jsx'
@@ -152,6 +152,7 @@ export { default as EmblaNav } from './molecules/EmblaNav.jsx'
 export { default as MobileTabBar, TABBAR_H } from './molecules/MobileTabBar.jsx'
 export { default as ContentFilters } from './organisms/ContentFilters.jsx'
 export { default as PageHeader } from './molecules/PageHeader.jsx'
+export { MastheadContext, MASTHEADS, useMasthead, mastheadTitleClass } from './utilities/masthead.js'
 export { default as ErrorBoundary } from './utilities/ErrorBoundary.jsx'
 export { default as FeatureSplit } from './organisms/FeatureSplit.jsx'
 export { default as FeaturedCarousel } from './organisms/FeaturedCarousel.jsx'

package/src/molecules/ColorInputRow.jsx

@@ -243,7 +243,7 @@ export default function ColorInputRow({
           )}
           {/* QUICK STATES. Theme (the auto value — a token that flips with
               light/dark) is offered only where the field HAS one; None is
-              always available, because clearing a colour is not a palette
+              always available, because clearing a color is not a palette
               decision. Both were dropped in the first port, which is what left
               `value == null` renderable but unreachable. */}
           <div className="flex items-center gap-2">

package/src/molecules/ContentCard.jsx

@@ -47,7 +47,7 @@ const BOX = {
   /* SLIDE (slide-variant-and-shelf-preset, kol-client-olina 2026-09-03; user: "they are genuinely
    * different with 16:9 layout and those exposed properties"): file's stack — cover on top, the
    * plate below — on the PAGE'S surface, rest and hover (olina's /slide-deck, read off the render).
-   * The plate is not a tone (user: "no just controls"); it is this kind's colour. */
+   * The plate is not a tone (user: "no just controls"); it is this kind's color. */
   slide: { layout: 'stack', border: null, bg: 'var(--kol-surface-primary)', pad: 'var(--kol-pad-card-sm)' },
   /* THE FRAME READS BACKWARDS (CatalogCardFrameAndZoom, kol-website 2026-08-28 — user, on a 212-tile
    * grid: no frame at rest; the old rest value is the hover): a wall of fg-04 frames is a grid of boxes,
@@ -94,7 +94,7 @@ const BOX = {
  * has no surface of its own to step, so it dims its title instead. */
 const HOVER = {
   file:  'var(--kol-oq-04)',
-  slide: 'var(--kol-surface-primary)', /* the plate holds its colour on hover; the drawer control is the affordance */
+  slide: 'var(--kol-surface-primary)', /* the plate holds its color on hover; the drawer control is the affordance */
   catalog:  'var(--kol-surface-tertiary)',
   /* article and work take NO surface hover, and that is a decision not a gap:
    * article has no surface of its own (its media frame, when on, steps its
@@ -168,7 +168,7 @@ export default function ContentCard({
    * print draw it); `false` turns it off without an `!important` in a consumer sheet */
   plateRule,
   /* `bg` — the card's REST fill, overriding the variant's. It sets
-   * `--kol-card-bg`, not a background, because the rest colours are custom
+   * `--kol-card-bg`, not a background, because the rest colors are custom
    * properties so the hover class can win; that is also why
    * `className="bg-oq-48"` does nothing here and a consumer reaching around the
    * component had to write `className="[--kol-card-bg:var(--kol-oq-48)]"`
@@ -437,7 +437,7 @@ export default function ContentCard({
     'data-tags': isHero && Array.isArray(text.tags) && text.tags.length ? text.tags.join(' ') : undefined,
     className: `kol-card group flex ${box.layout === 'canvas' && reveal != null ? 'has-reveal' : ''} ${expanded ? 'flex-col md:flex-row-reverse' : 'flex-col'} ${box.layout === 'drawer' ? 'relative overflow-hidden rounded-[var(--kol-radius-sm)]' : ''} ${framed ? 'overflow-hidden rounded-[var(--kol-radius-sm)]' : ''} ${box.border ? 'border' : ''} ${box.layout === 'canvas' ? 'relative' : ''} ${interactive ? 'cursor-pointer select-none' : ''} ${hoverBg && interactive ? 'kol-content-hover' : ''} ${interactive && box.frameHover ? 'kol-content-hover-frame' : ''} ${className}`.trim(),
     style: {
-      /* same reason as ContentRow: rest colours are PROPERTIES, because an
+      /* same reason as ContentRow: rest colors are PROPERTIES, because an
        * inline background/borderColor outranks the hover class and the step
        * would never render. */
       '--kol-card-bg': bg ?? box.bg ?? undefined,
@@ -464,7 +464,7 @@ export default function ContentCard({
         onContextMenu={onContextMenu}
         onDoubleClick={onDoubleClick}
         /* SELECTED HAS TO SHOW (user 2026-09-23: a click in the grid "should select/highlight").
-         * `selected` only flipped a border colour on the variants that HAVE a border, and the file
+         * `selected` only flipped a border color on the variants that HAVE a border, and the file
          * wall's cards have none — so the prop was true and the card looked untouched. The
          * attribute is the hook; the theme paints it, once, for every variant. */
         data-selected={selected || undefined}

package/src/molecules/ContentMedia.jsx

@@ -57,7 +57,7 @@ import AssetPlaceholder from '../utilities/AssetPlaceholder.jsx'
  * @param {boolean}   frame     tinted box + border UNDER the media
  * @param {boolean}   border    border only, no tint
  * @param {string}    bg        tint only, no border — a raw token value
- * @param {string}    borderHover  border colour on hover (article's fg-16 step)
+ * @param {string}    borderHover  border color on hover (article's fg-16 step)
  * @param {boolean}   ring      hairline border OVER the media, inset
  * @param {boolean|'hero'} zoom  the artwork creeps up inside its frame on the
  *                            card's hover — 1.06; `'hero'` = the hero rung, 1.02

package/src/molecules/ContentRow.jsx

@@ -130,7 +130,7 @@ const BOX = {
                      * its background and read as a different interaction from every other listing.
                      *
                      * The three passes are the lesson: the ask was "make it look like /work" and
-                     * each ticket named only the state someone had looked at — rest colours, then
+                     * each ticket named only the state someone had looked at — rest colors, then
                      * the derive's collateral, then this. When a user says make X look like Y,
                      * diff EVERY state: rest, hover, selected, focus. */
                     bg: 'var(--kol-surface-secondary)', frame: 'transparent', frameHover: 'var(--kol-fg-08)' },
@@ -171,7 +171,7 @@ export default function ContentRow({
    * card, `contentcard-bg-and-text-props` 2026-09-03; the pair ships together
    * and a consumer that re-grounds one hits the same wall on the other in the
    * same grid). It sets `--kol-row-bg`, not a background, because the rest
-   * colours are custom properties so the hover class can win — which is why
+   * colors are custom properties so the hover class can win — which is why
    * `className="bg-oq-48"` does nothing here either. `selected` still wins:
    * a selected row is the list's state, not the consumer's ground. For the
    * row's INK, pass `text` — it falls through to ContentText. */

package/src/{utilities → molecules}/ContextMenu.jsx

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useState } from 'react'
-import { usePopover, PopoverPanel } from './Popover.jsx'
+import { usePopover, PopoverPanel } from '../utilities/Popover.jsx'
 
 /**
  * ContextMenu — a right-click menu, anchored at the pointer.

package/src/molecules/DocsToc.jsx

@@ -128,7 +128,7 @@ export default function DocsToc({
                * `block transition-colors focus-visible:ring-focus
                * hover:text-emphasis text-body` as utilities, so the same rung
                * rendered a different className here than in the left tree.
-               * Layout, colour, hover and focus live in `.shell-nav-item` now;
+               * Layout, color, hover and focus live in `.shell-nav-item` now;
                * active is the shared `is-active` marker, not `text-emphasis`
                * typed at one call site. Matches RailRow exactly. */
               className={`shell-nav-item kol-mono-14${activeId === item.id ? ' is-active' : ''}`}

package/src/molecules/LabeledControl.jsx

@@ -48,19 +48,22 @@ export default function LabeledControl({
     /* `'auto'`: the label is the yielding cell — flex-1, truncating — and the
      * control hugs. The control still carries min-w-0 + overflow-hidden so a
      * combo wider than the whole column CLIPS at the column edge rather than
-     * painting over the neighbour (the invariant: no cell outside its column). */
+     * painting over the neighbour (the invariant: no cell outside its column).
+     * BELOW `sm` IT STACKS (apps review, 2026-09-29): the yielding label yielded to
+     * nothing on a phone — a sentence-long combo took the whole row and the label
+     * showed as "C" or not at all. Label on its line, the value under it. */
     const labelAuto = labelWidth === 'auto'
     return (
-      <div className={`flex items-center gap-3 ${className}`}>
+      <div className={`flex ${labelAuto ? 'flex-col items-start gap-1 sm:flex-row sm:items-center sm:gap-3' : 'items-center gap-3'} ${className}`}>
         {showLabel && (
           <span
-            className={`kol-helper-10 tracking-widest text-meta ${labelAuto ? 'flex-1 min-w-0 truncate' : 'shrink-0'}`}
+            className={`kol-helper-10 tracking-widest text-meta ${labelAuto ? 'max-w-full min-w-0 truncate sm:flex-1' : 'shrink-0'}`}
             style={labelAuto ? undefined : { width: labelWidth }}
           >
             {labelInner}
           </span>
         )}
-        <div className={labelAuto ? 'min-w-0 overflow-hidden' : 'flex-1 min-w-0'}>{children}</div>
+        <div className={labelAuto ? 'min-w-0 max-w-full sm:overflow-hidden' : 'flex-1 min-w-0'}>{children}</div>
       </div>
     )
   }

package/src/molecules/MenuItem.jsx

@@ -19,6 +19,9 @@ import { PopoverPanel, usePopover } from '../utilities/Popover.jsx'
  * `Dropdown` molecule instead — MenuItem is for action menus / popovers
  * that hold arbitrary children.
  */
+/* the ladder's tokens, so the touch rung (D5, 2026-09-29) grows the trigger with its row */
+const TRIGGER_H = { xs: 'var(--kol-ctl-xs)', sm: 'var(--kol-ctl-sm)', md: 'var(--kol-ctl-md)', lg: 'var(--kol-ctl-lg)' }
+
 export function MenuItem({
   label,
   children,
@@ -33,6 +36,10 @@ export function MenuItem({
    * an affordance; neither reference draws one (ColumnBrowserMobileViews item
    * 15, kol-r2b2 2026-09-04). Default keeps every existing call-site. */
   caret = true,
+  /* THE TRIGGER IS ON THE LADDER (apps review 2026-09-29). It was a fixed `h-8` — 32px whatever sat
+   * beside it, so media's phone `···` stood 32 next to a 26 `sm` search field. `size` pins it to the
+   * control heights (01-foundations/09-sizes: 22 · 26 · 32 · 40); `md` is the 32 it always was. */
+  size = 'md',
 }) {
   const [open, setOpen] = useState(defaultOpen)
   const popover = usePopover({
@@ -51,7 +58,8 @@ export function MenuItem({
         ref={popover.refs.setReference}
         {...popover.getReferenceProps()}
         type="button"
-        className={`kol-menu-btn kol-helper-12 px-3 h-8 inline-flex items-center gap-2 rounded text-body hover:text-emphasis transition-colors ${buttonClassName}`}
+        className={`kol-menu-btn kol-helper-12 px-3 inline-flex items-center gap-2 rounded text-body hover:text-emphasis transition-colors ${buttonClassName}`}
+        style={{ height: TRIGGER_H[size] ?? TRIGGER_H.md }}
       >
         <span>{label}</span>
         {caret && (

package/src/molecules/Modal.jsx

@@ -119,7 +119,7 @@ function ModalView({ state, closeWith }) {
           />
         )}
         <div className="flex gap-2 justify-end">
-          {state.kind !== 'alert' && <Button variant="secondary" size="sm" onClick={cancel}>{state.cancelLabel ?? 'Cancel'}</Button>}
+          {state.kind !== 'alert' && <Button size="sm" onClick={cancel}>{state.cancelLabel ?? 'Cancel'}</Button>}
           <Button variant="primary"   size="sm" onClick={submit}>{state.okLabel ?? 'OK'}</Button>
         </div>
       </div>

package/src/molecules/PageHeader.jsx

@@ -1,4 +1,5 @@
 import SectionText from './SectionText.jsx'
+import { TITLE_ROLES, useMasthead } from '../utilities/masthead.js'
 /**
  * PageHeader — the page's masthead: an optional eyebrow, the title, and a
  * sub-line.
@@ -62,19 +63,25 @@ import SectionText from './SectionText.jsx'
  *                    with an `!important` on the margin — a DS text role re-implemented outside.
  * @param {string}    subtitleMaxWidth  the lede's measure (e.g. '800px' or '60ch'), a prop
  *                    instead of a consumer selector reaching inside
+ * @param {'display'|'mono'} masthead  the APP's masthead (utilities/masthead.js, 2026-09-29): inside
+ *                    a Shell it comes from `AppShell masthead` and WINS over `voice`/`size`, and
+ *                    `display` drops the subtitle — one app, one header. Outside a Shell, unset =
+ *                    the props as given, so no site page moves.
  * The bottom rhythm is `--kol-page-header-mb` (default 40px): inline, as before, but through a
  * variable a consumer can re-point where an inline literal could only be `!important`-ed.
  */
 /* the title role per size and voice — the one thing PageHeader knows that the
- * base does not, because the base's ladder is the SECTION scale */
-const TITLE = {
-  sans: { sm: 'kol-sans-heading-03', md: 'kol-sans-display-03', lg: 'kol-sans-display-02' },
-  mono: { sm: 'kol-mono-heading-03', md: 'kol-mono-display-03', lg: 'kol-mono-display-02' },
-}
+ * base does not, because the base's ladder is the SECTION scale. Lives in
+ * utilities/masthead.js since 2026-09-29 so a tool's own title reads the same table. */
+const TITLE = TITLE_ROLES
 /* the ONE thing the registers disagree about */
 const LEDE = { app: 'kol-mono-14', site: 'kol-sans-body-01' }
 
-export default function PageHeader({ eyebrow, title, subtitle, actions, subtitleMaxWidth, size = 'md', voice = 'sans', register = 'app', titleClass, className = '' }) {
+export default function PageHeader({ eyebrow, title, subtitle: ownSubtitle, actions, subtitleMaxWidth, size: ownSize = 'md', voice: ownVoice = 'sans', register = 'app', titleClass, masthead, className = '' }) {
+  const m = useMasthead(masthead)
+  const voice = m ? m.voice : ownVoice
+  const size = m ? m.size : ownSize
+  const subtitle = m && !m.subtitle ? undefined : ownSubtitle
   const roles = TITLE[voice] ?? TITLE.sans
   return (
     /* the block owns its own rhythm — margins inline, never in a shared type
@@ -83,7 +90,7 @@ export default function PageHeader({ eyebrow, title, subtitle, actions, subtitle
       eyebrow={eyebrow}
       headline={title}
       headlineAs="h1"
-      headlineClass={`text-fg-96 ${titleClass ?? roles[size] ?? roles.md}`}
+      headlineClass={`text-fg-96 ${titleClass ?? roles[size] ?? roles.md}${m?.upper ? ' uppercase' : ''}`}
       body={subtitle}
       bodyClass={`text-oq-64 ${LEDE[register] ?? LEDE.app} min-w-0`}
       actions={actions}

package/src/molecules/PaletteHarmonyWheel.jsx

@@ -43,11 +43,11 @@ import { HARMONIES, harmonyById, harmonyColors, normHue, reHueSlots } from '../h
  * @param {Array}         harmonies   injectable scheme table (default HARMONIES)
  * @param {Array}         slots       the CURRENT palette in role order (`{hex, locked}` objects or plain hex strings). Given, `colors` re-hues these — each slot keeps its own S/L, locked and empty entries pass through — instead of generating flat ones
  * @param {Function}      onChange    ({ hue, colors }) => void
- * @param {Function}      onHueChange (hue) => void — the payload-free seam, for a caller that derives its own colours
+ * @param {Function}      onHueChange (hue) => void — the payload-free seam, for a caller that derives its own colors
  */
 
 /* Marker outline — white for contrast against the fully-saturated ring hues
- * (theme-independent: the wheel's colours, not the surface, sit behind it). */
+ * (theme-independent: the wheel's colors, not the surface, sit behind it). */
 const MARKER_STROKE = '#FFFFFF'
 
 export default function PaletteHarmonyWheel({
@@ -74,9 +74,9 @@ export default function PaletteHarmonyWheel({
   /* Emit next hue + its harmony colors. Held in a ref so the pointer/key
    * handlers stay stable while always seeing the latest props.
    *
-   * With `slots`, the colours are the CALLER'S palette re-hued — each slot
+   * With `slots`, the colors are the CALLER'S palette re-hued — each slot
    * keeping its own saturation and lightness — rather than a fresh flat set.
-   * Both fire, so a caller can take the hue and ignore the colours. */
+   * Both fire, so a caller can take the hue and ignore the colors. */
   emitRef.current = (nextHue) => {
     const h = normHue(nextHue)
     const colors = slots?.length

package/src/molecules/ProfileCard.jsx

@@ -27,7 +27,7 @@ import { surfaceClass } from '../utilities/sectionSurface.js'
  * `inverse` with inverse ink, exactly as shipped. `controlVariant` goes straight
  * to the disclosure's `IconFrame`; `pad` is `ContentCard`'s — one step on
  * `--kol-pad-card-*`, overriding the size ramp's padding. The logo is a slot
- * and stays one: its ink follows the shelf, a coloured mark is the asset's.
+ * and stays one: its ink follows the shelf, a colored mark is the asset's.
  *
  * THE SHELF SIZES TO ITS CONTENT. The source held it in a fixed box
  * (`h-60`/`h-44`/`h-32`/`h-24`, `overflow-hidden`) and every vertical size

package/src/molecules/QuickLookFrame.jsx

@@ -1,6 +1,6 @@
 import { useRef, useState } from 'react'
 import Button from '../atoms/Button.jsx'
-import CloseButton from '../utilities/CloseButton.jsx'
+import CloseButton from '../atoms/CloseButton.jsx'
 
 /* taxonomy-ok: molecule — nests Button (atom) + CloseButton (utility). */
 

package/src/molecules/SearchInput.jsx

@@ -103,8 +103,9 @@ export default function SearchInput({
     if (expanding && isOpen) inputRef.current?.focus()
   }, [expanding, isOpen])
 
-  /* the pinned squares, 01-foundations/09-sizes.md — 22 · 26 · 32 · 40 */
-  const square = { sm: 28, md: 32, lg: 36 }[size] ?? 32
+  /* the pinned squares, 01-foundations/09-sizes.md — 22 · 26 · 32 · 40, read from the theme's
+   * `--kol-ctl-*` so the touch rung (D5, 2026-09-29) grows them with every other control */
+  const square = `var(--kol-ctl-${['xs', 'sm', 'md', 'lg'].includes(size) ? size : 'md'})`
   /* THE OPEN FIELD'S HEIGHT IS ITS OWN KNOB, defaulting to the square.
    *
    * /work's pill is `h-9` open AND closed, sitting level with a 36px toggle —
@@ -209,8 +210,10 @@ export default function SearchInput({
 
   /* Same height pin as Input: Chromium sizes an <input> from font metrics,
    * not CSS line-height, so without this the shell lands ~0.5px tall.
-   * h-4 / h-[18px] match the kol-mono-12 / -14 line-heights. */
-  const heightCls = size === 'sm' ? 'h-4' : 'h-[18px]'
+   * h-4 / h-[18px] match the kol-mono-12 / -14 line-heights. On TOUCH the input types 16 / 22 (the
+   * touch rung, D5 2026-09-29), and this utility out-ranked the theme's coarse rule — 16px text in a
+   * 16px line in a 26px box; `pointer-coarse:` carries the 22 so the box grows with its row. */
+  const heightCls = `${size === 'sm' ? 'h-4' : 'h-[18px]'} pointer-coarse:h-[22px]`
 
   const inputCls = [
     'min-w-0 flex-1 bg-transparent border-none outline-none text-auto',

package/src/molecules/ShellDrawer.jsx

@@ -2,7 +2,7 @@ import { useEffect, useRef, useState } from 'react'
 import { pushLayer, popLayer, isTopLayer } from '../utilities/layerStack.js'
 import { createPortal } from 'react-dom'
 import { Icon } from '@kolkrabbi/kol-icons'
-import CloseButton from '../utilities/CloseButton.jsx'
+import CloseButton from '../atoms/CloseButton.jsx'
 import usePrefersReducedMotion from '../hooks/usePrefersReducedMotion.js'
 
 /* taxonomy-ok: nests kol-icons's Icon (a package import the relative-import

package/src/molecules/SwatchControls.jsx

@@ -4,7 +4,7 @@ import ColorSwatch from '../atoms/ColorSwatch.jsx'
 import { Tooltip } from '../utilities/Popover.jsx'
 
 /*
- * SwatchControls — the Photoshop-style top row of the colour panel, in two
+ * SwatchControls — the Photoshop-style top row of the color panel, in two
  * hand-tuned pieces plus the composed row. Hand-tuned visuals (fixed pixel
  * slots, the overlap-by-DOM-order trick, the double-ring halo, the red-slash
  * "none" marker). DO NOT refactor pieces to atoms — the look is intentional
@@ -20,7 +20,7 @@ import { Tooltip } from '../utilities/Popover.jsx'
  *       No z-index, no transform — DOM order alone stacks them.
  *
  *   <EyedropPick sampleColor onPick disabled />
- *     — eyedropper icon button + a small sample chip of the sampled colour.
+ *     — eyedropper icon button + a small sample chip of the sampled color.
  *       The button is feature-gated: it is hidden entirely when the browser
  *       EyeDropper API is unavailable, and `disabled` dims it when supported
  *       but unusable. The actual EyeDropper call + canvas sampling live at the
@@ -92,7 +92,7 @@ export function SwatchStack({
 }
 
 /**
- * EyedropPick — eyedropper icon button + a sample chip of the sampled colour.
+ * EyedropPick — eyedropper icon button + a sample chip of the sampled color.
  * The button is hidden when the browser EyeDropper API is unavailable (no
  * affordance for an action that can't run); when supported but unusable pass
  * `disabled` to dim it. `onPick` is the app seam where EyeDropper + canvas

package/src/molecules/TabsRow.jsx

@@ -1,5 +1,5 @@
 import { useRef } from 'react'
-import CloseButton from '../utilities/CloseButton.jsx'
+import CloseButton from '../atoms/CloseButton.jsx'
 import { Icon } from '@kolkrabbi/kol-icons'
 
 /* taxonomy-ok: nests kol-icons's Icon */

package/src/organisms/Canvas.jsx

@@ -93,7 +93,7 @@ export function CanvasFrame({
   const { ratio, label } = resolveAspect(aspect, customRatio, aspects)
   /* NO guideColor → THEME INK (editor DS sync 2026-09-27, from the design editor's copy, which had
    * it and this lift had not): the border and label follow the theme, so the frame reads on a light
-   * page and a dark one. A guideColor (a type frame's own colour) still tints both. */
+   * page and a dark one. A guideColor (a type frame's own color) still tints both. */
   const borderColor = guideColor ? `color-mix(in srgb, ${guideColor} 24%, transparent)` : 'var(--kol-oq-24)'
   const labelColor = guideColor ? `color-mix(in srgb, ${guideColor} 70%, transparent)` : 'var(--kol-fg-64)'
   const virtualH = CANVAS_VIRTUAL_W / ratio

package/src/organisms/ContentFilters.jsx

@@ -7,6 +7,7 @@ import { glyphSize } from '../hooks/glyphLadders.js'
 import SearchInput from '../molecules/SearchInput.jsx'
 import IconFrame from '../atoms/IconFrame.jsx'
 import { Tooltip } from '../utilities/Popover.jsx'
+import { filterItems } from '../utilities/searchItems.js'
 
 /**
  * ContentFilters — universal filter component for content grids.
@@ -214,16 +215,8 @@ const ContentFilters = ({
   }
 
   const filteredItems = useMemo(() => {
-    let result = items
-    if (searchText) {
-      const q = searchText.toLowerCase()
-      result = result.filter((item) =>
-        searchKeys.some((key) => {
-          const val = item[key]
-          return val && String(val).toLowerCase().includes(q)
-        }),
-      )
-    }
+    /* the KOL engine, not a private substring match (apps review 2026-09-29) — utilities/searchItems */
+    let result = filterItems(items, searchText, { keys: searchKeys })
     if (activeFilters.size === 0) return result
     return result.filter((item) => {
       let matches = true
@@ -402,7 +395,7 @@ const ContentFilters = ({
               * 05-control-chrome.md:109 — "any icon-only control in chrome is
               * IconFrame; nothing hand-writes the square". This wore
               * `kol-btn-md kol-btn-icon` and then removed the background, the
-              * border and the colour by inline style, which is the whole button
+              * border and the color by inline style, which is the whole button
               * paid for and thrown away — and it left the control with no
               * states at all while the search beside it had hover.
               *