@lotics/ui 44.13.0 → 45.2.0

package/docs/reviewing.md

@@ -15,17 +15,25 @@ Everything here is about a screen **that already renders**. Building one starts
 
 ## The method
 
-**"Looks off" is a hypothesis, not a finding.** An impression cannot be compared across a screen
-or re-checked after a fix. Extract computed values and let the table show the defect. Every
-finding cites numbers.
+**"Looks off" is where a finding starts.** Trust the impression — it is the same reaction the
+reader will have — and use measurement to say precisely WHAT is off, so the fix can be aimed and
+re-checked. Numbers are how a finding is confirmed and communicated, never what makes it real.
+
+The failure this doc has caused more than once: a screen passes every probe, the auditor reports
+that it measures fine, and the person who called it ugly is still right. Defect-removal converges
+on *inoffensive*. When the probes come back clean and the screen is still wrong, the probes are
+not the answer — the form, the density, or the fact that nothing on screen belongs to this product
+is. Go and look at it.
 
 1. **Render it** — `lotics app dev` for an app, a preview route for a screen. Drive it with
    browser automation that can evaluate JS in the page.
-2. **Run the two gates**, then the probes.
-3. **Fix, then re-measure.** A design fix is verified the way it was found.
-4. **Screenshot too.** Numbers say *what* is wrong; a picture says *that* something is, and some
-   defects live only in the picture — a mark floating over a tile that never loaded measures
-   perfectly and is obviously broken on sight. Take it even when the numbers are clean.
+2. **Look at it first.** Form a view before running anything, and write it down. That view is
+   what the probes are being asked to explain.
+3. **Run the gates**, then reach for whichever probes speak to what you saw. They are a
+   diagnostic kit, not a checklist to complete — a screen that needs three of them needs three.
+4. **Fix, then re-check** the way you found it.
+5. **Screenshot.** Some defects live only in the picture — a mark floating over a tile that never
+   loaded measures perfectly and is obviously broken on sight.
 
 **Map raw CSS back to the ladder as you go.** A finding reads as `xs/500/muted`, not
 `12px/500/rgb(82,82,91)`, so the treatment classes are visible at a glance. The rungs are in
@@ -619,10 +627,14 @@ has three gotchas of its own: [testing.md](./testing.md).
 
 ## What measurement cannot see
 
-A screenshot shows *that* something is wrong when every number looks defensible. But it will not
-show you a disclosure you did not expand, or copy that only lies in its terminal state (a settled
-row still saying "Loading…" measures perfectly). Nor a flattering fixture — compare the preview
-data's SHAPE against what the real source emits before trusting any of it.
+Most of what makes a screen good, which is why the probes are a floor and not a target. They will
+not tell you the density is wrong for the job, that the register has no point of view, or that
+nothing on the page belongs to this product rather than to any product. Those are judgements, and
+they are the ones that decide whether the work reads as considered.
+
+Nor will they show a disclosure you did not expand, copy that only lies in its terminal state (a
+settled row still saying "Loading…" measures perfectly), or a flattering fixture — compare the
+preview data's SHAPE against what the real source emits before trusting any of it.
 
 ---
 

package/docs/templates.md

@@ -680,7 +680,7 @@ billing, and quick-capture templates. Top → bottom:
 - **The page layout is the DOCS layout — the reading column is CENTRED IN THE VIEWPORT, and
   the rail sits in its left gutter.** The `ScrollView` is FULL-WIDTH — **never cap it at
   `CONTENT_MAX`, or the scroll container becomes the column and the gutters go wheel-dead**
