@homepages/template-kit 0.8.1-dev-20260718224903 → 0.9.0-dev-20260719205406

package/CHANGELOG.md

@@ -1,9 +1,37 @@
 # @homepages/template-kit
 
-## 0.8.1-dev-20260718224903
+## 0.9.0-dev-20260719205406
+
+### Minor Changes
+
+- 5030122: The authoring ESLint rules move out of `@homepages/template-kit` into the new
+  `@homepages/eslint-plugin-template`, which takes the kit as a peerDependency.
+
+  The kit's `./eslint` subpath is removed with no shim. Replace
+
+      import kit from "@homepages/template-kit/eslint";
+
+  with
+
+      import kit from "@homepages/eslint-plugin-template";
+
+  and add `@homepages/eslint-plugin-template` to devDependencies. Rule ids are
+  unchanged — the namespace is still `template-kit/`, so any rule-specific
+  `eslint-disable` comment and any `rules` override keep working.
+
+  The kit also gains a `./rules` subpath exposing the rule-id registry, and its
+  `./ssr` entry now exports the `"use client"` resolver (`isClientFile`,
+  `resolveImportedFile`, `resetClientFileCache`) that the plugin's rules consume
+  over the peer edge.
 
 ### Patch Changes
 
+- 10f53a7: `template-kit dev`'s canvas hover/select ring no longer overflows the page's
+  x-axis when hovering a full-bleed section (e.g. a hero or header flush with
+  both page edges). The ring's geometry inflated the target's bounding rect by
+  a fixed offset on every side with no bound, so a rect already touching the
+  document edge pushed the ring 2px past it, growing the iframe's horizontal
+  scroll extent. The ring box is now clamped to `[0, containerWidth]`.
 - f3f6d70: `template-kit check` no longer fails on a tsconfig `paths` alias (e.g.
   `"@/platform/*": ["../platform/*"]`) or on a section whose contract files
   share a module large enough for esbuild to code-split. Previously the
@@ -43,6 +71,7 @@
   (`ci/build-css.ts`) has always assembled it. `fontFaces` is still prepended
   to the final bundle separately, since a nested `@import url(...)` doesn't
   hoist out of an imported partial.
+- 2e36277: Escape `>` and `&` as well as `<` in the dev server's island map, matching the escaping used by published pages.
 - 1c4c7dd: Island hydration is now nesting-safe: `hydrateIslands` skips any island marker
   nested inside another marker, so an island can render another island without the
   child being hydrated twice (once by its parent root, once independently). Enables

package/README.md

