@kywi-software/core 0.9.0 → 0.11.0

package/dist/scope/sticky-offset.js

@@ -0,0 +1,432 @@
+'use client';
+/**
+ * Site-authored top-anchored chrome vs. the editor's own fixed bars
+ * (kywi-cms#146).
+ *
+ * Both front-of-site bars are `position: fixed; top: 0` — the edit-mode
+ * `.kywi-overlay-toolbar` (46px) and the browse-mode `.kywi-edit-toolbar`
+ * (44px). Each pushes the DOCUMENT down by its own height
+ * (`.kywi-frontend-edit--editing` / `--browsing` in editor.css), which is
+ * enough for a header in normal flow: it starts one bar lower and stays
+ * visible.
+ *
+ * It is NOT enough for `position: sticky; top: 0`, the most common theme
+ * pattern there is — and the one the marketing site uses. Document padding
+ * moves an element's FLOW position; it does nothing to where the element pins
+ * once it sticks. So the moment the reader scrolls, a `top: 0` header pins to
+ * viewport y=0, underneath a bar that outranks it by ~950 z-index tiers, and
+ * the top 46px of the site's own navigation is covered and unclickable for the
+ * rest of the session. Measured on the reference app at 1280×720: header rect
+ * `top: 0, height: 65` against a bar occupying 0–46.
+ *
+ * z-index cannot fix this (the bar has to stay on top — it is the way out of
+ * edit mode), and neither can CSS alone: the offset a sticky element needs is
+ * `top: <bar height>`, a declaration only the site's own stylesheet can carry
+ * and only for the elements it knows are sticky. So the editor patches it, for
+ * exactly as long as a bar is mounted, and puts it back on the way out.
+ *
+ * Two things come out of one scan:
+ *   - each detected element gets an inline `top: var(<bar height token>, <px>)`
+ *     — plus its own original offset, for a second tier — so the theme's whole
+ *     top stack pins UNDER the bar instead of behind it, gaps intact;
+ *   - the tallest detected top BAND is published as `--kywi-editor-sticky-offset`
+ *     on `documentElement`, which `useChromeFlip` (use-chrome-flip.ts) adds to
+ *     the strip it clamps in-place chrome below — otherwise the chrome clears
+ *     the editor's bar only to land inside the site's nav (kywi-cms#122 pinned
+ *     it at y≈62 into a nav band of 46–111).
+ *
+ * Lives in `scope/` rather than `admin/layout-editor/` because BOTH bars need
+ * it and only one of them is the layout editor: `scope/inline-editing.tsx`
+ * (the browse toolbar) is a public-site module, and `admin/` already imports
+ * `scope/` while nothing in `scope/` imports `admin/`. Putting it the other way
+ * round would invert that.
+ */
+/**
+ * Height of the tallest site-authored top band the editor offset, in px, on
+ * `documentElement` — 0/absent when the page has none.
+ *
+ * Published as an INLINE custom property deliberately, not a stylesheet rule:
+ * `useChromeFlip` reads it on every scroll frame, and
+ * `documentElement.style.getPropertyValue()` is a CSSOM read of a declaration
+ * this module wrote, not a `getComputedStyle` that can force a style recalc.
+ * It is an editor-published measurement, not a theme token — a theme has
+ * nothing useful to say about it.
+ */
+export const STICKY_OFFSET_VAR = '--kywi-editor-sticky-offset';
+/** Height token of the edit-mode bar (`.kywi-overlay-toolbar`), editor.css. */
+export const EDIT_BAR_HEIGHT_VAR = '--kywi-overlay-bar-height';
+/**
+ * The literal behind {@link EDIT_BAR_HEIGHT_VAR}, for the `var()` fallback.
+ *
+ * Kept beside the token rather than only in CSS because a `var()` whose token
+ * is undefined resolves to the property's INITIAL value, and `top`'s initial
+ * value is `auto` — i.e. the patch below would un-stick every header it touched
+ * rather than merely mis-offsetting it. See {@link applyStickyOffset}.
+ */
+export const EDIT_BAR_HEIGHT_PX = 46;
+/** Height token of the browse-mode bar (`.kywi-edit-toolbar`), editor.css. */
+export const BROWSE_BAR_HEIGHT_VAR = '--kywi-browse-bar-height';
+/** The literal behind {@link BROWSE_BAR_HEIGHT_VAR} — see {@link EDIT_BAR_HEIGHT_PX}. */
+export const BROWSE_BAR_HEIGHT_PX = 44;
+/**
+ * Marks an element the editor is currently holding an offset on. Public so a
+ * test (or a confused developer looking at the DOM) can tell an editor-applied
+ * `top` from one the site authored, and so a second `applyStickyOffset` can
+ * never capture an already-patched value as the "original".
+ */
+export const STICKY_PATCH_ATTR = 'data-kywi-sticky-offset';
+/**
+ * How far from y=0 still counts as "anchored to the top of the viewport" — the
+ * FIRST tier of a theme's sticky stack, offset by exactly one bar height.
+ *
+ * Not just `top: 0`: a sub-pixel or `0.5px` theme value is the same intent, and
+ * `top: -1px` is a widely-copied trick for detecting the stuck state with an
+ * IntersectionObserver sentinel.
+ */
+export const STICKY_TOP_THRESHOLD_PX = 4;
+/**
+ * How far down a SECOND sticky tier may be anchored and still be treated as
+ * part of the same top stack (kywi-cms#146 fix round).
+ *
+ * A theme that stacks — `header { top: 0 }` with a sub-nav at `top: 64px`, the
+ * pattern behind every docs site's category bar — used to be half-patched: the
+ * header moved to 46 and the sub-nav did not, so a 65px-tall header now covered
+ * 46–111 and ate the sub-nav's 64–104 outright. Leaving the second tier alone
+ * was not neutral; it was an overlap the PATCH created, and the earlier claim
+ * that such an element "is already positioned relative to something" only holds
+ * while the thing it is positioned relative to has not moved.
+ *
+ * So the whole stack shifts by the same delta — `calc(var(<bar>) + <original>)`
+ * — which preserves every gap the theme built rather than flattening them.
+ *
+ * 200px is the ceiling because it is comfortably taller than any real header +
+ * sub-nav pair and comfortably shorter than "parked in the middle of the page":
+ * a sticky filter panel at `top: 320px` is anchored to page content, not to the
+ * top of the viewport, and moving it would be the very break this avoids.
+ */
+export const STICKY_SECOND_TIER_MAX_PX = 200;
+/**
+ * Below this in either dimension an element is a probe, not chrome. Next's dev
+ * overlay parks a 1×1 `position: fixed; top: 0` div at (-1, -1) on every page,
+ * and giving it an inline `top` is pure noise in the DOM the owner inspects.
+ */
+const MIN_PATCHABLE_PX = 8;
+/**
+ * A top-anchored element taller than this share of the viewport is a drawer, a
+ * scrim or a full-height sidebar — not a band across the top of the page — so
+ * it must not drag the chrome clamp down with it. It still gets the offset (it
+ * is still covered by the bar); it just does not define a band to clamp below.
+ */
+const MAX_BAND_VIEWPORT_FRACTION = 0.25;
+/**
+ * …but a band no taller than this is a header whatever the viewport is doing,
+ * so it publishes even when the fraction above says otherwise (kywi-cms#146 fix
+ * round).
+ *
+ * The fraction alone is a trap on a short window: a nav whose links wrap to two
+ * rows measures ~170px, and at a 640px-tall viewport (a laptop with devtools
+ * docked, or the editor's own responsive preview) a quarter is 160 — so the
+ * band silently published as 0 while the elements stayed patched, and the
+ * chrome clamped straight back INTO the nav, which is the exact collision the
+ * band exists to end. The two rules are a UNION, never an intersection: a band
+ * that is short in ABSOLUTE terms or short RELATIVE to the viewport publishes;
+ * only one that is both tall and viewport-dominating is read as a drawer. A
+ * 700px full-height drawer fails both at any viewport, which is the case the
+ * fraction was written for and still catches.
+ */
+const ALWAYS_A_BAND_MAX_PX = 200;
+/**
+ * The editor's OWN top-anchored chrome, which must never be offset: these
+ * elements ARE the bars being cleared, and pushing them down by their own
+ * height would walk them off the screen one mode-switch at a time.
+ *
+ * An explicit list, not a `[class*="kywi-overlay"]` wildcard, for one specific
+ * reason: `.kywi-overlay-shell` is `display: contents` and WRAPS the whole
+ * in-place canvas, i.e. the site's own sections and modules. A wildcard would
+ * match it, and `closest()` would then exclude every sticky element the owner
+ * is actually editing. `[data-kywi-editor-chrome]` is the extension point —
+ * new chrome marks itself with it (the attribute already exists for the
+ * inline-edit exclusions) rather than growing this list.
+ */
+const EDITOR_CHROME_SELECTOR = [
+    '[data-kywi-editor-chrome]',
+    '.kywi-edit-toolbar',
+    '.kywi-overlay-toolbar',
+    '.kywi-overlay-rail',
+    '.kywi-overlay-dialog-host',
+    '.kywi-editor-template-overlay',
+    '.kywi-admin-shell',
+    '.kywi-ip-chrome',
+    '.kywi-ip-chip',
+].join(',');
+/**
+ * Keyed by element rather than carried on the handle so a patch applied while
+ * another is somehow still live restores the SITE's value, never the previous
+ * patch's `var(...)`. React unmounts the outgoing bar's effect before it runs
+ * the incoming one's, so browse→edit already swaps cleanly; this is the belt to
+ * that braces, and it is a WeakMap so a detached element is not retained.
+ */
+const originalTops = new WeakMap();
+const NOOP_PATCH = {
+    elements: [],
+    bandPx: 0,
+    revert() { },
+};
+/** True for an element the editor's own chrome owns (or lives inside). */
+function isEditorChrome(el) {
+    return el.closest(EDITOR_CHROME_SELECTOR) !== null;
+}
+/**
+ * The inline `top` the editor writes for one tier of a theme's sticky stack.
+ *
+ * The token, not its resolved px: `var()` in an inline style resolves at
+ * used-value time, so a bar height that changes (a theme override, a media
+ * query) moves everything this patched without a re-scan. The fallback is
+ * mandatory — see {@link applyStickyOffset}'s `fallbackPx`.
+ *
+ * A pure function so the exact declaration can be pinned by a test: happy-dom's
+ * CSS value parser understands neither `calc(var(…))` nor a `var()` fallback
+ * written with a space after the comma, and silently DROPS the whole
+ * declaration in both cases, so a DOM read-back cannot see this string. Which is
+ * also why the comma is written tight — browsers treat `var(--x,4px)` and
+ * `var(--x, 4px)` identically, and the tight form is the one that survives the
+ * test environment, keeping the first-tier DOM assertions (and the integration
+ * ones in inline-editing / overlay-editor) real rather than vacuous.
+ *
+ * @param shift how far down the stack this tier sits — 0 for the first.
+ */
+export function stickyTopValue(barHeightVar, fallbackPx, shift) {
+    const bar = `var(${barHeightVar},${fallbackPx}px)`;
+    return shift === 0 ? bar : `calc(${bar} + ${shift}px)`;
+}
+/**
+ * True when a sticky element pins against the VIEWPORT rather than inside some
+ * ancestor's scroll pane.
+ *
+ * Only ever asked of a second-tier candidate, and it is what keeps a sticky
+ * table head at `top: 40px` inside an `overflow: auto` pane out of the patch:
+ * that element's `top` is measured from its scrollport, not from the top of the
+ * window, so the editor's bar never covers it and shifting it by a bar height
+ * would push it down inside its own pane for no reason. The overflow test is
+ * the same one the browser applies — any `overflow-y` other than `visible` or
+ * `clip` makes that ancestor the scrollport (which is also why `overflow-x:
+ * hidden`, whose `overflow-y` computes to `auto`, famously "breaks" sticky).
+ */
+function pinsToViewport(el, view) {
+    const doc = el.ownerDocument;
+    for (let parent = el.parentElement; parent && parent !== doc.body && parent !== doc.documentElement; parent = parent.parentElement) {
+        const overflowY = view.getComputedStyle(parent).overflowY;
+        if (overflowY && overflowY !== 'visible' && overflowY !== 'clip')
+            return false;
+    }
+    return true;
+}
+/**
+ * How far down the top stack this element is anchored — 0 for the first tier,
+ * its own `top` in px for a second tier — or null when it is not part of the
+ * stack at all and must be left exactly as the theme wrote it.
+ */
+function topAnchorOf(el, view) {
+    const style = view.getComputedStyle(el);
+    const position = style.position;
+    // `-webkit-sticky` still shows up in older Safari's computed style.
+    const sticky = position === 'sticky' || position === '-webkit-sticky';
+    if (!sticky && position !== 'fixed')
+        return null;
+    // A px length and nothing else. `top: auto` — a sticky element with no
+    // vertical anchor, which never pins to the top at all — is the obvious
+    // rejection, but the one that matters is a PERCENTAGE: `.kywi-selfid-modal`
+    // is `position: fixed; top: 50%` (centred, then pulled back by a transform),
+    // and a bare `parseFloat` reads that as "50", i.e. a second tier to shift by
+    // a bar height. A resolved `top` is normally px, but it is a percentage for
+    // an element the box tree has no used value for, and half a viewport is a
+    // second tier on any short window. Anchoring on the UNIT rather than the
+    // number rejects both without a special case.
+    const match = /^(-?[0-9]*\.?[0-9]+)px$/.exec(style.top.trim());
+    if (!match)
+        return null;
+    const top = Number.parseFloat(match[1]);
+    if (!Number.isFinite(top))
+        return null;
+    if (Math.abs(top) <= STICKY_TOP_THRESHOLD_PX)
+        return 0;
+    // Below the top, but within one header stack of it: a second tier, shifted by
+    // the same delta so the theme's own gap survives (see
+    // {@link STICKY_SECOND_TIER_MAX_PX}). Negative values beyond the threshold
+    // are scroll tricks, not tiers, and are left alone.
+    if (top < 0 || top > STICKY_SECOND_TIER_MAX_PX)
+        return null;
+    if (sticky && !pinsToViewport(el, view))
+        return null;
+    return top;
+}
+/**
+ * The height this element contributes to the clamp band, or 0 if it is not a
+ * band: it has to cross the viewport's horizontal midline (a left sidebar or a
+ * corner badge does not) and read as a header rather than a drawer (see
+ * {@link ALWAYS_A_BAND_MAX_PX}).
+ *
+ * The band a tier is responsible for is measured from the TOP of the stack —
+ * `shift + height`, not the element's own height — because that is the strip
+ * the chrome has to clear: a sub-nav at `top: 64px` and 40px tall leaves the
+ * chrome nothing until 104.
+ */
+function bandHeightOf(el, view, shift) {
+    const { height, left, right } = el.getBoundingClientRect();
+    const midX = view.innerWidth / 2;
+    if (left > midX || right < midX)
+        return 0;
+    const band = shift + height;
+    if (band > ALWAYS_A_BAND_MAX_PX && band > view.innerHeight * MAX_BAND_VIEWPORT_FRACTION)
+        return 0;
+    return band;
+}
+/**
+ * Offset every site-authored top-anchored element by one bar height, for as
+ * long as the returned patch is held.
+ *
+ * ONE scan, at bar mount. A `MutationObserver` is deliberately not part of
+ * this: it would have to re-run `getComputedStyle` on every subtree the site
+ * (or the editor's own canvas) inserts for the whole session, and the elements
+ * this exists for — the site's header — are in the document before the editor
+ * mounts. **Accepted limitation:** a sticky bar that MOUNTS mid-session (a
+ * cookie banner that appears on a timer, a mobile menu that is `display: none`
+ * at editor open, a site header rendered by a client-only component that has
+ * not hydrated yet) is not offset, and pins under the bar as it does today.
+ * Re-entering edit mode re-scans.
+ *
+ * The measured band IS re-published when a patched element resizes (a header
+ * whose nav wraps to two rows on a narrower viewport, or the responsive-preview
+ * switch), via a `ResizeObserver` — the same reason `useChromeFlip` grew one in
+ * kywi-cms#132's fix round: no window event fires for that.
+ *
+ * @param barHeightVar the CSS custom property holding the mounted bar's height
+ *   — {@link EDIT_BAR_HEIGHT_VAR} or {@link BROWSE_BAR_HEIGHT_VAR}. Passed as a
+ *   token rather than a number so a theme that re-declares the token moves the
+ *   offset with the bar, and so nothing here has to re-parse px.
+ * @param fallbackPx that token's literal — {@link EDIT_BAR_HEIGHT_PX} or
+ *   {@link BROWSE_BAR_HEIGHT_PX} — emitted as the `var()` fallback. NOT
+ *   optional, because the case it covers is the default one on a generated app:
+ *   both tokens are declared in `editor.css`, which a scaffold loads LAZILY
+ *   (behind `next/dynamic`, only once the overlay editor opens — see
+ *   `create-kywi-app/lib/templates.mjs`), so the BROWSE bar renders with
+ *   neither token defined. A fallback-less `var()` there resolves to `top`'s
+ *   initial value, `auto`, and a sticky header with `top: auto` stops sticking
+ *   at all — strictly worse than the overlap this fixes, and for the whole
+ *   session. `site/styles.css` declares both on `:root` for the same reason
+ *   (belt to this brace); the fallback is what holds if a host ships neither
+ *   stylesheet.
+ */
+export function applyStickyOffset(barHeightVar, fallbackPx) {
+    if (typeof document === 'undefined' || typeof window === 'undefined')
+        return NOOP_PATCH;
+    const body = document.body;
+    if (!body)
+        return NOOP_PATCH;
+    const patched = [];
+    /** Each patched element's tier depth, for the band it is responsible for. */
+    const shifts = new Map();
+    for (const el of Array.from(body.querySelectorAll('*'))) {
+        if (el.hasAttribute(STICKY_PATCH_ATTR))
+            continue;
+        if (isEditorChrome(el))
+            continue;
+        const shift = topAnchorOf(el, window);
+        if (shift === null)
+            continue;
+        const { width, height } = el.getBoundingClientRect();
+        if (width < MIN_PATCHABLE_PX || height < MIN_PATCHABLE_PX)
+            continue;
+        originalTops.set(el, {
+            value: el.style.getPropertyValue('top'),
+            priority: el.style.getPropertyPriority('top'),
+        });
+        el.setAttribute(STICKY_PATCH_ATTR, '');
+        // A second tier keeps its own offset ON TOP of the bar, so the theme's
+        // stack arrives intact one bar lower rather than collapsing onto itself.
+        el.style.setProperty('top', stickyTopValue(barHeightVar, fallbackPx, shift));
+        patched.push(el);
+        shifts.set(el, shift);
+    }
+    const root = document.documentElement;
+    const publishBand = () => {
+        let band = 0;
+        for (const el of patched)
+            band = Math.max(band, bandHeightOf(el, window, shifts.get(el) ?? 0));
+        // Rounded up: a fractional band rounded DOWN would clamp chrome half a
+        // pixel INTO the nav, which is the collision this exists to end.
+        const px = Math.ceil(band);
+        if (px > 0)
+            root.style.setProperty(STICKY_OFFSET_VAR, `${px}px`);
+        // Same gate as `revert` below, for the same reason: a scan that patched
+        // NOTHING has no band of its own and must not clear the live patch's. Two
+        // bars overlapping by a frame is the ordinary case (browse → edit), and
+        // without this the second one's empty scan wipes the first one's band and
+        // the chrome clamps back into the nav.
+        else if (patched.length > 0)
+            root.style.removeProperty(STICKY_OFFSET_VAR);
+        return px;
+    };
+    const bandPx = publishBand();
+    // Feature-detected, exactly as in use-chrome-flip.ts: happy-dom ships an
+    // inert stub and older hosts have none, so a missing observer degrades to
+    // "the band is what it measured at mount" instead of throwing.
+    const ResizeObserverCtor = window
+        .ResizeObserver;
+    let observer = null;
+    if (patched.length > 0 && typeof ResizeObserverCtor === 'function') {
+        observer = new ResizeObserverCtor(() => { publishBand(); });
+        for (const el of patched)
+            observer.observe(el);
+    }
+    let reverted = false;
+    return {
+        elements: patched,
+        bandPx,
+        revert() {
+            if (reverted)
+                return;
+            reverted = true;
+            observer?.disconnect();
+            for (const el of patched) {
+                el.removeAttribute(STICKY_PATCH_ATTR);
+                const original = originalTops.get(el);
+                originalTops.delete(el);
+                if (original && original.value !== '') {
+                    el.style.setProperty('top', original.value, original.priority);
+                }
+                else {
+                    el.style.removeProperty('top');
+                }
+                // An element that carried no `style` attribute before must carry none
+                // after — "restored exactly" has to include leaving no empty husk
+                // behind for the next reader of the DOM to wonder about.
+                if (el.getAttribute('style') === '')
+                    el.removeAttribute('style');
+            }
+            // Only a patch that could have published the band may clear it — the
+            // same reasoning as restoring `top` from the recorded original rather
+            // than blindly: a revert must never undo something it did not do.
+            if (patched.length > 0) {
+                root.style.removeProperty(STICKY_OFFSET_VAR);
+                if (root.getAttribute('style') === '')
+                    root.removeAttribute('style');
+            }
+        },
+    };
+}
+/**
+ * The published sticky band, in px — 0 when the page has no offset top band.
+ *
+ * Cheap enough for a scroll handler: this reads the inline declaration
+ * {@link applyStickyOffset} wrote, so unlike `getComputedStyle` it cannot force
+ * a style recalculation.
+ */
+export function readStickyOffsetPx() {
+    if (typeof document === 'undefined')
+        return 0;
+    const raw = document.documentElement.style.getPropertyValue(STICKY_OFFSET_VAR);
+    const parsed = Number.parseFloat(raw);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}
+//# sourceMappingURL=sticky-offset.js.map

