@refrakt-md/lumina 0.20.0 → 0.20.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@refrakt-md/lumina",
   "description": "Lumina theme for refrakt.md — design tokens, CSS, identity transform, and layout configs",
-  "version": "0.20.0",
+  "version": "0.20.1",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -83,9 +83,9 @@
     "build": "tsc"
   },
   "dependencies": {
-    "@refrakt-md/runes": "0.20.0",
-    "@refrakt-md/transform": "0.20.0",
-    "@refrakt-md/types": "0.20.0"
+    "@refrakt-md/runes": "0.20.1",
+    "@refrakt-md/transform": "0.20.1",
+    "@refrakt-md/types": "0.20.1"
   },
   "devDependencies": {
     "postcss": "^8.4.0"

package/styles/dimensions/cover.css

@@ -103,14 +103,27 @@
 	position: absolute;
 	inset: 0;
 	pointer-events: none;
-	background-image: linear-gradient(var(--cover-scrim-dir, to top), rgb(0 0 0 / 0.55), transparent 62%);
+	/* `inherit` matches the media zone's `--rf-radius-media`, so a frost scrim's
+	 * `backdrop-filter` region clips at the same rounded corners — `overflow:
+	 * hidden` on the media zone doesn't reliably clip backdrop-filter past the
+	 * rounded edge in WebKit, so the pseudo carries its own radius. (The
+	 * gradient variant doesn't strictly need this, but it's harmless and keeps
+	 * the two scrim variants visually congruent.) */
+	border-radius: inherit;
+	/* The scrim shape is `--cover-scrim-image` (custom property override) when
+	 * the engine emits one — for `content-place="center …"` it emits a radial
+	 * ellipse so the dark falls under the centred overlay. For the directional
+	 * cases (`start`/`end` block-axis) the engine sets `--cover-scrim-dir` and
+	 * the linear fallback resolves to the right edge. */
+	background-image: var(--cover-scrim-image, linear-gradient(var(--cover-scrim-dir, to top), rgb(0 0 0 / 0.55), transparent 62%));
 }
 
 /* Frost treatment (`scrim-type="frost"`) — a frosted-glass blur over the media
  * instead of a gradient. `scrim-blur` (named scale) sets the blur radius; the
  * tint follows the cover scheme (a dark scheme → a dark frost for light text).
  * The frost is masked to the content edge (following `--cover-scrim-dir`, default
- * bottom) so it reads as a band behind the text, not a blur over the whole image. */
+ * bottom) so it reads as a band behind the text, not a blur over the whole
+ * image. `--cover-scrim-mask` is the radial equivalent for centred content. */
 [data-media-position="cover"][data-scrim-blur="none"] { --cover-scrim-blur: 0px; }
 [data-media-position="cover"][data-scrim-blur="sm"]   { --cover-scrim-blur: 4px; }
 [data-media-position="cover"][data-scrim-blur="md"]   { --cover-scrim-blur: 8px; }
@@ -120,8 +133,8 @@
 	background-color: rgb(0 0 0 / 0.18);
 	-webkit-backdrop-filter: blur(var(--cover-scrim-blur, 8px));
 	backdrop-filter: blur(var(--cover-scrim-blur, 8px));
-	-webkit-mask-image: linear-gradient(var(--cover-scrim-dir, to top), #000 30%, transparent 72%);
-	mask-image: linear-gradient(var(--cover-scrim-dir, to top), #000 30%, transparent 72%);
+	-webkit-mask-image: var(--cover-scrim-mask, linear-gradient(var(--cover-scrim-dir, to top), #000 30%, transparent 72%));
+	mask-image: var(--cover-scrim-mask, linear-gradient(var(--cover-scrim-dir, to top), #000 30%, transparent 72%));
 }
 [data-media-position="cover"][data-scrim-type="frost"][data-color-scheme="light"]:not([data-scrim="none"]) [data-section="media"]::after {
 	background-color: rgb(255 255 255 / 0.25);

package/styles/dimensions/frame.css

@@ -20,11 +20,31 @@
  * `frame-shadow` (drop-shadow silhouette here) never collide — different property,
  * different surface. */
 
-/* ── Silhouette drop-shadow ──────────────────────────────────────────── */
-[data-frame-shadow="none"] { filter: none; }
-[data-frame-shadow="sm"]   { filter: drop-shadow(0 4px 12px rgba(0, 0, 0, 0.10)); }
-[data-frame-shadow="md"]   { filter: drop-shadow(0 2px 8px rgba(0, 0, 0, 0.25)); }
-[data-frame-shadow="lg"]   { filter: drop-shadow(0 12px 40px rgba(0, 0, 0, 0.20)); }
+/* ── Silhouette drop-shadow ────────────────────────────────────────────
+ * Same media-target / self-target split as `frame-displace`. Media-target
+ * frames land `data-frame-shadow` on the media zone wrapper, but the shadow
+ * should ride the inner guest so it (a) shifts with `frame-displace` and
+ * (b) actually casts onto exposed slot interior when the guest is inset
+ * from the wrapper. Self-target frames (showcase, figure) keep the filter
+ * on the root itself, where it traces the rune's own painted silhouette. */
+[data-frame-shadow="none"] { --frame-shadow: none; }
+[data-frame-shadow="sm"]   { --frame-shadow: drop-shadow(0 4px 12px rgba(0, 0, 0, 0.10)); }
+[data-frame-shadow="md"]   { --frame-shadow: drop-shadow(0 2px 8px rgba(0, 0, 0, 0.25)); }
+[data-frame-shadow="lg"]   { --frame-shadow: drop-shadow(0 12px 40px rgba(0, 0, 0, 0.20)); }
+
+/* Self-target — figure, showcase, anything else where the rune root is the
+ * frame target. The filter applies to the painted root. */
+[data-frame-shadow]:not([data-section="media"]) {
+	filter: var(--frame-shadow);
+}
+
+/* Media-target — card, bento-cell, recipe, etc. The filter rides the inner
+ * guest so a displaced image's shadow falls into the slot's exposed
+ * interior (clipped at the slot's `overflow: hidden` boundary like any
+ * other in-slot content). */
+[data-section="media"][data-frame-shadow] > :is(img, video, [data-rune]) {
+	filter: var(--frame-shadow);
+}
 
 /* ── Aspect ratio ────────────────────────────────────────────────────── */
 [style*="--frame-aspect"] { aspect-ratio: var(--frame-aspect); }
@@ -36,19 +56,49 @@
 [style*="--frame-place-x"] { justify-self: var(--frame-place-x, auto); align-self: var(--frame-place-y, auto); }
 
 /* ── Oversize — guest exceeds its slot (clipping hosts crop it) ──────── */
-[style*="--frame-oversize"] > :is(img, video) { width: calc(100% * var(--frame-oversize, 1)); max-width: none; }
-
-/* ── Displacement (bleed / peek) — move the guest toward an edge/corner.
- * The host decides whether it spills or is cropped; this only moves it. ─ */
-[data-displace] { position: relative; z-index: 1; }
-[data-displace="top"]        { margin-top: calc(-1 * var(--frame-offset, var(--rf-spacing-lg))); }
-[data-displace="bottom"]     { margin-bottom: calc(-1 * var(--frame-offset, var(--rf-spacing-lg))); }
-[data-displace="both"]       { margin-block: calc(-1 * var(--frame-offset, var(--rf-spacing-lg))); }
-[data-displace="end"]        { margin-inline-end: calc(-1 * var(--frame-offset, var(--rf-spacing-lg))); }
-[data-displace="bottom-end"] { margin-bottom: calc(-1 * var(--frame-offset, var(--rf-spacing-lg))); margin-inline-end: calc(-1 * var(--frame-offset, var(--rf-spacing-lg))); }
-[data-displace="top-end"]    { margin-top: calc(-1 * var(--frame-offset, var(--rf-spacing-lg))); margin-inline-end: calc(-1 * var(--frame-offset, var(--rf-spacing-lg))); }
-
-/* Collapse displacement on mobile, regardless of host. */
-@media (max-width: 768px) {
-	[data-displace] { margin: 0; }
+/* `[data-rune]` extends the rule to nested rune guests (codegroup, mockup,
+ * chart, etc.), so frame chrome stays guest-agnostic — the same selector
+ * pattern the displace rule uses. */
+[style*="--frame-oversize"] > :is(img, video, [data-rune]) { width: calc(100% * var(--frame-oversize, 1)); max-width: none; }
+
+/* ── Displacement (peek / spill) — move the guest toward an edge/corner.
+ * The host decides whether the guest is cropped or spills; this only moves it.
+ * Two cases, distinguished by where the engine landed `data-displace`:
+ *
+ *   1. Media-target frame (`frameTarget: 'media'`, e.g. card / bento-cell /
+ *      figure media well). `data-displace` lands on the media zone wrapper
+ *      (`[data-section="media"]`), but the wrapper itself is the *host* and
+ *      already has `overflow: hidden`. We translate the inner guest with
+ *      `transform: translate(...)` so the zone clips the peek at its own edge,
+ *      not at the outer card/cell edge. The wrapper stays put — the card's
+ *      layout is unchanged.
+ *
+ *   2. Self-target frame (`frameTarget: 'self'`, e.g. showcase, where the rune
+ *      root is the host). `data-displace` lands on the root, and the root's
+ *      parent (a page section, the page itself) is the clip-or-spill decider.
+ *      We push the root with negative margins so it can spill past its
+ *      parent's edge for a true breakout. */
+
+/* — Case 1: media-zone displace → translate the inner guest, zone clips. */
+[data-section="media"][data-displace] > :is(img, video, [data-rune]) {
+	transform: translate(var(--displace-x, 0), var(--displace-y, 0));
 }
+[data-section="media"][data-displace="top"]        { --displace-y: calc(-1 * var(--frame-offset, var(--rf-spacing-lg))); }
+[data-section="media"][data-displace="bottom"]     { --displace-y: var(--frame-offset, var(--rf-spacing-lg)); }
+[data-section="media"][data-displace="end"]        { --displace-x: var(--frame-offset, var(--rf-spacing-lg)); }
+[data-section="media"][data-displace="top-end"]    { --displace-x: var(--frame-offset, var(--rf-spacing-lg)); --displace-y: calc(-1 * var(--frame-offset, var(--rf-spacing-lg))); }
+[data-section="media"][data-displace="bottom-end"] { --displace-x: var(--frame-offset, var(--rf-spacing-lg)); --displace-y: var(--frame-offset, var(--rf-spacing-lg)); }
+
+/* — Case 2: self-target (showcase, etc.) → root moves; parent decides. */
+[data-displace]:not([data-section="media"]) { position: relative; z-index: 1; }
+[data-displace="top"]:not([data-section="media"])        { margin-top: calc(-1 * var(--frame-offset, var(--rf-spacing-lg))); }
+[data-displace="bottom"]:not([data-section="media"])     { margin-bottom: calc(-1 * var(--frame-offset, var(--rf-spacing-lg))); }
+[data-displace="both"]:not([data-section="media"])       { margin-block: calc(-1 * var(--frame-offset, var(--rf-spacing-lg))); }
+[data-displace="end"]:not([data-section="media"])        { margin-inline-end: calc(-1 * var(--frame-offset, var(--rf-spacing-lg))); }
+[data-displace="bottom-end"]:not([data-section="media"]) { margin-bottom: calc(-1 * var(--frame-offset, var(--rf-spacing-lg))); margin-inline-end: calc(-1 * var(--frame-offset, var(--rf-spacing-lg))); }
+[data-displace="top-end"]:not([data-section="media"])    { margin-top: calc(-1 * var(--frame-offset, var(--rf-spacing-lg))); margin-inline-end: calc(-1 * var(--frame-offset, var(--rf-spacing-lg))); }
+
+/* Displacement carries across breakpoints. For media-target the guest is
+ * clipped by the zone's `overflow: hidden` regardless of width, so the peek
+ * reads consistently from desktop to mobile. For self-target (showcase) the
+ * negative-margin spill stays on too — that's the intended breakout. */

package/styles/dimensions/substrate.css

@@ -55,16 +55,23 @@
 	--substrate-tile: auto;
 }
 
-/* cross — plus marks on a grid (a grid masked down to short ticks at each node) */
+/* cross — plus marks at the centre of each cell, drawn as two perpendicular
+ * thin ellipses (no `mask` — an element-level `mask` would clip the rune's
+ * own text content along with the pattern, which is what we don't want). A
+ * small plus reads fainter than a 1px line at the same ink opacity, so the
+ * pattern carries its own ink boost — same idea as dots.
+ *
+ * The stop syntax mirrors dots: `ink <r>, transparent 0` produces a sharp-
+ * edged shape filled with ink (the explicit length on ink, plus `0` after
+ * transparent for a zero-length transition, beats the `ink 100%, transparent
+ * 100%` form which some renderers collapse to nothing). Ellipse radii at
+ * 1px (rather than sub-pixel 0.5px) so the stroke survives DPR rounding. */
 [data-substrate="cross"] {
 	--substrate-image:
-		linear-gradient(var(--substrate-ink) 1px, transparent 1px),
-		linear-gradient(90deg, var(--substrate-ink) 1px, transparent 1px);
+		radial-gradient(ellipse 3px 1px at center, var(--substrate-ink) 100%, transparent 0),
+		radial-gradient(ellipse 1px 3px at center, var(--substrate-ink) 100%, transparent 0);
 	--substrate-pos: center;
-	-webkit-mask-image: radial-gradient(circle at center, #000 0 2px, transparent 2px);
-	-webkit-mask-size: var(--substrate-cell) var(--substrate-cell);
-	mask-image: radial-gradient(circle at center, #000 0 2px, transparent 2px);
-	mask-size: var(--substrate-cell) var(--substrate-cell);
+	--substrate-boost: 1.6;
 }
 
 /* checker — alternating filled cells */

package/styles/dimensions/surfaces.css

@@ -103,6 +103,17 @@
 	padding: var(--rune-padding, var(--rf-spacing-md));
 }
 
+/* ─── Media slot inherits the surface border ─────────────────────────
+ * When a surface-bearing rune wraps a `[data-section="media"]` slot, the slot
+ * shares the surface's 1px border so the framed media reads as part of the
+ * same surface rather than a separate inner box. Scoped via `:where()` for
+ * zero specificity — per-rune CSS can still override if a particular surface
+ * wants a different chrome (e.g. character's circular portrait avoids this
+ * because it's not a `[data-section="media"]` slot). */
+:where(.rf-card, .rf-bento-cell, .rf-recipe, .rf-realm, .rf-faction, .rf-playlist) [data-section="media"] {
+	border: 1px solid var(--rf-color-border);
+}
+
 /* ─── Inset surface (SPEC-087) — tint-tracking recessed fill ──────────
  * Derived at use-site via relative-color (lower L, keep C+H) so it recomputes from a tinted
  * `--rf-color-surface` automatically (a static inset-colour token would
@@ -116,6 +127,28 @@
 	background: oklch(from var(--rf-color-surface) calc(l - var(--rf-surface-inset-shift)) c h);
 }
 
+/* …but when they're a media-zone guest the slot already provides the recessed
+ * surface (border, radius, inset fill), so the inner chrome would just stack
+ * as double-chrome. Drop it; keep padding so axis labels / SVG keep breathing
+ * room. */
+[data-section="media"] > :is(.rf-chart, .rf-diagram) {
+	background: transparent;
+	border: 0;
+}
+
+/* Same treatment for `juxtapose` as a media guest — its `__panels` container
+ * has its own border + background + rounded corners (juxtapose stands alone
+ * outside a card), but inside a card slot they double up with the slot's own
+ * chrome. Drop the inner chrome; round to match the slot's media radius so the
+ * comparison reads as part of the card surface. The slot's overflow:visible
+ * and container-type:normal still come from `split.css` (juxtapose manages
+ * its own clip inside `__panels`). */
+[data-section="media"] > .rf-juxtapose .rf-juxtapose__panels {
+	background: transparent;
+	border: 0;
+	border-radius: var(--rf-radius-media);
+}
+
 /* Media wells of media-bearing runes: a recessed sub-surface that tracks the
  * (possibly tinted) container colour — invisible under a full-bleed guest,
  * visible in the gaps (transparent, displaced, or absent guest). */

package/styles/layouts/split.css

@@ -106,6 +106,16 @@
 ) {
   overflow: visible;
   container-type: normal;
+}
+/* `preview` (negative-margin breakout) and a displaced `showcase` (peek
+ * spill) want the slot fully de-chromed so the bleed reads as edge-to-edge.
+ * Juxtapose just opted out of the clip — it still wants to read as part of
+ * the card surface, so it keeps the slot's rounded corners (juxtapose's
+ * own `__panels` chrome is dropped instead; see surfaces.css). */
+[data-section="media"]:is(
+  :has(> [data-rune="preview"]),
+  :has(> .rf-showcase[data-displace]:not(.rf-showcase--in-bento-cell))
+) {
   border-radius: 0;
 }
 /* …and let those self-managing guests keep their intrinsic width/sizing: the

package/styles/runes/bg.css

@@ -1,11 +1,16 @@
 /* Background — Directive rune for background images, video, overlays, blur */
 
-/* Background layer — absolute positioned behind content */
+/* Background layer — absolute positioned behind content. `border-radius:
+ * inherit` rounds the gradient/image to whatever shape the parent surface has,
+ * so a card / bento-cell / any rounded host clips the bg to its own corners
+ * without needing `overflow: hidden` (though hosts with thin-edge padding
+ * still need it so the bg can't poke past the rounded outer edge). */
 [data-name="bg"] {
 	position: absolute;
 	inset: 0;
 	z-index: 0;
 	overflow: hidden;
+	border-radius: inherit;
 	background-image: var(--bg-image);
 	background-size: var(--bg-fit, cover);
 	background-position: var(--bg-position, center);
@@ -22,8 +27,14 @@
 [data-name="bg"][data-bg-fixed] {
 	background-attachment: fixed;
 }
-/* Content above background — any sibling of bg layer gets z-index */
-.rf-has-bg > :not([data-name="bg"]) {
+/* Content above background — any sibling of the bg layer gets `z-index: 1`
+ * so it stacks over the `data-name="bg"` layer (which sits at `z-index: 0`).
+ * Keyed off the `data-bg` attribute the engine emits on the bg-owning rune
+ * (`engine.ts` → `bgDataAttrs['data-bg'] = ''`), not the per-block BEM
+ * modifier class `rf-<block>--has-bg` — the attribute is rune-agnostic so
+ * one rule covers card, bento-cell, hero, feature, and anything else that
+ * raises a bg layer. */
+[data-bg] > :not([data-name="bg"]) {
 	position: relative;
 	z-index: 1;
 }

package/styles/runes/card.css

@@ -27,6 +27,13 @@
 	border-radius: var(--rf-radius-container);
 	border: 1px solid var(--rf-color-border);
 	background: var(--rf-color-surface);
+	/* Clip non-media content (substrate patterns, bg gradient/image layers) to
+	 * the card's rounded outer corners. The displaced-peek case is unaffected:
+	 * `frame-displace` translates the guest *inside* the media zone, which has
+	 * its own `overflow: hidden`, so no peek ever crosses this boundary.
+	 * `box-shadow` from `elevation` paints outside the element box and is
+	 * unaffected by `overflow`. */
+	overflow: hidden;
 }
 
 /* Content zone fills the remaining inset so total text padding still equals

package/styles/runes/figure.css

@@ -1,9 +1,23 @@
 /* Figure */
 .rf-figure img {
+	display: block;
 	max-width: 100%;
 	height: auto;
+	margin-inline: auto;
 	border-radius: var(--rf-radius-media);
 }
+
+/* When `frame-aspect` sets an explicit surface shape, the image fills the
+ * shape rather than sitting at its natural size with whitespace on the
+ * inline-end. `object-fit: cover` crops only if the natural aspect doesn't
+ * match — and `frame-anchor` already picks the focal point of that crop
+ * (the same contract as a card's media slot). */
+.rf-figure[style*="--frame-aspect"] img {
+	width: 100%;
+	height: 100%;
+	object-fit: cover;
+	margin: 0;
+}
 .rf-figure figcaption {
 	margin-top: 0.625rem;
 	font-size: 0.825rem;

package/styles/runes/map.css

@@ -22,6 +22,13 @@
 	width: 100%;
 	position: relative;
 	background: var(--rf-color-surface, #f8f9fa);
+	/* Establish a stacking context so Leaflet's internal pane z-indices
+	 * (tile-pane 200, overlay-pane 400, marker-pane 600, popup-pane 700,
+	 * etc.) stay contained instead of escaping past siblings — otherwise
+	 * a map dropped into a cover card's media slot punches through the
+	 * cover scrim (z-index auto) and overlaid content (z-index 1).
+	 * `position: relative` alone is not enough; `isolation: isolate` is. */
+	isolation: isolate;
 }
 
 /* Fallback list shown while Leaflet loads */
@@ -80,6 +87,28 @@
 	display: none;
 }
 
+/* ── Map as a media guest ──
+ * When dropped into a `[data-section="media"]` slot (e.g. a card or
+ * bento-cell in cover mode), the map yields its standalone presentation to
+ * the slot: no outer margin or padding (map is in the Banner surface group
+ * which gives it vertical `--rune-padding`; see `surfaces.css`), no rounding
+ * (the slot already clips), and the Leaflet container stretches to fill the
+ * slot height instead of capping at the per-size pixel height. The fallback
+ * list (rendered before Leaflet hydrates) drops its outer padding too so it
+ * doesn't bleed past the slot edge during the brief flash before tiles load. */
+[data-section="media"] > .rf-map {
+	margin: 0;
+	padding: 0;
+	height: 100%;
+	border-radius: inherit;
+}
+[data-section="media"] > .rf-map > .rf-map__container {
+	height: 100%;
+}
+[data-section="media"] .rf-map__fallback {
+	padding: 0.75rem 1rem;
+}
+
 /* Leaflet popup overrides to match theme */
 .rf-map .leaflet-popup-content-wrapper {
 	border-radius: var(--rf-radius-md, 0.5rem);

package/styles/runes/preview.css

@@ -75,7 +75,11 @@
 	border-radius: var(--rf-radius-lg);
 	overflow: hidden;
 }
-.rf-preview__canvas:has(.rf-mockup) {
+/* Centre a standalone mockup whose `data-fit="none"` makes it inline-block —
+ * margin-inline auto can't centre an inline-block, only its parent's text
+ * alignment can. Scoped to a *direct-child* mockup so a card or bento cell
+ * that happens to hold a mockup doesn't get its body text centred too. */
+.rf-preview__canvas:has(> .rf-mockup) {
 	text-align: center;
 }
 .rf-preview__canvas > *:first-child {