@@ -17,7 +17,7 @@ The fastest way to start is the workspace scaffolder — it creates a workspace
 working starter template and the full toolchain already wired:
 
 ```bash
-npm create homepages-workspace <name>
+npm create @homepages/workspace <name>
 cd <name>
 npm install
 npm run dev        # preview the starter; the island hydrates
@@ -97,7 +97,7 @@ Full contract: **[guide/primitives.md](guide/primitives.md)**.
 | `@homepages/template-kit/browser` | Browser helpers for published pages (site config, signed ingest) |
 | `@homepages/template-kit/styles.css` | The global Tailwind preamble: the breakpoint ladder, the spacing base unit, the motion defaults, kit source registration |
 | `@homepages/template-kit/base.css` | Cascade-layer order, the three reset gaps Tailwind's preflight leaves, `.tr-section`, and the motion tokens |
-| `@homepages/template-kit/eslint` | ESLint flat-config preset |
+| `@homepages/eslint-plugin-template` | ESLint flat-config preset (its own package) |
 | `@homepages/template-kit/tsconfig` | tsconfig preset (`"extends"`) |
 
 One specifier for everything you write a section against. The exceptions are

package/dist/canvas-core/chrome-css.d.ts

@@ -0,0 +1,24 @@
+import { MarkerAttrs } from "./types.js";
+//#region src/canvas-core/chrome-css.d.ts
+/**
+ * Custom properties the chrome CSS reads but deliberately does not declare —
+ * the host must set them on the iframe document's root element. This is the
+ * host's obligation, not a suggestion: an adapter that skips one leaves the
+ * declared inline fallback in force, which renders plausibly and silently
+ * wrong rather than failing.
+ *
+ * - `--we-panel-w`: the floating panel's measured width, mirrored onto the
+ *   iframe root so the page card's right padding clears it. Unset, the card
+ *   lays out against the 436px base-width fallback and drifts out of alignment
+ *   whenever the real panel is any other width.
+ * - `--we-content`: the host's interior scaling unit, mirrored in so hidden-tab
+ *   chrome scales with the rest of the UI. Unset, it pins to the 1px fallback
+ *   and the tabs stay laptop-sized while every surrounding surface scales.
+ *
+ * Anything added here must actually be read by the kernel; the token test
+ * fails on a stale entry.
+ */
+declare const HOST_INJECTED_PROPERTIES: readonly ["--we-panel-w", "--we-content"];
+declare function buildChromeCss(markers: MarkerAttrs): string;
+//#endregion
+export { HOST_INJECTED_PROPERTIES, buildChromeCss };

package/dist/canvas-core/chrome-css.js

@@ -0,0 +1,403 @@
+import { TAB_TUCK } from "./hidden-tabs.js";
+
+//#region src/canvas-core/chrome-css.ts
+/**
+* Custom properties the chrome CSS reads but deliberately does not declare —
+* the host must set them on the iframe document's root element. This is the
+* host's obligation, not a suggestion: an adapter that skips one leaves the
+* declared inline fallback in force, which renders plausibly and silently
+* wrong rather than failing.
+*
+* - `--we-panel-w`: the floating panel's measured width, mirrored onto the
+*   iframe root so the page card's right padding clears it. Unset, the card
+*   lays out against the 436px base-width fallback and drifts out of alignment
+*   whenever the real panel is any other width.
+* - `--we-content`: the host's interior scaling unit, mirrored in so hidden-tab
+*   chrome scales with the rest of the UI. Unset, it pins to the 1px fallback
+*   and the tabs stay laptop-sized while every surrounding surface scales.
+*
+* Anything added here must actually be read by the kernel; the token test
+* fails on a stale entry.
+*/
+const HOST_INJECTED_PROPERTIES = ["--we-panel-w", "--we-content"];
+function buildChromeCss(markers) {
+	return `
+  html, body { background: transparent; }
+  body {
+    --we-page-radius: 14px;
+    margin: 0;
+    /* Padding aligns the page card with the floating panel and centers
+       it in the visible canvas area. Top/bottom match the panel's
+       top-5/bottom-5 inset (20px). Left is 20px. The right constant
+       (40px) covers the panel's right-5 inset (20px) plus an equal
+       20px gap, giving symmetric breathing room on both sides of the
+       card between the canvas's left edge and the panel's left edge.
+       Fallback 436px matches the panel's base CSS width. */
+    padding: 20px calc(var(--we-panel-w, 436px) + 40px) 20px 20px;
+    /* Body is the container for the auto-fit calc on #we-zoom. With
+       container-type: inline-size, descendants resolve 100cqw to the
+       body's content-box width — exactly the width we want the card
+       to scale into. */
+    container-type: inline-size;
+    position: relative;
+    display: flex;
+    justify-content: center;
+    align-items: flex-start;
+    min-height: 100%;
+    overflow: auto;
+    color: #14180F;
+    font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+    /* Dotted canvas surface. background-attachment: local makes the grid
+       scroll together with the page card so the canvas + website read as
+       one scene being panned, not a card sliding over a fixed grid. */
+    background-image: radial-gradient(rgba(20, 18, 13, 0.13) 1px, transparent 1.2px);
+    background-size: 20px 20px;
+    background-position: 10px 10px;
+    background-attachment: local;
+  }
+  /* Hide the native scrollbar on whichever element ends up being the
+     scroll container. Some browsers route the scroll to the root
+     element (html) rather than body, so cover both. Wheel / trackpad /
+     keyboard and programmatic scrollTo still work. */
+  html, body { scrollbar-width: none; -ms-overflow-style: none; }
+  html::-webkit-scrollbar,
+  body::-webkit-scrollbar { width: 0; height: 0; display: none; }
+  #we-zoom {
+    /* Auto-fit + manual zoom, declarative.
+       Two-slope formula: below ~1472px canvas (≤1536px viewport) slope 1
+       (0.8×) keeps the card at 80% of canvas width — the original
+       breathing-room factor. Above that breakpoint slope 2 (0.214×+0.600)
+       takes over, growing sub-linearly so the percentage of canvas the
+       card occupies shrinks on wider monitors while absolute pixel width
+       keeps growing. At a 1920px monitor this yields ~12.5% smaller than
+       the old native-1440px cap, restoring the birds-eye view. The outer
+       min(1,...) still prevents upscaling beyond native width.
+
+       --user-zoom is the manual multiplier the toolbar writes (1.0 = at
+       fit / "100%"). The browser recomputes on every resize — no host JS
+       needed.
+
+       Scale via the zoom property, NOT transform: scale(). A transform
+       only shrinks the PAINT — the layout box keeps the full unscaled
+       1440px footprint, so the body (scroll container) reserves space the
+       shrunken page no longer fills and the canvas scrolls far past the
+       bottom. zoom scales the layout box too, so scrollHeight tracks the
+       visible page exactly. getBoundingClientRect() reports visual coords
+       under either, so overlay-ring + scroll-into-view math in
+       iframe-canvas.tsx is unaffected; flex justify-content:center
+       re-centers the smaller box, so no transform-origin is needed. */
+    --user-zoom: 1;
+    --fit-zoom: min(0.9, min(
+      calc(0.72 * 100cqw / 1440px),
+      calc(0.1926 * 100cqw / 1440px + 0.540)
+    ));
+    zoom: calc(var(--fit-zoom) * var(--user-zoom));
+    transition: zoom 150ms cubic-bezier(0.4, 0, 0.2, 1);
+    flex-shrink: 0;
+    /* Positioned + stacked above #we-htabs (z-index:1) so the page's
+       drop-shadow falls over the hidden-tab's inner edge, nestling it against
+       the frame. #we-chrome-overlay (z-index:100) stays above. */
+    position: relative;
+    z-index: 2;
+  }
+  #we-page {
+    width: 1440px;
+    overflow: hidden;
+    border-radius: var(--we-page-radius);
+    background: #f5f3ee;
+    padding: 0;
+    box-shadow:
+      0 1px 0 rgba(20,18,13,0.06),
+      0 2px 6px -2px rgba(20,18,13,0.10),
+      0 12px 28px -8px rgba(20,18,13,0.18),
+      0 32px 64px -20px rgba(20,18,13,0.28);
+  }
+
+  /* Section wrapper -- structure only. No selection chrome here;
+     rings are painted by #we-chrome-overlay (see below). Zero margin
+     + padding means sections butt edge-to-edge, matching publisher. */
+  [${markers.sectionInstanceId}] {
+    position: relative;
+    margin: 0;
+    padding: 0;
+    cursor: pointer;
+    display: grid;
+    grid-template-rows: 1fr;
+    /* Reveal transition — governs the hidden→visible direction because
+       CSS uses the destination state's transition property. Spring easing
+       gives a snappy entrance. */
+    transition:
+      grid-template-rows 200ms cubic-bezier(0.16, 1, 0.3, 1),
+      opacity 180ms cubic-bezier(0.16, 1, 0.3, 1);
+  }
+
+  /* Section title pill -- lives in #we-chrome-overlay above the rings
+     so it straddles the top border without being covered. Sections
+     only; slots get the outline ring but no on-canvas label. */
+  .we-chrome-label {
+    position: absolute;
+    pointer-events: none;
+    z-index: 1;
+    background: rgba(229,184,50,0.95);
+    color: #282c32;
+    padding: 3px 8px;
+    border-radius: 4px;
+    font-size: 10.5px;
+    font-weight: 600;
+    line-height: 1;
+    letter-spacing: 0.02em;
+    text-transform: uppercase;
+    white-space: nowrap;
+    opacity: 0;
+    transform: translateY(calc(-50% - 4px)) scale(0.96);
+    transition:
+      opacity 60ms ease-in,
+      transform 60ms ease-in;
+  }
+  .we-chrome-label[data-active="true"] {
+    opacity: 1;
+    transform: translateY(-50%) scale(1);
+    transition:
+      opacity 130ms cubic-bezier(0.16, 1, 0.3, 1) 50ms,
+      transform 130ms cubic-bezier(0.16, 1, 0.3, 1) 50ms;
+  }
+
+  /* Hidden state -- collapse the section out of the page so it reflows shut.
+     The 0-height wrapper stays in flow as the anchor for the section's
+     floating edge tab (built in #we-htabs by iframe-canvas.tsx). See
+     docs/superpowers/specs/2026-06-02-hidden-section-edge-tabs-design.md. */
+  [${markers.sectionInstanceId}][data-hidden="true"] {
+    grid-template-rows: 0fr;
+    opacity: 0;
+    pointer-events: none;
+    /* Collapse transition — governs the visible→hidden direction.
+       Faster + accelerating so the hide feels decisive. */
+    transition:
+      grid-template-rows 150ms cubic-bezier(0.4, 0, 1, 1),
+      opacity 120ms cubic-bezier(0.4, 0, 1, 1);
+  }
+
+  /* Slot wrapper -- structure only. No outline here; the overlay
+     ring handles slot hover + selection too. */
+  [${markers.slotId}] {
+    position: relative;
+    cursor: pointer;
+  }
+
+  /* Slot-group container -- the gaps between grouped members (dividers,
+     padding) carry no slot id, so give the group container itself
+     the pointer cursor: the whole group reads as one clickable unit, and
+     the overlay ring outlines this container (see iframe-canvas.tsx). */
+  [${markers.slotGroup}],
+  [${markers.slotItem}] {
+    position: relative;
+    cursor: pointer;
+  }
+
+  /* Per-section body holds the API HTML.
+       1. position:relative gives the body a positioning context for any
+          body-scoped chrome or future body-only effects.
+       2. isolation:isolate SEALS the section's z-index hierarchy
+          inside this stacking context. Without it, any positioned
+          descendant with z-index > 0 (the header's sticky+z-50, a
+          dropdown's z-40, a sticky CTA) creates a stacking context
+          that escapes upward. Sections never need to know the
+          editor chrome exists -- internal z-index is unconstrained. */
+  /* overflow:hidden clips section content as the grid row collapses;
+     min-height:0 lets the grid child shrink below its content size.
+     Constraint: overflow:hidden is permanent (not just during animation), so
+     section content must not overflow its section-body boundary — sticky
+     elements, absolutely-positioned dropdowns, or shadows that bleed outside
+     the section edge will be silently clipped. Template sections are
+     self-contained blocks; this is safe in practice. */
+  .we-section-body { position: relative; isolation: isolate; overflow: hidden; min-height: 0; }
+
+  /* Chrome overlay -- sibling of #we-zoom inside the iframe body.
+     Sized to body's padding box; rings inside are absolutely
+     positioned by JS using getBoundingClientRect + window.scrollY/X.
+     Lives OUTSIDE #we-page so rings ride above the page's rounded
+     clip and any section's overflow:hidden. pointer-events:none so
+     clicks pass through to the section/slot underneath -- the
+     click resolver remains on doc.body. */
+  #we-chrome-overlay {
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+    z-index: 100;
+  }
+  .we-chrome-ring {
+    position: absolute;
+    pointer-events: none;
+    border: 2px solid transparent;
+    border-radius: 6px;
+    opacity: 0;
+    box-sizing: border-box;
+  }
+  /* Hover ring -- instant on cursor arrival, fades out on leave.
+     Position updates instantly (no top/left transition) so dragging
+     across elements never flickers. Ink stroke + white drop-shadow
+     halo (same trick as crop handles in globals.css) keeps the ring
+     readable on both light sections and dark ones like footer. */
+  .we-chrome-ring--hover {
+    border-color: rgba(15,42,34,0.85);
+    filter: drop-shadow(0 0 1px rgba(255,255,255,0.95));
+    transition: opacity 70ms ease-in;
+  }
+  .we-chrome-ring--hover[data-active="true"] {
+    opacity: 1;
+    transition: opacity 100ms cubic-bezier(0.16, 1, 0.3, 1);
+  }
+  /* Selection ring -- appears instantly (continuous with hover),
+     then morphs ink → gold. No position transition so resize
+     tracking stays tight. Same ink + white halo as hover. */
+  .we-chrome-ring--selection {
+    border-color: rgba(15,42,34,0.85);
+    filter: drop-shadow(0 0 1px rgba(255,255,255,0.95));
+    transform: scale(1);
+    box-shadow: none;
+    transition:
+      opacity 50ms ease-in,
+      border-color 160ms cubic-bezier(0.2, 0, 0, 1),
+      box-shadow 160ms cubic-bezier(0.2, 0, 0, 1);
+  }
+  .we-chrome-ring--selection[data-active="true"] {
+    opacity: 1;
+    /* Instant show on select; only border + glow animate */
+    transition:
+      opacity 0ms,
+      border-color 180ms cubic-bezier(0.2, 0, 0, 1),
+      box-shadow 180ms cubic-bezier(0.2, 0, 0, 1);
+  }
+  .we-chrome-ring--selection[data-kind="section"],
+  .we-chrome-ring--selection[data-kind="slot"] {
+    border-color: #E5B832;
+    filter: drop-shadow(0 0 1px rgba(255,255,255,0.95));
+    box-shadow: 0 0 0 1px rgba(229,184,50,0.25), 0 8px 24px -10px rgba(229,184,50,0.35);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .we-chrome-ring,
+    .we-chrome-label,
+    [${markers.sectionInstanceId}] {
+      transition: none !important;
+    }
+  }
+
+  /* Hidden-section edge tabs -------------------------------------
+     One dim chip-tab per hidden section, pinned to the page's left edge at
+     the collapsed wrapper's reflow seam. Built + positioned by
+     iframe-canvas.tsx (positionHiddenTabs); de-collided via placeTabs. Lives
+     in its own layer (sibling of #we-zoom) so it rides with page scroll and
+     stays a constant size at any zoom — like the rings. Colors are literals
+     (the iframe doesn't inherit dashboard Tailwind tokens). */
+  #we-htabs {
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+    z-index: 1;
+  }
+  .we-htab {
+    position: absolute;
+    transform: translateY(-50%);
+    display: flex;
+    align-items: center;
+    gap: calc(9 * var(--we-content, 1px));
+    height: calc(34 * var(--we-content, 1px));
+    padding: 0 calc(${12 + 16} * var(--we-content, 1px)) 0 calc(13 * var(--we-content, 1px));
+    background: #ffffff;
+    border: 1px solid #ebebe6;
+    border-radius: calc(9 * var(--we-content, 1px)) 0 0 calc(9 * var(--we-content, 1px));
+    box-shadow: 0 10px 24px -12px rgba(20,18,13,0.34);
+    color: #4a4842;
+    font: inherit;
+    cursor: pointer;
+    opacity: 1;
+    pointer-events: auto;
+    transition: transform 0.2s cubic-bezier(0.2,0.7,0.3,1),
+                border-color 0.18s, box-shadow 0.18s;
+  }
+  .we-htab-eye {
+    display: grid;
+    place-items: center;
+    flex: 0 0 auto;
+    color: #8a877e;
+    transition: color 0.18s;
+  }
+  .we-htab-eye svg { width: calc(14 * var(--we-content, 1px)); height: calc(14 * var(--we-content, 1px)); }
+  .we-htab-name {
+    font-size: calc(13 * var(--we-content, 1px));
+    font-weight: 600;
+    letter-spacing: -0.01em;
+    color: #14180F;
+    white-space: nowrap;
+  }
+  .we-htab:hover {
+    transform: translateY(-50%) scale(1.07);
+    border-color: rgba(15,42,34,0.5);
+    box-shadow: 0 13px 30px -12px rgba(15,42,34,0.45);
+  }
+  .we-htab:hover .we-htab-eye { color: #0F2A22; }
+  .we-htab:focus-visible {
+    outline: none;
+    transform: translateY(-50%) scale(1.07);
+    border-color: #0F2A22;
+    box-shadow: 0 0 0 3px #F3F6EF, 0 13px 30px -12px rgba(15,42,34,0.45);
+  }
+  /* Hover/focus swaps the eye-off glyph to the eye glyph in place — no width
+     change, no sliding label. Only one glyph is in flow at a time, so the eye
+     slot's grid keeps the shown glyph centered. */
+  .we-htab-eye-on { display: none; }
+  .we-htab:hover .we-htab-eye-off,
+  .we-htab:focus-visible .we-htab-eye-off { display: none; }
+  .we-htab:hover .we-htab-eye-on,
+  .we-htab:focus-visible .we-htab-eye-on { display: block; }
+
+  /* Render-error placeholder ------------------------------------- */
+  .we-render-error {
+    margin: 8px 0;
+    padding: 24px 16px;
+    border-radius: 6px;
+    border: 1px dashed #ebebe6;
+    background: #ffffff;
+    color: #8a877e;
+    font-size: 12.5px;
+  }
+  .we-render-error__title {
+    margin: 0;
+    color: #4a4842;
+    font-weight: 500;
+  }
+  .we-render-error__detail {
+    margin: 4px 0 0 0;
+    color: #b9b6ab;
+    font-size: 11.5px;
+  }
+
+/* Island interaction shield: a transparent click layer over an
+   island's live surface (editor.liveSurface) (e.g. the neighborhood map canvas). Present until
+   the surface's owner (slot/section) is the live selection; a click on it
+   falls through to the editor's resolver, which selects the owner. Once the
+   owner carries data-we-live the shield is removed, so the live surface (map
+   pan/zoom/markers) is interactive. z-index 1 sits on the map canvas's plane
+   (later in DOM than the canvas -> above it) but below the floating
+   .tr-nbhd__card (z-index 2), so the card's slots stay clickable. */
+.we-enh-shield {
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+  cursor: pointer;
+  background: transparent;
+}
+[data-we-live] .we-enh-shield { display: none; }
+
+/* Image slider: until the slider's \`images\` slot is the live selection, its
+   z-index:2 nav arrows would paint above the z-index:1 shield and stay
+   clickable, escaping the select-first gate. Disable them so the shield
+   catches the first click; restored once .tr-slider carries data-we-live.
+   Editor-only — deliberately not in published tokens.css. */
+.tr-slider:not([data-we-live]) .tr-slider__nav { pointer-events: none; }
+`;
+}
+
+//#endregion
+export { HOST_INJECTED_PROPERTIES, buildChromeCss };

package/dist/canvas-core/chrome.d.ts

@@ -0,0 +1,49 @@
+//#region src/canvas-core/chrome.d.ts
+/** How far outside the target the ring sits, in CSS px. With a 2px border-box
+ *  border, offset = 1 centers the stroke on the element's edge (1px outside,
+ *  1px overlapping inside) so the ring reads as flush. */
+declare const RING_OFFSET = 1;
+/** Inset of the section title pill from the target's left edge, in CSS px. */
+declare const LABEL_LEFT_INDENT = 12;
+interface RingRect {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}
+/**
+ * Ring geometry in document space: shift by scroll, inflate by `offset`.
+ *
+ * `containerWidth` clamps the horizontal edges. A section flush with both page
+ * edges would otherwise inflate `offset` px past each one and grow the
+ * document's horizontal scroll extent. Omitting it means unclamped: the app's
+ * overlay is wider than its page card and never overflows, so clamping it would
+ * silently shift every full-bleed ring. A consumer whose overlay is page-width
+ * opts in by passing one.
+ *
+ * Absence — not a sentinel value — is what selects the unclamped branch. A
+ * numeric stand-in for "unbounded" would make NaN (plausible out of a detached
+ * document's clientWidth arithmetic) take the clamped branch and yield NaN
+ * geometry, and would let Number.MAX_SAFE_INTEGER quietly enable the left floor.
+ */
+declare function ringBox(rect: RingRect, scroll: {
+  x: number;
+  y: number;
+}, offset: number, containerWidth?: number): RingRect;
+/** Whether an element has a box a ring can actually wrap. */
+declare function hasMeasurableRingBox(el: HTMLElement): boolean;
+declare function measureRingRect(el: HTMLElement): DOMRect;
+/**
+ * Move a ring in #we-chrome-overlay to sit `offset` px outside `target`.
+ *
+ * `kind` flips a data attribute so CSS can pick a color (gold for sections and
+ * slots). The hover ring leaves it unset and uses its own selector.
+ */
+declare function positionRing(ring: HTMLElement | null, target: HTMLElement | null, offset: number, kind?: "section" | "slot", containerWidth?: number): void;
+declare function applySelectionKind(ring: HTMLElement, kind: "section" | "slot"): void;
+declare function clearRing(ring: HTMLElement | null): void;
+declare function positionLabel(label: HTMLElement | null, target: HTMLElement | null, text: string): void;
+declare function clearLabel(label: HTMLElement | null): void;
+declare function cssEscape(value: string): string;
+//#endregion
+export { LABEL_LEFT_INDENT, RING_OFFSET, RingRect, applySelectionKind, clearLabel, clearRing, cssEscape, hasMeasurableRingBox, measureRingRect, positionLabel, positionRing, ringBox };

package/dist/canvas-core/chrome.js

@@ -0,0 +1,147 @@
+//#region src/canvas-core/chrome.ts
+/** How far outside the target the ring sits, in CSS px. With a 2px border-box
+*  border, offset = 1 centers the stroke on the element's edge (1px outside,
+*  1px overlapping inside) so the ring reads as flush. */
+const RING_OFFSET = 1;
+/** Inset of the section title pill from the target's left edge, in CSS px. */
+const LABEL_LEFT_INDENT = 12;
+/**
+* Ring geometry in document space: shift by scroll, inflate by `offset`.
+*
+* `containerWidth` clamps the horizontal edges. A section flush with both page
+* edges would otherwise inflate `offset` px past each one and grow the
+* document's horizontal scroll extent. Omitting it means unclamped: the app's
+* overlay is wider than its page card and never overflows, so clamping it would
+* silently shift every full-bleed ring. A consumer whose overlay is page-width
+* opts in by passing one.
+*
+* Absence — not a sentinel value — is what selects the unclamped branch. A
+* numeric stand-in for "unbounded" would make NaN (plausible out of a detached
+* document's clientWidth arithmetic) take the clamped branch and yield NaN
+* geometry, and would let Number.MAX_SAFE_INTEGER quietly enable the left floor.
+*/
+function ringBox(rect, scroll, offset, containerWidth) {
+	const rawLeft = rect.left + scroll.x - offset;
+	const rawRight = rawLeft + rect.width + 2 * offset;
+	const left = containerWidth === void 0 ? rawLeft : Math.max(0, rawLeft);
+	const right = containerWidth === void 0 ? rawRight : Math.min(containerWidth, rawRight);
+	return {
+		top: rect.top + scroll.y - offset,
+		left,
+		width: Math.max(0, right - left),
+		height: rect.height + 2 * offset
+	};
+}
+/** Whether an element has a box a ring can actually wrap. */
+function hasMeasurableRingBox(el) {
+	const rect = measureRingRect(el);
+	return rect.width > 0 && rect.height > 0;
+}
+function measureRingRect(el) {
+	const rect = el.getBoundingClientRect();
+	if (rect.width > 0 && rect.height > 0) return rect;
+	let top = Infinity;
+	let left = Infinity;
+	let right = -Infinity;
+	let bottom = -Infinity;
+	let found = false;
+	for (const child of Array.from(el.children)) {
+		const childRect = measureRingRect(child);
+		if (childRect.width <= 0 || childRect.height <= 0) continue;
+		found = true;
+		top = Math.min(top, childRect.top);
+		left = Math.min(left, childRect.left);
+		right = Math.max(right, childRect.right);
+		bottom = Math.max(bottom, childRect.bottom);
+	}
+	if (!found) return rect;
+	return new DOMRect(left, top, right - left, bottom - top);
+}
+/**
+* Move a ring in #we-chrome-overlay to sit `offset` px outside `target`.
+*
+* `kind` flips a data attribute so CSS can pick a color (gold for sections and
+* slots). The hover ring leaves it unset and uses its own selector.
+*/
+function positionRing(ring, target, offset, kind, containerWidth) {
+	if (!ring) return;
+	if (!target) {
+		ring.removeAttribute("data-active");
+		return;
+	}
+	const win = target.ownerDocument.defaultView;
+	if (!win) return;
+	const box = ringBox(measureRingRect(target), {
+		x: win.scrollX,
+		y: win.scrollY
+	}, offset, containerWidth);
+	ring.style.top = `${box.top}px`;
+	ring.style.left = `${box.left}px`;
+	ring.style.width = `${box.width}px`;
+	ring.style.height = `${box.height}px`;
+	if (kind) ring.setAttribute("data-kind", kind);
+	ring.setAttribute("data-active", "true");
+}
+function applySelectionKind(ring, kind) {
+	ring.removeAttribute("data-kind");
+	requestAnimationFrame(() => {
+		requestAnimationFrame(() => {
+			ring.setAttribute("data-kind", kind);
+		});
+	});
+}
+function clearRing(ring) {
+	if (!ring) return;
+	ring.removeAttribute("data-active");
+	ring.removeAttribute("data-kind");
+}
+function positionLabel(label, target, text) {
+	if (!label) return;
+	if (!target || !text) {
+		clearLabel(label);
+		return;
+	}
+	const win = target.ownerDocument.defaultView;
+	if (!win) return;
+	const rect = measureRingRect(target);
+	const wasActive = label.getAttribute("data-active") === "true";
+	const textChanged = label.textContent !== text;
+	label.textContent = text;
+	label.style.top = `${rect.top + win.scrollY}px`;
+	label.style.left = `${rect.left + win.scrollX + 12}px`;
+	if (wasActive && textChanged) {
+		label.removeAttribute("data-active");
+		label.offsetWidth;
+	}
+	label.setAttribute("data-active", "true");
+}
+function clearLabel(label) {
+	if (!label) return;
+	label.removeAttribute("data-active");
+	label.textContent = "";
+}
+function cssEscape(value) {
+	if (typeof CSS !== "undefined" && CSS.escape) return CSS.escape(value);
+	return value.replace(/[^a-zA-Z0-9_-]/g, (c) => `\\${c}`);
+}
+function resolveVisibleSlotEl(scope, slotId, markers) {
+	const nodes = scope.querySelectorAll(`[${markers.slotId}="${cssEscape(slotId)}"]`);
+	for (const el of Array.from(nodes)) if (hasMeasurableRingBox(el)) return el;
+	return nodes[0] ?? null;
+}
+function resolveItemEl(slotEl, selection, markers) {
+	if (!selection || selection.kind !== "slot" || selection.item_index == null) return null;
+	return slotEl?.querySelector(`[${markers.slotItem}="${cssEscape(String(selection.item_index))}"]`) ?? null;
+}
+function resolveSelectionEl(doc, selection, markers) {
+	if (!selection) return null;
+	const sec = doc.querySelector(`[${markers.sectionInstanceId}="${cssEscape(selection.instance_id)}"]`);
+	if (!sec) return null;
+	if (selection.kind === "section") return sec;
+	const node = resolveVisibleSlotEl(sec, selection.slot_id, markers);
+	if (!node) return null;
+	return resolveItemEl(node, selection, markers) ?? node.closest(`[${markers.slotGroup}]`) ?? node;
+}
+
+//#endregion
+export { LABEL_LEFT_INDENT, RING_OFFSET, applySelectionKind, clearLabel, clearRing, cssEscape, hasMeasurableRingBox, measureRingRect, positionLabel, positionRing, resolveItemEl, resolveSelectionEl, resolveVisibleSlotEl, ringBox };