package/dist/scope/sticky-offset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sticky-offset.js","sourceRoot":"","sources":["../../src/scope/sticky-offset.ts"],"names":[],"mappings":"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"}

package/dist/site/styles.css

@@ -701,6 +701,32 @@
  * (renders nothing for non-editors), so these rules only ever apply for an
  * authenticated admin who opted into edit mode. */
 
+/* Both front-of-site bar heights, declared HERE as well as in editor.css.
+ *
+ * They are an ecosystem contract — documented for theme authors in
+ * packages/core/README.md ("Sticky site headers and the editor's bars"), read
+ * by `scope/sticky-offset.ts` to offset a theme's sticky header for an editing
+ * session (kywi-cms#146), and offered to a theme's own `.kywi-frontend-edit--*`
+ * rules — so a page that can show a bar has to have them defined.
+ *
+ * editor.css alone does not deliver that. A generated app pulls the admin
+ * design system in behind `next/dynamic`, so it is loaded only once someone
+ * OPENS the overlay editor and is deliberately absent from the public browse
+ * bundle (create-kywi-app/lib/templates.mjs) — the exact lazy-load trap
+ * kywi-cms#144 hit from the other side. The BROWSE bar ships in this
+ * stylesheet's own bundle and renders with editor.css nowhere in the document,
+ * so anything resolving these tokens then would get nothing at all. Every
+ * public page loads THIS sheet, so declaring them here closes that window.
+ *
+ * The values are identical to editor.css's (44/46), which is what makes two
+ * declaration sites safe: whichever sheet a host loads last, `:root` resolves
+ * to the same number. A theme that overrides either token still wins by loading
+ * after core's stylesheet, as it already had to. */
+:root {
+  --kywi-browse-bar-height: 44px;
+  --kywi-overlay-bar-height: 46px;
+}
+
 .kywi-edit-toolbar {
   position: fixed;
   top: 0;
@@ -710,7 +736,7 @@
   display: flex;
   align-items: center;
   gap: var(--_kywi-sm, 0.5rem);
-  height: 44px;
+  height: var(--kywi-browse-bar-height, 44px);
   padding: 0 var(--kywi-spacing-md, 1rem);
   background: #0f172a;
   color: #f8fafc;
@@ -718,8 +744,20 @@
   box-shadow: 0 1px 4px rgba(0, 0, 0, 0.25);
 }
 /* Push the page down while the browse-mode bar is visible so it never overlaps
- * the site's own header (class toggled by KywiEditToolbar). */
-.kywi-frontend-edit--browsing body { padding-top: 44px; }
+ * the site's own header (class toggled by KywiEditToolbar, which puts it on
+ * `documentElement`).
+ *
+ * This rule targets the CLASS-CARRYING element and uses the bar's own token,
+ * so it is byte-for-byte the same declaration editor.css makes — deliberately,
+ * because a site that mounts the overlay editor loads BOTH sheets. It used to
+ * read `.kywi-frontend-edit--browsing body`, a different element, and two
+ * different elements each padded 44px pushed the page down 88px for a 44px
+ * bar: the seam of body background above the site's nav in kywi-cms#146(1)
+ * (reproduced on the reference app — header at y=88, bar 0–44). Two identical
+ * declarations collapse; two different ones stack. The `44px` fallback keeps
+ * this correct for a host that ships the browse toolbar without ever importing
+ * the editor, which is the only reason this copy exists at all. */
+.kywi-frontend-edit--browsing { padding-top: var(--kywi-browse-bar-height, 44px); }
 .kywi-edit-toolbar-spacer { flex: 1; }
 .kywi-edit-toolbar-title { font-weight: 600; }
 .kywi-edit-toolbar-status {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kywi-software/core",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Kywi CMS core — schema generator, REST API, and admin UI for Next.js.",
   "type": "module",
   "license": "AGPL-3.0-only",