-  (measured: a 720px scroller in a 1440px window leaves half the page ignoring the wheel).
+  (a capped scroller leaves the page either side of it ignoring the wheel).
   Inside it sits one centred row (`width: "100%"`,
   `maxWidth: GUTTER * 2 + CONTENT_MAX`, `alignSelf: "center"`, `flexDirection: "row"`) of
   three parts: a gutter RESERVED for the rail (`width: GUTTER` — the rail's own `RAIL_W`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "44.13.0",
+  "version": "45.2.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -233,6 +233,7 @@
     "./list": "./src/list.tsx",
     "./list_item": "./src/list_item.tsx",
     "./section_heading": "./src/section_heading.tsx",
+    "./heading_altitude": "./src/heading_altitude.ts",
     "./section_stack": "./src/section_stack.tsx",
     "./sequence": "./src/sequence.tsx",
     "./separator": "./src/separator.tsx",

package/src/accordion.tsx

@@ -152,8 +152,8 @@ export interface AccordionMetaProps {
 export function AccordionMeta(props: AccordionMetaProps) {
   // The meta yields before the title does. The title NAMES the disclosure; the
   // meta only qualifies it — but with the title on `flex: 1` and the meta at its
-  // intrinsic width, the squeeze landed entirely on the name (measured at 375:
-  // title clipped 24% and ellipsised, meta untouched). Same inverted priority
+  // intrinsic width, the squeeze lands entirely on the name — the title
+  // ellipsises while the meta goes untouched. Same inverted priority
   // `PageHeader` fixed one rung up; resolved the same way here.
   return (
     <Text size="xs" color="muted" tabular numberOfLines={1} style={styles.meta}>

package/src/avatar_group.tsx

@@ -42,7 +42,7 @@ const OVERLAP_RATIO = 0.3;
  * component overlap at all. The conventional facepile rings each mark in the
  * page background so the discs read as separate, which binds the ring to a
  * colour the row does not keep: a register row washes to `zinc[50]` on hover,
- * `accent_wash` as the open record and `zinc[200]` while pressed, so a white
+ * `zinc[100]` as the open record and `zinc[200]` while pressed, so a white
  * ring is a halo in three of the four states — and those are the states a
  * reader is in when they are actually looking at the row. A translucent dark
  * edge DARKENS whatever is behind it instead of matching it, so it holds on

package/src/avatar_size.ts

@@ -104,9 +104,8 @@ const words = (name: string): string[] => name.trim().split(/\s+/).filter((w) =>
  * TWO LETTERS, AND THEY ARE THE FIRST AND **LAST** WORDS — not the first two.
  * A Vietnamese name is họ + đệm + tên, so the first two words are the family name
  * and a middle name shared by half the office: "Vũ Thị Lan" and "Vũ Thị Ngọc" both
- * reduce to "VT". Taking the first and last gives VL and VN. Measured on a real
- * 29-person workspace, first-two-words leaves 11 people indistinguishable and
- * first-and-last leaves 5. It is also what English display initials have always
+ * reduce to "VT". Taking the first and last gives VL and VN, which collides far
+ * less often on a real roster. It is also what English display initials have always
  * been — "Mary Jane Watson" is MW — so this is a correction, not a localization.
  *
  * `sm` gets ONE letter: two do not fit legibly at 24px, which is the whole reason

package/src/card_select_item.tsx

@@ -61,12 +61,13 @@ const styles = StyleSheet.create({
   ring: {
     ...({ boxShadow: FOCUS_RING } as ViewStyle),
   },
-  // The accent wash + accent edge is the same "you are here" the selected table
-  // row and the active chip carry, so one signal means one thing product-wide.
-  // A ground rather than a heavier outline: among white cards a 1px border
-  // change is noise, and it vanishes entirely under the hover ring.
+  // A DARK EDGE, the same one a selected chip wears — this card cited the chip
+  // as its precedent when both used the accent, and it still follows it. Doubled
+  // by a boxShadow so it is two pixels of the kit's darkest ink rather than one,
+  // which is what the accent ground was introduced to fix and what the ground
+  // itself could not do without spending the brand on a selection.
   selected: {
-    backgroundColor: colors.accent_wash,
-    borderColor: colors.accent,
+    borderColor: colors.zinc[900],
+    ...({ boxShadow: `0 0 0 1px ${colors.zinc[900]}` } as ViewStyle),
   },
 });

package/src/color_tokens.ts

@@ -337,7 +337,8 @@ export const colors = {
    */
   primary: palette.zinc["900"],
   /**
-   * The brand's TINT — a row's hover, an active filter's ground, a header band.
+   * The brand's TINT — a selected row's ground, an active filter's ground, a
+   * header band.
    *
    * It exists as its own token because it cannot be derived where it is used:
    * `withAlpha`/`tint` do string surgery on an `rgba()`, and on web `accent` is a
@@ -345,11 +346,26 @@ export const colors = {
    * type would catch. `applyLoticsTheme` computes it instead, from the literal
    * hex the app handed it — derivation happens where the literal still exists.
    *
-   * The default is DERIVED FROM `accent`'s default, not picked separately: the
-   * accent is blue-600, so the wash is blue-50. It was zinc-100, which meant the
-   * two halves of one token pair disagreed and every unthemed app got a
-   * colourless "you are here"; a wash that contradicts its own accent is not a
-   * neutral default, it is a second brand nobody chose.
+   * IT IS FOR ATTENTION, NEVER FOR SELECTION, and that line is why this comment
+   * is long. Every SELECTED state in the kit is neutral and says so in its own
+   * literal: a register row is zinc-100, a chip and a card are a doubled zinc-900
+   * EDGE with no ground of their own. What is left for this token is the state
+   * that genuinely wants the brand — a region lighting up under a dragged file,
+   * a moment the eye is meant to be pulled to and that no app would want in grey.
+   *
+   * The confusion cost a round trip in both directions, so the line is worth
+   * holding. Selections were painted through this token, and the kit shipped a
+   * blue nobody had chosen on its busiest surface; the token was then made
+   * neutral, which turned a themed app's drop target grey and made the name a
+   * lie. Pointing selections at their own literals fixes both at once — the token
+   * keeps its meaning, and "is this selected" stops depending on whether a tenant
+   * happened to set an accent.
+   *
+   * It is a TOKEN rather than a call-site derivation because `withAlpha`/`tint`
+   * do string surgery on an `rgba()`, and on web `accent` is a `var()` — asking
+   * for "accent at 7%" where it is used produces garbage no type would catch.
+   * `applyLoticsTheme` computes it from the literal hex the app handed it, which
+   * is the one place the literal still exists.
    */
   accent_wash: palette.blue["50"],
   shadow: `0px 0px 6px 1px ${palette.zinc["300"]}`,

package/src/combobox.tsx

@@ -534,7 +534,17 @@ export function ComboboxContent(props: ComboboxContentProps) {
                 // Rich row (custom content, or a label over its description) → the growing
                 // `MenuListItem`; a plain option stays the fixed-height `MenuButton`.
                 return content || desc ? (
-                  <MenuListItem key={`${row.kind}-${opt.value}`} {...shared} title={content ?? label} description={content ? undefined : desc} />
+                  <MenuListItem
+                    key={`${row.kind}-${opt.value}`}
+                    {...shared}
+                    title={content ?? label}
+                    // A custom render and a description are INDEPENDENT facts —
+                    // see the same rule in `option_list`. `optionPicker` sets
+                    // `renderOptionContent` whenever a badge is asked for, so
+                    // suppressing here loses the subtitle for any caller who
+                    // wanted both, silently.
+                    description={desc}
+                  />
                 ) : (
                   <MenuButton
                     key={`${row.kind}-${opt.value}`}

package/src/control_surface.ts

@@ -190,22 +190,28 @@ export function chipSurfaceStyle(
     justifyContent: "center",
     borderRadius: CONTROL_RADIUS,
     borderWidth: 1,
-    // A SELECTED chip needs a GROUND, not a heavier outline. This drew
-    // zinc-900 at 2px on a white fill — and in a toolbar where every sibling is
-    // also a white pill with a 1px border, "which filter is on" came down to a
-    // one-pixel colour change that reads as noise at a glance. The accent wash
-    // is the same "you are here" ground the active tab and the selected row
-    // carry, so one signal means one thing across the product; it also stays
-    // clear of the primary button's near-black fill, which a dark chip would
-    // have collided with two controls away.
-    borderColor: selected ? colors.accent : colors.border,
-    backgroundColor: selected
-      ? colors.accent_wash
-      : state.pressed
-        ? colors.zinc[200]
-        : state.hovered
-          ? colors.zinc[100]
-          : colors.white,
+    // A SELECTED chip is a dark EDGE, and its ground is the ground of every other
+    // chip. The edge is `zinc[900]` doubled by a boxShadow — the kit's focus-ring
+    // ink and weight — so "which one is on" is answered by the same treatment
+    // that answers "where am I", learned once and used everywhere.
+    //
+    // It carried a ground for a while instead, on the argument that among white
+    // pills a one-pixel border change reads as noise. Two things were wrong with
+    // that. A ground is the row's language and a chip is a CONTROL, so the two
+    // altitudes started saying the same thing in the same paint; and it spent the
+    // brand on a selection, which then had to be walked back everywhere at once.
+    // The doubled edge is not one pixel — it is two, in the darkest ink the kit
+    // has, and it survives the hover wash instead of being replaced by it.
+    //
+    // boxShadow rather than a thicker `borderWidth`: a border grows the box, so a
+    // chip would reflow its neighbours on selection.
+    borderColor: selected ? colors.zinc[900] : colors.border,
+    backgroundColor: state.pressed
+      ? colors.zinc[200]
+      : state.hovered
+        ? colors.zinc[100]
+        : colors.white,
+    ...(selected ? ({ boxShadow: `0 0 0 1px ${colors.zinc[900]}` } as ViewStyle) : null),
   };
 }
 

package/src/date_stamp.tsx

@@ -126,9 +126,7 @@ export function DateStamp(props: DateStampProps) {
               // an icon has no equivalent of, so the label's optical centre (its
               // cap band) sits ~2px above the box centre. Matching box centres
               // therefore hangs the icon low against the text every time.
-              //
-              // Measured on this row: label box 344–364, cap band ~348–358. The
-              // lift is that gap, not a taste adjustment.
+              // The lift is that gap, not a taste adjustment.
               <View style={{ height: 16, justifyContent: "center", alignSelf: "center", marginBottom: 2 }}>
                 <Icon name="calendar" size={13} color={hovered ? colors.zinc[500] : colors.zinc[400]} />
               </View>

package/src/detail_row.tsx

@@ -249,8 +249,7 @@ const styles = StyleSheet.create({
   // `flex: 1` — grow 1, shrink 1, basis **0** — so the label entered the layout
   // claiming no size at all, and a value too wide for the row (a company name in
   // a stacked register) took the whole row while the label absorbed the entire
-  // deficit: measured at 0px wide and 140px tall, "Hợp đồng" set one character
-  // per line down the page.
+  // deficit and set one character per line down the page.
   //
   // With `basis: auto` the label enters at its TEXT width, so a deficit is split
   // between the two in proportion to what each actually asked for — a long value
@@ -260,9 +259,9 @@ const styles = StyleSheet.create({
   // Spread mode's label. It does NOT shrink, and that is the whole rule: both
   // items in this row are floorless under React Native Web (which defaults flex
   // children to `min-width: 0`, unlike the web's `auto`), so with shrink on both
-  // the flex algorithm splits the deficit and the LABEL loses — measured on a
-  // narrow register, a two-word column name collapsed to a 4px box 200px tall,
-  // one character per line, while its neighbour with a short value measured a
+  // the flex algorithm splits the deficit and the LABEL loses — a two-word
+  // column name collapses to a sliver set one character per line, while its
+  // neighbour with a short value keeps a
   // clean 251x20. A label the reader cannot finish makes the row meaningless,
   // and the value beside it wraps for free (`spreadValue` already carries the
   // `minWidth: 0` that lets it), so the value is the one that gives way.

package/src/dialog.tsx

@@ -16,6 +16,7 @@ import {
   useRouteRegistry,
   useNavigationStack,
 } from "./screen_router";
+import { HeadingAltitudeContext } from "./heading_altitude";
 
 // ============================================================================
 // Shared Navigation Context (used by both Dialog and MasterDetailDialog)
@@ -104,9 +105,9 @@ function dialogGutterFor(small: boolean): number {
  *
  * Centralising the VALUE was not enough, and that mistake shipped: `dialogGutter(small)` still
  * left every band to work out `small` for itself, and `AgentRunPane` asked
- * `useContainerSize()` (its own measured box, "small" at a 760px dialog) while the header,
- * scroll area and footer asked `useScreenSize()` (the viewport, not small). Two honest answers
- * to one question put the run's rows 8px left of the dialog's own title.
+ * `useContainerSize()` (its own box) while the header, scroll area and footer asked
+ * `useScreenSize()` (the viewport). Two honest answers to one question left the run's rows
+ * out of line with the dialog's own title.
  *
  * So the Dialog decides ONCE and publishes it. A band inside a dialog gets that number
  * whatever its own box measures; a surface rendered outside one falls back to the SCREEN — the
@@ -285,10 +286,16 @@ export function DialogScrollArea(props: DialogScrollAreaProps) {
   const { children } = props;
   const gutter = useDialogGutter();
 
+  // The gutter and the heading altitude are the same kind of fact — both belong
+  // to the panel, and both were being answered by callers who could only guess.
+  // A `SectionHeadingTitle` in here renders the ramp's `####` rung, under the
+  // `lg` `DialogHeaderTitle` above it. See `heading_altitude.ts`.
   return (
-    <ScrollView contentContainerStyle={[styles.scrollAreaContent, { paddingHorizontal: gutter }]}>
-      {children}
-    </ScrollView>
+    <HeadingAltitudeContext.Provider value="panel">
+      <ScrollView contentContainerStyle={[styles.scrollAreaContent, { paddingHorizontal: gutter }]}>
+        {children}
+      </ScrollView>
+    </HeadingAltitudeContext.Provider>
   );
 }
 

package/src/drawer.tsx

@@ -8,6 +8,7 @@ import { IconButton } from "@lotics/ui/icon_button";
 import { Text } from "@lotics/ui/text";
 import { useOverlayScope } from "@lotics/ui/overlay_scope";
 import { useLoticsLocale } from "@lotics/ui/locale";
+import { HeadingAltitudeContext } from "./heading_altitude";
 
 /**
  * The panel's inset — the ONE left edge the header, `DrawerScrollArea` and the footer
@@ -167,9 +168,8 @@ export interface DrawerScrollAreaProps {
  * its title was inset 20.
  *
  * It ALWAYS scrolls, and there is deliberately no flag to stop it. A padded box
- * holding a `flex:1` scroller insets that scroller's VIEWPORT — measured, a 400px
- * panel ends its scroll at 380 — so the list clips short of the panel with dead
- * space beneath it. A surface that genuinely needs a pinned region above a
+ * holding a `flex:1` scroller insets that scroller's VIEWPORT, so the list clips
+ * short of the panel with dead space beneath it. A surface that genuinely needs a pinned region above a
  * scrolling one is not this component: it goes in the `Drawer`'s bare slot and
  * puts `DRAWER_GUTTER` on the pinned part's padding AND on its scroller's
  * `contentContainerStyle`, which is the only arrangement where content still
@@ -182,7 +182,21 @@ export interface DrawerScrollAreaProps {
  * does, and would force every full-bleed child to cancel it with a negative margin.
  */
 export function DrawerScrollArea(props: DrawerScrollAreaProps) {
-  return <ScrollView style={styles.body} contentContainerStyle={styles.bodyContent}>{props.children}</ScrollView>;
+  // It publishes the panel's HEADING ALTITUDE as well as its gutter, and for the
+  // same reason: this is the region whose left edge and whose outline both
+  // belong to the panel. A `SectionHeadingTitle` in here steps to the ramp's
+  // `####` rung, under the `lg` title in the bar above it, without the caller
+  // naming the container it is in — that naming is what nine apps out of nine
+  // got wrong, and the container never has to be told.
+  //
+  // Not on `Drawer` itself: the drawer's BARE slot is where a whole record
+  // screen goes, and that surface brings its own `#` identity band, so its
+  // sections are page sections and must stay `##`. See `heading_altitude.ts`.
+  return (
+    <HeadingAltitudeContext.Provider value="panel">
+      <ScrollView style={styles.body} contentContainerStyle={styles.bodyContent}>{props.children}</ScrollView>
+    </HeadingAltitudeContext.Provider>
+  );
 }
 
 export interface DrawerFooterProps {

package/src/filter_chip.tsx

@@ -91,8 +91,7 @@ export function FilterChip(props: FilterChipProps) {
   // bring their own bottom actions — an `OptionList` with `enableSelectAll`
   // renders "Select all / Deselect all" in a bordered band of its own — so the
   // popover ended with TWO stacked rules whose lower one held a single button
-  // that "Deselect all" directly above it already performed. Measured on a live
-  // filter: bands at 49px and 47px, each with its own 1px top border.
+  // that "Deselect all" directly above it already performed.
   //
   // The × is also the more discoverable of the two: it sits on the pill, which
   // is on screen whether or not the popover is open, and it carries `clearLabel`

package/src/finding.tsx

@@ -164,16 +164,33 @@ export function Finding(props: FindingProps) {
 
 /** The source behind a reading. Pressable only when the host can navigate to
  *  it — an affordance on something that goes nowhere is a broken promise. */
+/**
+ * A reading's source — the caption naming WHERE the value came from, and, when
+ * the host can open it, the way there.
+ *
+ * The two states are treated differently ON PURPOSE. A source that opens
+ * something is a control and wears navigation ink: default colour, `medium`,
+ * underlined. A source that opens nothing stays a caption: `muted`, regular, no
+ * rule. They used to render IDENTICALLY — muted caption text, with the press
+ * target announced only to a screen reader and revealed to everyone else on
+ * hover. A control nobody can see is not reachable in any sense that counts, and
+ * the inverse mistake (a caption dressed as a link, so a reader keeps pressing
+ * text that does nothing) is the same failure read from the other end. What a
+ * control looks like has to promise what pressing it does.
+ */
 function SourceName({ label, onOpen }: { label: string; onOpen?: (source: string) => void }) {
-  const name = (
-    <Text size="sm" color="muted" numberOfLines={1}>
-      {label}
-    </Text>
-  );
-  if (!onOpen) return name;
+  if (!onOpen) {
+    return (
+      <Text size="sm" color="muted" numberOfLines={1}>
+        {label}
+      </Text>
+    );
+  }
   return (
     <PressableHighlight onPress={() => onOpen(label)} accessibilityRole="link" accessibilityLabel={label}>
-      {name}
+      <Text size="sm" weight="medium" decoration="underline" numberOfLines={1}>
+        {label}
+      </Text>
     </PressableHighlight>
   );
 }

package/src/heading_altitude.ts

@@ -0,0 +1,65 @@
+import { createContext, useContext } from "react";
+
+/**
+ * WHICH SURFACE a heading is standing on — the one fact the fixed heading ramp
+ * needs, and the one fact a caller should never have to restate.
+ *
+ * `page` — the flat canvas. A `#` identity band (`PageHeader`, `RecordSummary`)
+ * tops the outline, so a section title is the `##` below it.
+ *
+ * `panel` — a self-contained pane whose own chrome title caps at `lg`, or which
+ * has no title at all: a `Dialog`, `Drawer`, `Modal` or `Popover` body, and
+ * equally a side panel docked beside a page. A `##` renders at 24px there, over
+ * a 20px bar — measured, and identical everywhere, because the ramp had no way
+ * to know which surface it was on and the caller had no reason to think it
+ * mattered.
+ *
+ * A parallel per-surface heading component does not fix that; it only moves the
+ * question to the call site, where the caller still has to know what is holding
+ * their heading, and answers wrong for the same reason they never noticed the
+ * inversion. So the CONTAINER answers instead. It is the only party that knows,
+ * and it knows without being told.
+ */
+export type HeadingAltitude = "page" | "panel";
+
+/**
+ * Published by the CONTENT REGIONS — `DrawerScrollArea`, `DialogScrollArea`,
+ * `ModalBody`, `PopoverContent` — and NOT by `Drawer`, `Dialog` or `Modal`
+ * themselves.
+ *
+ * That is deliberate, and it is the whole reason the split works. An overlay is
+ * used two ways: as a PANEL, whose chrome title is the top of its outline, and
+ * as a FRAME around a whole page surface that brings its own `#` identity band
+ * (the master-detail register — a record screen docked in a drawer). The panel
+ * has to step down; the page surface must not, or its `##` sections drop below
+ * the `###` subsections nested inside them.
+ *
+ * The kit already distinguishes those two, and it distinguishes them exactly
+ * here: the content regions own the container's gutter, and a body that carries
+ * its own gutters — "a full-bleed band, a whole record screen" — takes the
+ * container's bare slot instead and skips them. So the marker already exists,
+ * already means what we need it to mean, and is already load-bearing enough that
+ * it cannot be dropped by accident.
+ *
+ * A body that uses neither keeps `page` and renders exactly what it renders
+ * today. That is the safe direction to be wrong in: the fix arrives when the
+ * body wraps in the region the kit already asks it to wrap in, and a surface the
+ * kit cannot see is never silently re-ranked.
+ *
+ * **A host that builds its own pane publishes it directly** — wrap the pane's
+ * content in `<HeadingAltitudeContext.Provider value="panel">`. A docked side
+ * panel is the case: it is not an overlay, it uses none of the regions above,
+ * and its headings still must not out-shout a pane 400px wide. Scoping the rule
+ * to the containers the KIT happens to render would make it an allowlist that is
+ * silently short by however many panes the host builds itself.
+ *
+ * The value is FLAT, never a depth counter. A popover opened from inside a
+ * drawer is still one rung down, not two — the ramp is absolute per altitude,
+ * and nesting panes must not invent a fifth rung.
+ */
+export const HeadingAltitudeContext = createContext<HeadingAltitude>("page");
+
+/** The altitude of the surface this heading is on. `page` unless a pane says otherwise. */
+export function useHeadingAltitude(): HeadingAltitude {
+  return useContext(HeadingAltitudeContext);
+}

package/src/icon.tsx

@@ -132,8 +132,12 @@ import Maximize2 from "lucide-react-native/dist/esm/icons/maximize-2";
 import Megaphone from "lucide-react-native/dist/esm/icons/megaphone";
 import Mic from "lucide-react-native/dist/esm/icons/mic";
 import Menu from "lucide-react-native/dist/esm/icons/menu";
+import Facebook from "lucide-react-native/dist/esm/icons/facebook";
+import Instagram from "lucide-react-native/dist/esm/icons/instagram";
+import Linkedin from "lucide-react-native/dist/esm/icons/linkedin";
 import MessageCircle from "lucide-react-native/dist/esm/icons/message-circle";
 import MessageCircleQuestionMark from "lucide-react-native/dist/esm/icons/message-circle-question-mark";
+import Twitter from "lucide-react-native/dist/esm/icons/twitter";
 import MessageSquare from "lucide-react-native/dist/esm/icons/message-square";
 import MessagesSquare from "lucide-react-native/dist/esm/icons/messages-square";
 import Minimize2 from "lucide-react-native/dist/esm/icons/minimize-2";
@@ -328,8 +332,12 @@ const iconComponents = {
   "maximize-2": Maximize2,
   megaphone: Megaphone,
   menu: Menu,
+  facebook: Facebook,
+  instagram: Instagram,
+  linkedin: Linkedin,
   "message-circle": MessageCircle,
   "message-circle-question-mark": MessageCircleQuestionMark,
+  twitter: Twitter,
   "message-square": MessageSquare,
   "messages-square": MessagesSquare,
   mic: Mic,

package/src/inline_edit.tsx

@@ -167,8 +167,15 @@ interface InlineEditFrameProps {
    * which is the truth for every editor whose input arrives with the edit.
    */
   editOpen?: boolean;
-  /** The formatted current value, shown in view mode. Empty → placeholder. */
-  display: string;
+  /** The current value as the view shows it. Empty string → placeholder.
+   *
+   *  A NODE renders as-is, which is what a SWAPPING editor needs when its
+   *  resting form is not text — rendered markdown against its own source. That
+   *  is admissible for the same reason number/date swap: the string genuinely
+   *  CHANGES between the two states, so the sub-pixel drift an always-input
+   *  exists to avoid is not perceptible. `InlineEditView` already renders both;
+   *  this only stops the frame from narrowing what it forwards. */
+  display: string | ReactNode;
   placeholder?: string;
   /** Enter edit mode (the view is pressed). */
   onBegin: () => void;
@@ -760,7 +767,11 @@ const styles = StyleSheet.create({
   },
   placeholder: { color: colors.zinc[400] },
   struck: { textDecorationLine: "line-through", color: colors.zinc[500] },
-  viewNode: { flex: 1, minWidth: 0 },
+  // `textAlign` is not cosmetic here: the resting box is a button-role Pressable,
+  // so the UA stylesheet centres every string inside it. A STRING display never
+  // showed it — `Text` sets its own alignment — so the centring only surfaced
+  // once `display` accepted a node and rendered prose that inherited it.
+  viewNode: { flex: 1, minWidth: 0, textAlign: "left" },
   editRow: { flexDirection: "row", alignItems: "flex-start", gap: 6 },
   editControl: { flex: 1, position: "relative" },
   // The input brings its own 40px height, so the surface must not add its resting