@kolkrabbi/kol-component 0.233.0 → 0.235.0

package/src/organisms/Canvas.jsx

@@ -419,7 +419,7 @@ function isTypingTarget(el) {
 }
 
 /**
- * PanZoomViewport — infinite-canvas viewport (pan + zoom), and the one that
+ * PanZoomViewport — An infinite canvas to pan and zoom. infinite-canvas viewport (pan + zoom), and the one that
  * publishes `CanvasZoomContext`.
  *
  * Pan: hold Space + drag (cursor grab/grabbing), or two-finger trackpad
@@ -787,7 +787,7 @@ export function useFrameGeom(containerRef, virtualWidth = CANVAS_VIRTUAL_W) {
 }
 
 /**
- * CanvasRuler — top + left rulers in virtual-canvas px, mapped through the
+ * CanvasRuler — Rulers along the canvas edges. top + left rulers in virtual-canvas px, mapped through the
  * measured frame geometry (see useFrameGeom).
  *
  * Dragging off a ruler starts a new guide: the ruler only ANNOUNCES the
@@ -900,7 +900,7 @@ function GuideLine({ axis, screenPos, interactive, onGrab }) {
 }
 
 /**
- * CanvasGuides — ruler guides rendered at the viewport level so each line
+ * CanvasGuides — Guide lines across the whole canvas. ruler guides rendered at the viewport level so each line
  * spans the entire visible canvas area instead of clipping to the letterbox
  * frame. Positions are stored in virtual canvas px and threaded down as props
  * — the viewport is chrome and owns no guide state; the screen mapping is the

package/src/organisms/ColumnBrowser.jsx

@@ -12,7 +12,7 @@ import useMarquee from '../hooks/useMarquee.js'
 import { GRAB_COLUMN } from '../utilities/motion.js'
 
 /**
- * ColumnBrowser — Finder-style Miller columns over a flat key space (kol-r2b2's
+ * ColumnBrowser — Finder-style columns over a bucket. Finder-style Miller columns over a flat key space (kol-r2b2's
  * `src/ColumnBrowser.jsx`, built and ruled there first — user 2026-08-27: "make
  * it locally first, then ship it" — and shipped verbatim; ticket ColumnBrowser).
  * The listing surface's FOLDER view: it replaces the folder rows above the

package/src/organisms/ContentCollection.jsx

@@ -1,7 +1,7 @@
 import usePrefersReducedMotion from '../hooks/usePrefersReducedMotion.js'
 
 /**
- * ContentCollection — the container half of the content-card system: the
+ * ContentCollection — A grid or list of content items. the container half of the content-card system: the
  * grid/list switch plus the motion that belongs to it. Animation lives in
  * the wrapper — the only place it can (06-content-card-system.md §6);
  * cards never animate themselves.

package/src/organisms/CurveEditor.jsx

@@ -109,7 +109,7 @@ function TermRow({ term, onSet, onRemove, canRemove }) {
 }
 
 /**
- * CurveEditor — curve authoring: a kind picker, per-kind ranges and
+ * CurveEditor — Author a curve by kind and expression. curve authoring: a kind picker, per-kind ranges and
  * EXPRESSION fields, and the epicycle term list.
  *
  * Lifted from kol-fxr's editor (`compose/inspectors/CurveEditor.jsx`,

package/src/organisms/DocumentEditor.jsx

@@ -11,7 +11,7 @@ import { splitFrontmatter, joinFrontmatter } from '@kolkrabbi/kol-markdown'
 import { readDraft, writeDraft, clearDraft } from '../utilities/localDrafts.js'
 
 /**
- * DocumentEditor — write a text file: open one, or make a new one (media D1 plan v2, 2026-09-26).
+ * DocumentEditor — Open or write a text file. write a text file: open one, or make a new one (media D1 plan v2, 2026-09-26).
  *
  * The concept is kol-olina's brand notes page (NoteEdit): a title, a markdown body, Write / Preview,
  * attachments from the bucket, a page for writing something NEW rather than a button hidden in a

package/src/organisms/FeaturedCarousel.jsx

@@ -85,7 +85,7 @@ function SlideMedia({ media, active = true, onEnded, onTimeUpdate }) {
  * the one hero (SectionHeroRound2); this stays as its engine and renders
  * unchanged. Removed from the barrel at the next major.
  *
- * FeaturedCarousel — a full-width carousel of featured media: each wide slide
+ * FeaturedCarousel — A full-width carousel of featured media. a full-width carousel of featured media: each wide slide
  * is a fixed-height frame with an image or HLS-video background and a centered
  * OverlayGlassPanel (title / description / CTA), plus prev/next and optional
  * autoplay with a progress bar.

package/src/organisms/FramedMediaBand.jsx

@@ -1,7 +1,7 @@
 import Image from '../atoms/Image'
 
 /**
- * FramedMediaBand — full-width media breather band: a centered, aspect-locked
+ * FramedMediaBand — A full-width band with one framed image. full-width media breather band: a centered, aspect-locked
  * frame (bordered surface-secondary panel, rounded) holding one object-cover
  * image. Extracted from the foundry TypefacePage, where it sat inlined 5x
  * verbatim between content sections. The double radius (`rounded` panel,

package/src/organisms/GalleryCarousel.jsx

@@ -9,7 +9,7 @@ import MediaViewer from './MediaViewer.jsx'
 const DRAG_THRESHOLD_SQ = 25
 
 /**
- * GalleryCarousel — the project-detail media gallery: a horizontal, drag-scroll
+ * GalleryCarousel — A shelf of media that opens fullscreen. the project-detail media gallery: a horizontal, drag-scroll
  * shelf of image/video tiles where clicking a tile opens THE shared fullscreen
  * MediaViewer starting at that tile.
  *

package/src/organisms/KeyframeEditor.jsx

@@ -22,7 +22,7 @@ export const DEFAULT_KEYFRAMES = [
 ]
 
 /**
- * KeyframeEditor — a keyframe list over a pose track, kept sorted by `t`.
+ * KeyframeEditor — A sorted list of keyframes. a keyframe list over a pose track, kept sorted by `t`.
  *
  *   { t: 0..1, rot: [x, y, z] RADIANS, pos: [x, y, z], scale, ease }
  *

package/src/organisms/LayerStack.jsx

@@ -207,7 +207,7 @@ function CanvasRow({ IconC, active, collapsed, onToggleCollapse, onSelect }) {
 }
 
 /**
- * LayerStack — the layers panel: a z-stacked tree of rows with HTML5 drag to
+ * LayerStack — The layers panel. the layers panel: a z-stacked tree of rows with HTML5 drag to
  * reorder AND reparent in one gesture, hover-revealed eye + lock toggles,
  * inline rename, collapsible containers, and a Canvas root row above it all.
  *
@@ -440,7 +440,7 @@ export default function LayerStack({
 }
 
 /**
- * AddLayerButton — the `+` that opens a menu of layer types. Lives in the
+ * AddLayerButton — Add a layer from a menu. the `+` that opens a menu of layer types. Lives in the
  * panel's tab row, not the stack footer (the source's placement). One entry
  * may expand inline to a kind picker so adding "a shape" doesn't silently
  * default to the first kind.

package/src/organisms/MediaLibrary.jsx

@@ -19,7 +19,7 @@ import { SettingsChipRow, chipCls } from './SettingsPanel.jsx'
 import { filterMedia } from '../utilities/mediaSearch.js'
 
 /**
- * MediaLibrary — a browser over an object bucket, in two views over one
+ * MediaLibrary — Browse and pick files from a bucket. a browser over an object bucket, in two views over one
  * headless core. Consolidates four consumer forks (kol-ds-fxr, kol-labs-single,
  * kol-client-kolkrabbi, kol-website/brand — 9 files, ~1542 lines) that had
  * already diverged: only fxr carried the canvas-taint fix, only labs carried
@@ -263,7 +263,7 @@ function sortFiles(files, { by, dir }) {
 }
 
 /**
- * MediaLibraryProvider — the headless core: one list call, then a
+ * MediaLibraryProvider — The data core behind the media views. the headless core: one list call, then a
  * PREFIX-SCOPED view over it: the folders directly under the prefix, the
  * files at that level (or the whole subtree in `flat`), the kind allow-list,
  * the search, the sort with direction, and paging.

package/src/organisms/MediaLibraryExplorer.jsx

@@ -4,7 +4,7 @@ import { useModal } from '../molecules/Modal.jsx'
 import useMediaQuery from '../hooks/useMediaQuery.js'
 
 /**
- * MediaLibraryExplorer — the media surface, and since 2026-09-22 a thin name for it.
+ * MediaLibraryExplorer — The media browser. the media surface, and since 2026-09-22 a thin name for it.
  *
  * IT USED TO BE THE MERGE ITSELF: it held a BROWSE · FILES switch and mounted one of two pages,
  * each of which listed the bucket, drew its own header and printed its own count. The user's read

package/src/organisms/MediaLibraryPages.jsx

@@ -596,7 +596,7 @@ function FileEditorHost({ o, client, bucket, onClose, onSaved, assets }) {
 }
 
 /**
- * MediaInspector — the full-screen viewer for one file in a set: image, video
+ * MediaInspector — View one file at full size. the full-screen viewer for one file in a set: image, video
  * (scrubbable, audio on), audio, or a document page, in one `QuickLookFrame`, with
  * prev / next fixed at the viewport edges.
  *

package/src/organisms/MediaTileGallery.jsx

@@ -2,7 +2,7 @@ import { useState } from 'react'
 import MediaViewer from './MediaViewer.jsx'
 
 /**
- * MediaTileGallery — a stack or grid of framed media tiles that open THE
+ * MediaTileGallery — Media tiles that open a fullscreen viewer. a stack or grid of framed media tiles that open THE
  * shared fullscreen MediaViewer at the clicked tile, paged across all items
  * (the monorepo's FullscreenGallery recreated on the shared viewer instead of
  * its nav-less single image; the AssetFigure/AssetGrid deps are dropped —

package/src/organisms/RecordManager.jsx

@@ -35,7 +35,7 @@ const ToolbarIcon = ({ name, label, onClick, active = false, triggerClassName })
 )
 
 /**
- * RecordManager — full-screen CMS record surface (lobby: RecordManager,
+ * RecordManager — A full-screen CMS record editor. full-screen CMS record surface (lobby: RecordManager,
  * reference: Framer CMS). A reorderable record table plus a slide-over detail
  * panel of FieldRows.
  *

package/src/organisms/SectionCards.jsx

@@ -6,7 +6,7 @@ import useSectionTheme from '../hooks/useSectionTheme.js'
 import { minHeightClass } from './sectionHeights.js'
 
 /**
- * SectionCards — the "N-up feature cards" band: a `SectionText` header over a
+ * SectionCards — A header over a row of feature cards. the "N-up feature cards" band: a `SectionText` header over a
  * responsive row of `SectionCardItem` cards, capped by an optional centred
  * action row. `FeaturesCardSection` is this component under its old name and
  * prop names (`headerLabel` → `headline`, `headerDescription` → `body`,

package/src/organisms/SectionCta.jsx

@@ -5,7 +5,7 @@ import SectionText from '../molecules/SectionText.jsx'
 import { minHeightClass } from './sectionHeights.js'
 
 /**
- * SectionCta — the editorial two-column contact/CTA band: a large display
+ * SectionCta — A closing call-to-action band. the editorial two-column contact/CTA band: a large display
  * wordmark on the left (e.g. "/ CONNECT") and a right column of stacked
  * label-over-value rows, each a `SectionText` (label in the helper voice,
  * value as a heading-01; a row with `href` renders its value as a link).

package/src/organisms/SectionFaq.jsx

@@ -6,7 +6,7 @@ import SectionText from '../molecules/SectionText.jsx'
 import { minHeightClass } from './sectionHeights.js'
 
 /**
- * SectionFaq — a `SectionText` header over an `Accordion` of question /
+ * SectionFaq — Questions and answers in an accordion. a `SectionText` header over an `Accordion` of question /
  * answer items. The one NEW surface in the section family (SectionSet,
  * 2026-08-26) — the behaviour already shipped in the Accordion molecule; this
  * is the section around it.

package/src/organisms/SectionHero.jsx

@@ -85,7 +85,7 @@ function MediaLayer({ media }) {
 }
 
 /**
- * SectionHero — the full-bleed media hero: cover-fit background media (image
+ * SectionHero — Full-bleed media hero with a glass panel. the full-bleed media hero: cover-fit background media (image
  * or video) filling a fixed-height section, an optional surface scrim, and
  * the text in a glass panel over it. `FullBleedHero` is this component under
  * its old name (alias kept).

package/src/organisms/SectionNewsletter.jsx

@@ -8,7 +8,7 @@ import useSectionTheme from '../hooks/useSectionTheme.js'
 import { minHeightClass } from './sectionHeights.js'
 
 /**
- * SectionNewsletter — the newsletter card of the section family
+ * SectionNewsletter — A newsletter signup card. the newsletter card of the section family
  * (SectionNewsletter, kol-website 2026-08-27 — user: the newsletter as a card
  * in the family, same ladder, same cap, content centred on y, not its own
  * thing). `SectionText` (label · headline · body, centred) with the email

package/src/organisms/SectionSplit.jsx

@@ -6,7 +6,7 @@ import useSectionTheme from '../hooks/useSectionTheme.js'
 import { minHeightClass } from './sectionHeights.js'
 
 /**
- * SectionSplit — the media-and-text split section, on `SectionText` (the
+ * SectionSplit — Text beside media. the media-and-text split section, on `SectionText` (the
  * text column) beside the media frame. Two columns at/above 901px, one
  * stacked column below. `FeatureSplit` is this component under its old name
  * and old prop names (kept as an alias — see FeatureSplit.jsx).

package/src/organisms/SettingsPanel.jsx

@@ -9,7 +9,7 @@ import FullscreenOverlay from '../utilities/FullscreenOverlay.jsx'
 import { Tooltip } from '../utilities/Popover.jsx'
 
 /**
- * SettingsPanel — a settings surface for the thing you are looking at: you
+ * SettingsPanel — Settings beside the thing they change. a settings surface for the thing you are looking at: you
  * change how a list looks WHILE looking at it, so it is a slide-over (or an
  * overlay), never a route (SettingsPanel, kol-r2b2 2026-08-26 — the
  * per-bucket display settings: kinds allow-list, structure, loading, layout).
@@ -107,7 +107,7 @@ export default function SettingsPanel({
 }
 
 /**
- * SettingsRow — a `LabeledControl inline` (SettingsPanelApproved, 2026-08-27):
+ * SettingsRow — One labelled setting. a `LabeledControl inline` (SettingsPanelApproved, 2026-08-27):
  * uppercase label (`kol-helper-10` tracked, meta ink) in a 160px column, the
  * control fills the rest. A switch sits at the far right (`align="end"`, the
  * default); a dropdown fills the row (`align="fill"`). No hint sentences on the
@@ -127,7 +127,7 @@ export function SettingsRow({ label, hint, align = 'end', labelWidth = 160, chil
   )
 }
 
-/** SettingsSwitch — the row's on/off control: the DS ToggleSwitch, bare, sm.
+/** SettingsSwitch — An on/off setting. the row's on/off control: the DS ToggleSwitch, bare, sm.
  *  `disabledHint` rides a DS `Tooltip` so a switch that cannot act says why;
  *  inside a row's `hint` it wins while hovered, as the native `title` did. */
 export function SettingsSwitch({ on = false, onChange, disabled = false, disabledHint, label, title }) {
@@ -144,7 +144,7 @@ export function SettingsSwitch({ on = false, onChange, disabled = false, disable
   return tip ? <Tooltip label={tip}>{toggle}</Tooltip> : toggle
 }
 
-/** LabeledControlSection — a section of LabeledControls: the EYEBROW
+/** LabeledControlSection — A titled section of labelled controls. a section of LabeledControls: the EYEBROW
  *  (`kol-eyebrow text-fg-80`) standing apart from the rows (gap-3), the rows in
  *  their own stack — `rowGap` 1 for switch rows (24 tall already), 2 for
  *  dropdown rows. `divided` = a hairline above (between sections).
@@ -161,7 +161,7 @@ export function LabeledControlSection({ label, divided = false, rowGap = 2, chil
   )
 }
 
-/** SettingsChoice — the row's one-of-N control: the DS Dropdown, sm · primary
+/** SettingsChoice — A one-of-many setting. the row's one-of-N control: the DS Dropdown, sm · primary
  *  (SettingsPanelEyebrowAndDropdowns — user: "put the toggles inside a dropdown,
  *  because it's super messy like it is"). Options are values or `{ value, label }`;
  *  width is the call site's (`className="w-40"`).
@@ -189,7 +189,7 @@ export const CHIP_CLS = 'kol-control kol-control-sm kol-mono-12'
 export const chipCls = (on) => `${CHIP_CLS} ${on ? 'kol-control--filled' : 'text-meta hover:text-emphasis'}`
 
 /**
- * SettingsMulti — a many-of-N control as ONE Dropdown (SettingsPanelApproved,
+ * SettingsMulti — A many-of-many setting in one dropdown. a many-of-N control as ONE Dropdown (SettingsPanelApproved,
  * 2026-08-27 — the kinds row): the trigger reads `N of M <noun>`, every entry
  * toggles and `✓` marks the ones that are on. No grouping.
  * @param {Array}  options   [{ value, label }]
@@ -210,7 +210,7 @@ export function SettingsMulti({ options = [], selected = [], onToggle, noun = 'k
 }
 
 /**
- * SettingsChipRow — a wrap of toggle chips with optional counts (an
+ * SettingsChipRow — A row of toggle chips. a wrap of toggle chips with optional counts (an
  * allow-list: every chip sets a default, never a gate). `allChip` puts an
  * "all" chip first — the same control chip, filled when every option is on
  * (SettingsPanelEyebrowAndDropdowns — user: "Show all in ghost mode? makes no
@@ -247,7 +247,7 @@ export function SettingsChipRow({ options = [], selected = [], onToggle, allChip
   )
 }
 
-/** SettingsFooter — a Divider, then one `IconFrame refresh` (primary · sm) at the
+/** SettingsFooter — Reset settings to their defaults. a Divider, then one `IconFrame refresh` (primary · sm) at the
  *  right = reset to defaults (SettingsPanelApproved, 2026-08-27). No status word,
  *  no text button. `customised` is accepted for compatibility and unused.
  *

package/src/organisms/ShellSearchOverlay.jsx

@@ -59,7 +59,7 @@ export function HighlightMatch({ label, query, ranges }) {
 }
 
 /**
- * ShellSearchOverlay — the ⌘K command palette: fullscreen dim + centered
+ * ShellSearchOverlay — The ⌘K search palette. the ⌘K command palette: fullscreen dim + centered
  * panel, a bare SearchInput on top, result rows beneath (HighlightMatch
  * label, dim hint line, right-aligned group label). Distinct from Modal
  * (prompt/confirm only) — this is the search/command primitive.
@@ -69,7 +69,7 @@ export function HighlightMatch({ label, query, ranges }) {
  * The ⌘K binding itself lives in the shell's key handler, not here.
  *
  * Keyboard: ArrowUp/ArrowDown rove the active row (mouse hover roves too),
- * Enter selects it (index starts at 0 → Enter-selects-first preserved),
+ * Enter opens it (the top row from the first keystroke), ⌘/Ctrl+Enter opens every hit,
  * Escape closes. Focus trap: focus moves into the input on open, returns to
  * the opener on close, and Tab is pinned — rows are combobox options driven
  * via aria-activedescendant, never tab stops.
@@ -168,13 +168,12 @@ export default function ShellSearchOverlay({
       /* ⌘ENTER OPENS EVERY HIT (user 2026-09-30: *"enter would focus searched item, and maybe
        * command enter would open the results page"*) — only where the consumer has a place for them. */
       if ((e.metaKey || e.ctrlKey) && onOpenResults && query) { onOpenResults(query); onClose?.(); return }
-      /* Enter COMMITS the query and expands. It only selects when the user has
-       * actually arrowed to a row — `activeIndex` starts at 0, so "a row is
-       * highlighted" is true from the first keystroke and testing `active >= 0`
-       * made Enter navigate to whatever happened to be first. Committing a
-       * query must never be a navigation you didn't choose. */
-      /* An empty query has nothing to commit — Enter goes to the top suggestion. */
-      if (active >= 0 && (navigated || !query)) select(results[active])
+      /* ENTER OPENS THE HIGHLIGHTED ROW (user 2026-10-01: *"I think enter should also take you to
+       * the atom but something like command enter take you to the index"* — reverses the
+       * 2026-08-01 "Enter commits, it only selects once you have arrowed"). The top row is drawn
+       * highlighted from the first keystroke, so Enter goes where the highlight says. With no
+       * rows there is nothing to open and Enter commits the query. */
+      if (active >= 0) select(results[active])
       else onExpand?.()
     } else if (e.key === 'Tab') {
       /* Focus trap — the input is the palette's only tab stop. */
@@ -283,17 +282,28 @@ export default function ShellSearchOverlay({
           </ul>
         )}
         {/* THE FOOTER SAYS WHAT ENTER DOES — always, not only once typing. */}
-        {!expanded && ((!query && results.length > 0) || (query && enterLabel)) && (
+        {!expanded && (results.length > 0 || (query && (enterLabel || onOpenResults))) && (
           <div className="border-t border-fg-08 py-2">
-            <p className="flex items-center gap-2 kol-helper-12 text-fg-48 mx-2 px-4 border-x border-transparent">
-              <Kbd icon="corner-down-left" />
-              {query ? enterLabel : 'Go to page'}
-            </p>
+            {/* Enter's line names what Enter does NOW: a row is highlighted → it opens that row;
+              * no rows → it commits the query. */}
+            {(results.length > 0 || enterLabel) && (
+              <p className="flex items-center gap-2 kol-helper-12 text-fg-48 mx-2 px-4 border-x border-transparent">
+                <Kbd icon="corner-down-left" />
+                {results.length > 0 ? 'Go to page' : enterLabel}
+              </p>
+            )}
+            {/* THE RESULTS LINE IS A LINK (user 2026-10-01: *"make 'all results...' at the bottom
+              * also be a link to the results page"*) — the same door ⌘Enter opens. */}
             {query && onOpenResults && (
-              <p className="flex items-center gap-2 kol-helper-12 text-fg-48 mx-2 px-4 border-x border-transparent pt-1">
+              <button
+                type="button"
+                className="flex items-center gap-2 kol-helper-12 text-fg-48 hover:text-fg-default transition-colors mx-2 px-4 border-x border-transparent pt-1"
+                onMouseDown={(e) => e.preventDefault()}
+                onClick={() => { onOpenResults(query); onClose?.() }}
+              >
                 <Kbd icon="command"><Icon name="corner-down-left" size={12} /></Kbd>
                 {resultsLabel}
-              </p>
+              </button>
             )}
           </div>
         )}

package/src/organisms/ShortcutsOverlay.jsx

@@ -2,7 +2,7 @@ import { useEffect } from 'react'
 import SettingsSections from './SettingsSections.jsx'
 
 /**
- * ShortcutsOverlay — the keyboard-shortcut sheet: blurred scrim, centred
+ * ShortcutsOverlay — The keyboard shortcut sheet. the keyboard-shortcut sheet: blurred scrim, centred
  * panel, a 2-col grid (label · keys), Esc / backdrop-click close.
  * Ported from the shared cut (mirror's, "copied from kol-monitor").
  *

package/src/organisms/SpectrumControls.jsx

@@ -41,7 +41,7 @@ const HUE_GRADIENT =
   'linear-gradient(to right, hsl(0,100%,50%), hsl(60,100%,50%), hsl(120,100%,50%), hsl(180,100%,50%), hsl(240,100%,50%), hsl(300,100%,50%), hsl(360,100%,50%))'
 
 /**
- * HueStrip — 1D hue slider: a rainbow bar with a draggable knob. Pointer
+ * HueStrip — A hue slider. 1D hue slider: a rainbow bar with a draggable knob. Pointer
  * drag anywhere on the strip; focus + Left/Right (or Down/Up) arrow keys
  * nudge hue by 1° (role="slider").
  *
@@ -116,7 +116,7 @@ export function HueStrip({ hue, onChange }) {
 }
 
 /**
- * SBSquare — 2D saturation/value picker: white→hue horizontal gradient with
+ * SBSquare — Pick saturation and value on a square. 2D saturation/value picker: white→hue horizontal gradient with
  * a black overlay fading upward, crosshair handle. Fills its container
  * (consumer owns the size — and the rounding: apply `rounded-[var(--kol-radius-xs)]
  * overflow-hidden` on the wrapper). Focus + arrow keys nudge: Left/Right =
@@ -233,7 +233,7 @@ function vertexAt(angleRad) {
 }
 
 /**
- * WheelTriangle — HSV color wheel: conic hue ring with an inscribed,
+ * WheelTriangle — A hue wheel with a value triangle. HSV color wheel: conic hue ring with an inscribed,
  * rotating HSV triangle for saturation/value. Ring press snaps hue to the
  * cursor angle and drags; triangle press grabs the SV handle with a
  * cursor↔handle offset so fine tuning never teleports it. Focus + arrow
@@ -478,7 +478,7 @@ function SvgHandle({ cx, cy, r = 2.4 }) {
 }
 
 /**
- * SpectrumControls — the composed classic square picker: HueStrip stacked
+ * SpectrumControls — A hue strip over a saturation square. The composed classic square picker: HueStrip stacked
  * over a fill-height SBSquare, per the source color panel's Hue mode layout
  * (SBSquare wrapped in `rounded-[var(--kol-radius-xs)] overflow-hidden`, see its comment).
  * Fills its container — the consumer owns the outer size. For the ring

package/src/organisms/SpectrumGrid.jsx

@@ -4,7 +4,7 @@ import { resolveCssVar, resolveCssColor, isLight } from '../hooks/cssVar.js'
 import { Tooltip } from '../utilities/Popover.jsx'
 
 /**
- * SpectrumGrid — matrix view of the whole ramp system: rows = ramps, columns =
+ * SpectrumGrid — Every ramp by every stop. matrix view of the whole ramp system: rows = ramps, columns =
  * stops (50 → 900). Each cell is a ColorSwatch tile with the stop number and
  * hex printed over it (text color contrast-corrected via isLight), so the whole
  * palette is scannable in one grid.

package/src/organisms/Table.jsx

@@ -33,7 +33,7 @@ const WIDTHS = {
   column: '',
 }
 
-const Table = ({ caption, columns, rows, variant = 'default', className = '', width = 'panel', rowClassName, compact = false }) => {
+const Table = ({ caption, columns, rows, variant = 'default', className = '', width = 'panel', rowClassName, compact = false, lastRule = false }) => {
   const [sort, setSort] = useState({ key: null, dir: null })
 
   const cycle = (key) =>
@@ -58,7 +58,9 @@ const Table = ({ caption, columns, rows, variant = 'default', className = '', wi
   const variantClass = variant === 'simple' ? 'kol-table--simple' : ''
   /* compact — record-surface density (RecordManager, 2026-08-09): the default
    * 12/16 cell box read as bloated rows against the reference table. */
-  const wrapperClass = ['kol-table-wrapper', variantClass, compact && 'kol-table--compact', WIDTHS[width] ?? WIDTHS.panel, className].filter(Boolean).join(' ')
+  /* lastRule — `simple` only: the rule under the LAST row. Off by default (2026-10-01): the
+   * table is usually followed by a divider of its own, and the two read as a double line. */
+  const wrapperClass = ['kol-table-wrapper', variantClass, lastRule && 'kol-table--last-rule', compact && 'kol-table--compact', WIDTHS[width] ?? WIDTHS.panel, className].filter(Boolean).join(' ')
   return (
   <div className={wrapperClass}>
     <table className="kol-table">

package/src/organisms/ToolPalette.jsx

@@ -5,7 +5,7 @@ import SplitToolButton from '../molecules/SplitToolButton.jsx'
 import { Tooltip } from '../utilities/Popover.jsx'
 
 /**
- * ToolPalette — the editor's tool bar as one row (kol-fxr `shell/panels/ToolPalette.jsx`,
+ * ToolPalette — The editor's tool bar. the editor's tool bar as one row (kol-fxr `shell/panels/ToolPalette.jsx`,
  * editor-panels-the-held-specs A3, 2026-09-25). Four kinds of cell, all on one pinned-square rung:
  *
  * - `tool` — arms a mode; lit while `activeId` is its id

package/src/utilities/AsciiCursor.jsx

@@ -495,7 +495,7 @@ function AsciiCursorOverlay({ hideCursor }) {
 }
 
 /**
- * AsciiCursor — full-viewport decorative overlay that shadows the pointer
+ * AsciiCursor — An ASCII crosshair that follows the pointer. full-viewport decorative overlay that shadows the pointer
  * with an ASCII crosshair (diamond variant over interactive elements) and
  * layers ambient effects on top of the page: drifting cursor stars,
  * click-triggered ASCII fireworks, and a right-click Space Invader that

package/src/utilities/AssetGrid.jsx

@@ -1,5 +1,5 @@
 /**
- * AssetGrid — thin responsive N-column grid for tiling asset figures
+ * AssetGrid — A responsive grid for asset figures. thin responsive N-column grid for tiling asset figures
  * (swatches, placeholders, spec cards). Fixed 2/3/4-column layout that
  * collapses to 2 columns under the md breakpoint and to 1 column under
  * 480px, all via Tailwind responsive utilities — no CSS of its own.

package/src/utilities/ButtonGroup.jsx

@@ -1,5 +1,5 @@
 /**
- * ButtonGroup — responsive layout wrapper for a group of Buttons: stacked
+ * ButtonGroup — Lay out a group of buttons. responsive layout wrapper for a group of Buttons: stacked
  * full-width on mobile, horizontal row from `sm` up, aligned left / center /
  * right. Pure layout — children compose at the call site and render as-is
  * (nothing is cloned, no props injected); all button behavior lives on each

package/src/utilities/CropOverlay.jsx

@@ -2,7 +2,7 @@ import { useContext, useEffect, useState } from 'react'
 import { CanvasZoomContext } from '../hooks/canvasZoom.js'
 
 /**
- * CropOverlay — crop-mode chrome for a photo layer with an explicit crop
+ * CropOverlay — Crop handles over a photo layer. crop-mode chrome for a photo layer with an explicit crop
  * window ({imgX,imgY,imgW,imgH} — the image's draw rect in frame-local px).
  *
  *   • drag inside the frame  → pan the image within the frame (clamped)

package/src/utilities/CurveOverlay.jsx

@@ -81,7 +81,7 @@ function Handle({ cx, cy, role }) {
 }
 
 /**
- * CurveOverlay — SVG easing/curve visualizer laid absolutely over a frame:
+ * CurveOverlay — An easing curve drawn over a frame. SVG easing/curve visualizer laid absolutely over a frame:
  * a dashed accent curve with endpoint dots, and — in `curve="custom"`
  * mode — a two-handle cubic-bezier editor (Figma/After-Effects style)
  * with tangent lines back to the anchored endpoints.

package/src/utilities/ErrorBoundary.jsx

@@ -2,7 +2,7 @@ import { Component } from 'react'
 import Button from '../atoms/Button.jsx'
 
 /**
- * ErrorBoundary — class error boundary (boundaries can't be hooks). Catches
+ * ErrorBoundary — Catches a crash and shows a fallback. class error boundary (boundaries can't be hooks). Catches
  * render errors in its subtree and swaps in a centered full-screen fallback
  * ("Something went wrong") with two recovery actions: retry in place and go
  * home. A dev-only error/stack panel renders on Vite dev builds

package/src/utilities/ExitPreview.jsx

@@ -1,5 +1,5 @@
 /**
- * ExitPreview — the escape hatch out of a preview surface, worn as a fixed
+ * ExitPreview — A pill to leave a preview. the escape hatch out of a preview surface, worn as a fixed
  * pill. Router-AGNOSTIC by the same seam kol-shell uses for navigation: it
  * renders a plain `<a>` unless the consumer hands it its router's link.
  *

package/src/utilities/FullscreenOverlay.jsx

@@ -3,7 +3,7 @@ import { pushLayer, popLayer, isTopLayer } from './layerStack.js'
 import CloseButton from '../atoms/CloseButton.jsx'
 
 /**
- * FullscreenOverlay — the scrim + centred sheet every overlay in the repo
+ * FullscreenOverlay — The scrim and sheet every overlay wears. the scrim + centred sheet every overlay in the repo
  * wears. Owns dismissal (Escape, backdrop, close button), scroll lock and
  * stacking; the consumer supplies the panel.
  *

package/src/utilities/OverlayGlassPanel.jsx

@@ -1,5 +1,5 @@
 /**
- * OverlayGlassPanel — the KOL frosted-glass content card that floats over
+ * OverlayGlassPanel — A frosted panel over media. the KOL frosted-glass content card that floats over
  * hero/carousel media: translucent surface-primary (color-mix) + a 1px
  * backdrop blur, children stacked vertically. Extracted from 4 identical
  * inline copies in the monorepo (StudioHero, StudioAboutCard,

package/src/utilities/Popover.jsx

@@ -240,7 +240,7 @@ function TooltipOn({
 }
 
 /**
- * PopoverPanel — renders the floater into a portal with default panel chrome.
+ * PopoverPanel — A floating panel in a portal. renders the floater into a portal with default panel chrome.
  *
  * Props:
  *   popover         — the value returned from `usePopover`

package/src/utilities/ProsePreview.jsx

@@ -1,5 +1,5 @@
 /**
- * ProsePreview — a full rich-text specimen: one `.kol-prose` block exercising
+ * ProsePreview — Every long-form prose element in one view. a full rich-text specimen: one `.kol-prose` block exercising
  * every long-form element — H1–H4 ladder, section lede, body paragraph,
  * blockquote, indented passage, code block, pullout, and unordered/ordered
  * lists — so the KOL prose stylesheet can be reviewed end-to-end in one view.

package/src/utilities/TiltCard.jsx

@@ -4,7 +4,7 @@ import usePrefersReducedMotion from '../hooks/usePrefersReducedMotion.js'
 import useCoarsePointer from '../hooks/useCoarsePointer.js'
 
 /**
- * TiltCard — self-contained image card with a spring-based 3D tilt that
+ * TiltCard — An image card that tilts toward the pointer. self-contained image card with a spring-based 3D tilt that
  * follows the pointer (via the shared useTilt hook). On coarse-pointer
  * devices or when the user prefers reduced motion it renders a plain,
  * tilt-free card — no springs, no listeners.

package/src/utilities/TransparentX.jsx

@@ -1,5 +1,5 @@
 /**
- * TransparentX — diagonal stroke indicator for transparent / disabled / unused
+ * TransparentX — A slash marking an empty slot. diagonal stroke indicator for transparent / disabled / unused
  * slots. Universal "no value" affordance.
  *
  * Renders absolute-positioned to fill its parent. Parent must be `position: