@jxsuite/studio 4.1.0 → 5.0.0

package/src/ui/surface.ts

@@ -0,0 +1,122 @@
+/**
+ * The one way a Studio surface document is mounted.
+ *
+ * A surface is a Jx document under `src/surfaces/`, bundled as JSON and registered here by name.
+ * The adapter that owns a surface builds a scope of host records and functions and calls
+ * `mountSurface`; this module waits for the kit, mounts through the runtime's `mount()` with the
+ * surfaces' own base and resolver so a document's `$ref`s resolve with no network, stamps the
+ * host's region id, and records the mount so a redefinition or a saved edit can find it
+ * (specs/studio-ui-guidelines.md §9.3, specs/embedding.md §2).
+ *
+ * @docs extending/ui-kit
+ */
+import { mount, preloadDocument } from "@jxsuite/runtime";
+import type { JxMountOptions, JxScope } from "@jxsuite/runtime/types";
+import type { JxDocument } from "@jxsuite/schema/types";
+import { registerMount, unregisterMount } from "../services/surface-registry";
+import { kitReady } from "./kit";
+import { REGION_ATTR } from "./regions";
+
+/** The URL every surface document is known by: `jx-studio:/surfaces/<name>.json`. */
+export const SURFACES_BASE = "jx-studio:/surfaces/";
+
+const surfaces = new Map<string, JxDocument>();
+
+/**
+ * Register a surface document under a name. Bundled JSON, so it is also preloaded under its URL for
+ * the runtime's own resolution paths.
+ */
+export function registerSurface(name: string, doc: JxDocument): void {
+  surfaces.set(name, doc);
+  preloadDocument(surfaceUrl(name), doc);
+}
+
+/** The URL a surface name resolves to. */
+export function surfaceUrl(name: string): string {
+  return `${SURFACES_BASE}${name}.json`;
+}
+
+/** The registered document for a name, if any. */
+export function surfaceDocument(name: string): JxDocument | undefined {
+  return surfaces.get(name);
+}
+
+/** The mount resolver: answers surface URLs from the registry and nothing else. */
+export function surfaceResolver(url: string): JxDocument | undefined {
+  if (!url.startsWith(SURFACES_BASE) || !url.endsWith(".json")) {
+    return undefined;
+  }
+  return surfaces.get(url.slice(SURFACES_BASE.length, -".json".length));
+}
+
+export interface SurfaceHandle {
+  readonly scope: JxScope;
+  readonly root: HTMLElement | Text;
+  readonly elements: ReadonlySet<string>;
+  readonly dispose: () => void;
+}
+
+export interface MountSurfaceOptions {
+  /** A `data-jx-region` id stamped on the host, so the screenshot pipeline can address it. */
+  region?: string;
+  onNodeCreated?: JxMountOptions["onNodeCreated"];
+  onNodeMoved?: JxMountOptions["onNodeMoved"];
+  signal?: AbortSignal;
+}
+
+/**
+ * Mount a registered surface into a host node with the given host scope.
+ *
+ * @throws {Error} When no document is registered under `name`
+ */
+export async function mountSurface(
+  name: string,
+  hostScope: Record<string, unknown>,
+  host: HTMLElement,
+  options: MountSurfaceOptions = {},
+): Promise<SurfaceHandle> {
+  const doc = surfaces.get(name);
+  if (!doc) {
+    throw new Error(`Studio surface "${name}" is not registered`);
+  }
+  await kitReady();
+  if (options.region) {
+    host.setAttribute(REGION_ATTR, options.region);
+  }
+  const handle = await mount(doc, host, {
+    scope: hostScope,
+    base: SURFACES_BASE,
+    resolver: surfaceResolver,
+    ...(options.onNodeCreated ? { onNodeCreated: options.onNodeCreated } : {}),
+    ...(options.onNodeMoved ? { onNodeMoved: options.onNodeMoved } : {}),
+    ...(options.signal ? { signal: options.signal } : {}),
+  });
+
+  const surfaceHandle = (dispose: () => void): SurfaceHandle => ({
+    dispose,
+    elements: handle.elements,
+    root: handle.root,
+    scope: handle.scope,
+  });
+  if (options.signal?.aborted) {
+    // The runtime already disposed it without attaching; there is no mount to record.
+    return surfaceHandle(handle.dispose);
+  }
+
+  let id = 0;
+  const dispose = (): void => {
+    handle.dispose();
+    unregisterMount(id);
+  };
+  id = registerMount({
+    elements: handle.elements,
+    host,
+    name,
+    remount: async () => {
+      dispose();
+      await mountSurface(name, hostScope, host, options);
+    },
+  });
+  options.signal?.addEventListener("abort", () => unregisterMount(id), { once: true });
+  return surfaceHandle(dispose);
+}

package/src/ui/unit-selector.ts

@@ -1,138 +1,22 @@
-/// <reference lib="dom" />
 /**
- * Unit-selector.js — Number + unit picker widget.
+ * The CSS length grammar the Style tab parses a typed value with.
  *
- * Renders a text field for numeric input paired with a unit picker dropdown. Handles keywords
- * (auto, inherit, etc.) alongside numeric+unit values.
+ * This module used to draw the control as well — an `sp-textfield` beside an `sp-picker-button` and
+ * an `sp-overlay` of units — and that control is now the Style tab's own composite over the kit
+ * (`surfaces/style-panel.json`'s `group` widget: a field the reader may type anything into, beside
+ * a button that opens the KIT MENU of units and keywords). What could not move into the document is
+ * this: deciding whether `12px`, `auto` and `10px 20px` are a number with a unit, a keyword, or a
+ * value that only partially parses. That is a decision, so it stays in TypeScript, and it stays in
+ * ONE place because the panel reads it three times over — for the number the field shows, for the
+ * placeholder an inherited value contributes, and for the unit a menu choice re-attaches.
  */
 
-import { html, nothing } from "lit-html";
-import { live } from "lit-html/directives/live.js";
-import { classMap } from "lit-html/directives/class-map.js";
-import { cancelStyleDebounce, debouncedStyleCommit } from "../store";
-
-export const UNIT_RE = /^(-?[\d.]+)(px|rem|em|%|vw|vh|svw|svh|dvh|ms|s|fr|ch|ex|deg)?$/;
-
 /**
- * Render a number + unit selector widget.
+ * A number and, optionally, one of the units the panel offers.
  *
- * @param {Record<string, unknown>} entry — css-meta entry with $units and $keywords arrays
- * @param {string} prop — property key (for debounce namespace)
- * @param {string | number | undefined} value — current value (e.g. "12px", "auto", "")
- * @param {(val: string) => void} onChange — commit callback
- * @param {string} [placeholder]
- * @returns {import("lit-html").TemplateResult}
+ * Anchored at both ends on purpose: a value that is a length AND something else — `10px 20px`, a
+ * `calc()`, a `${}` template — must NOT match, because matching would let the unit menu rewrite a
+ * value it does not understand. Those fall through to the partial-parse path instead, which shows
+ * the leading number and leaves the value alone.
  */
-export function renderUnitSelector(
-  /** @type {Record<string, unknown>} */ entry: Record<string, unknown>,
-  /** @type {string} */ prop: string,
-  /** @type {string | number | undefined} */ value: string | number | undefined,
-  /** @type {(val: string) => void} */ onChange: (val: string) => void,
-  /** @type {string} */ placeholder = "",
-) {
-  const units = (entry.$units || []) as string[];
-  const keywords = (entry.$keywords || []) as string[];
-  const strVal = String(value ?? "");
-  const match = strVal.match(UNIT_RE);
-  const isKeyword = !match && strVal !== "" && keywords.includes(strVal);
-  const isNumericVal = (v: string) => /^-?\d*\.?\d*$/.test(v);
-
-  const currentUnit = isKeyword ? units[0] || "" : match ? match[2] || "" : units[0] || "";
-  let displayValue;
-  if (isKeyword) {
-    displayValue = strVal;
-  } else if (match) {
-    displayValue = match[1]!;
-  } else if (strVal !== "") {
-    // Intentional partial parse: shorthand like "10px 20px" displays its leading number.
-    // Number() yields NaN for those, so Number.parseFloat stays (see unit-selector tests).
-    // oxlint-disable-next-line unicorn/prefer-number-coercion
-    const num = Number.parseFloat(strVal);
-    displayValue = Number.isNaN(num) ? strVal : String(num);
-  } else {
-    displayValue = "";
-  }
-
-  // Parse placeholder so inherited values display as "500" not "500px"
-  const placeholderMatch = placeholder.match(UNIT_RE);
-  const numericPlaceholder = placeholderMatch ? placeholderMatch[1]! : placeholder || "0";
-
-  const isExpression = isKeyword || (displayValue !== "" && !isNumericVal(displayValue));
-  const hasUnits = units.length > 0 || keywords.length > 0;
-  const btnId = `style-unit-${prop}`;
-
-  const commitValue = (rawVal: string) => {
-    const val = rawVal.trim();
-    if (val === "") {
-      onChange("");
-      return;
-    }
-    if (isNumericVal(val)) {
-      onChange(units.length > 0 ? val + currentUnit : val);
-    } else {
-      onChange(val);
-    }
-  };
-
-  return html`
-    <div class="style-input-number-unit">
-      <div
-        class=${classMap({
-          "input-group": true,
-          "is-expression": isExpression,
-        })}
-      >
-        <sp-textfield
-          size="s"
-          placeholder=${numericPlaceholder}
-          .value=${live(displayValue)}
-          @input=${debouncedStyleCommit(`nui:${prop}`, 400, (e: Event) => {
-            commitValue((e.target as HTMLInputElement).value);
-          })}
-          @change=${(e: Event) => {
-            cancelStyleDebounce(`nui:${prop}`);
-            commitValue((e.target as HTMLInputElement).value);
-          }}
-        ></sp-textfield>
-        ${
-          hasUnits
-            ? html`
-                <sp-picker-button id=${btnId} size="s">
-                  <span slot="label">${currentUnit || units[0] || ""}</span>
-                </sp-picker-button>
-                <sp-overlay trigger="${btnId}@click" placement="bottom-end" offset="4">
-                  <sp-popover style="min-width: var(--spectrum-component-width-900, 64px)">
-                    <sp-menu
-                      label="CSS unit"
-                      @change=${(e: Event) => {
-                        const chosen = (e.target as HTMLInputElement).value;
-                        if (keywords.includes(chosen)) {
-                          onChange(chosen);
-                        } else if (units.includes(chosen)) {
-                          const curMatch = String(value ?? "").match(UNIT_RE);
-                          const numPart = curMatch ? curMatch[1] : "";
-                          if (numPart) {
-                            onChange(numPart + chosen);
-                          }
-                        }
-                      }}
-                    >
-                      ${units.map((u: string) => html`<sp-menu-item value=${u}>${u}</sp-menu-item>`)}
-                      ${
-                        keywords.length > 0 && units.length > 0
-                          ? html`<sp-menu-divider></sp-menu-divider>`
-                          : nothing
-                      }
-                      ${keywords.map(
-                        (kw: string) => html`<sp-menu-item value=${kw}>${kw}</sp-menu-item>`,
-                      )}
-                    </sp-menu>
-                  </sp-popover>
-                </sp-overlay>
-              `
-            : nothing
-        }
-      </div>
-    </div>
-  `;
-}
+export const UNIT_RE = /^(-?[\d.]+)(px|rem|em|%|vw|vh|svw|svh|dvh|ms|s|fr|ch|ex|deg)?$/;

package/src/ui/value-source.ts

@@ -40,6 +40,7 @@ import {
   stringOrRefSchema,
   styleObjectSchema,
   switchDefSchema,
+  tagExpressionSchema,
   tagNameSchema,
 } from "@jxsuite/schema/defs";
 import { isFunctionDef, isRef, isTemplateString } from "@jxsuite/schema/guards";
@@ -261,6 +262,19 @@ const ELEMENT_TAG_SCHEMA = {
   anyOf: [tagNameSchema, ...elementTagNameSchema.anyOf.slice(1)],
 } as const;
 
+/**
+ * The operators a `TagExpression` admits, READ OFF THE DEF rather than restated beside it.
+ *
+ * The Formula rung at a tag position is not the whole operator table: `TagExpression` is two
+ * branches, `?:` and `switch`, and every other operator produces a document `jx validate` rejects
+ * and `tagNameCandidates` cannot enumerate. The rung is derived from the schema and so is the
+ * grammar inside it, for the same reason — a third branch upstream reaches the Inspector by itself,
+ * and a hand-kept pair would not have noticed.
+ */
+export const TAG_EXPRESSION_OPERATORS: readonly string[] = tagExpressionSchema.anyOf.map(
+  (branch) => branch.properties.operator.const,
+);
+
 /**
  * The document positions a bindable slot can occupy. A panel names the position it is editing; the
  * rungs follow from the schema, so a panel can no longer offer a rung the compiler would reject —

package/src/ui/virtual-window.ts

@@ -114,9 +114,24 @@ export function computeWindow(spec: WindowSpec): WindowRange {
   };
 }
 
-/** Two ranges are the same window — the guard that keeps scrolling from repainting every frame. */
+/**
+ * Two ranges are the same window — the guard that keeps scrolling from repainting every frame.
+ *
+ * The SPACERS count, not only the slice. Both are pure functions of the same four inputs, so while
+ * the row height holds still a range with the same slice has the same spacers and the guard is
+ * exactly as quiet as it was. It is when the row height MOVES that the two come apart: the same
+ * eleven rows at a new height reserve a different number of pixels either side, and a guard that
+ * looked at the slice alone called that "nothing changed" and left the tree's declared height
+ * disagreeing with its own rows.
+ */
 export function sameWindow(a: WindowRange, b: WindowRange): boolean {
-  return a.start === b.start && a.end === b.end && a.totalRows === b.totalRows;
+  return (
+    a.start === b.start &&
+    a.end === b.end &&
+    a.totalRows === b.totalRows &&
+    a.padTop === b.padTop &&
+    a.padBottom === b.padBottom
+  );
 }
 
 // ─── The observer ────────────────────────────────────────────────────────────
@@ -160,6 +175,22 @@ export interface VirtualWindowOptions {
  * rAF hop would paint the spacer before the content one frame in three. `ResizeObserver` covers the
  * pane being resized; where the environment has none (happy-dom), `measure()` is the whole contract
  * and the caller drives it — which is also how the perf test drives it.
+ *
+ * **The list is observed as well as the scroller, and that is the whole of how a row-height change
+ * reaches the window.** The window has two inputs nothing else reports: the scroller's box, which
+ * its own observer covers, and the height of one row, which the host measures live off a drawn row
+ * — but only when something asks for a measurement. A density switch asks for nothing: the rows
+ * change height in place, the scroller's box is exactly what it was, and no scroll arrives, so the
+ * spacers stood at the old height until the reader happened to scroll — sighted when compact still
+ * drew rows at 20px, as a tree declaring 1320px over a 62-row model whose rows now totalled 1240.
+ * Compact is 24px today and the switch that moves a row is comfortable, 24px to 28px (ui.md §4.3);
+ * the drift is the same in either direction. The list's height, though, is `padTop + drawn ×
+ * rowHeight + padBottom` with the two spacers fixed in pixels, so ANY change to the row height
+ * changes the list's box by `drawn × Δ`, and observing the list is what turns that into the ask. It
+ * is deliberately not an observer on `data-density`: Studio writes no such attribute (the kit
+ * declares the rule and a consumer sets it), and the same drift follows a late web font, a zoom, or
+ * a stylesheet that overrides `--jx-control-h` — none of which touch an attribute, all of which
+ * move the list's box.
  */
 export function createVirtualWindow(options: VirtualWindowOptions): VirtualWindow {
   const { scroller, list, count, rowHeight, columns, onChange, overscanRows } = options;
@@ -187,10 +218,38 @@ export function createVirtualWindow(options: VirtualWindowOptions): VirtualWindo
 
   scroller.addEventListener("scroll", measure, { passive: true });
 
+  /*
+   * A resize is measured ONE FRAME LATER, and the reason is the list observer above.
+   *
+   * Measuring inside the observer's own callback is how a scroll is answered, and for a scroll it
+   * is right. For a resize it is a loop: the measure repaints the spacers, the spacers are part of
+   * the list's box, the box the observer is watching changes during delivery, and the browser —
+   * which will not deliver a second observation in the same frame — reports "ResizeObserver loop
+   * completed with undelivered notifications" as a window `error` instead. One per density toggle,
+   * measured; zero before the list was observed. A frame hop is the documented remedy: the write
+   * lands in the next frame, the observer sees it as a fresh observation, and the second measure
+   * finds the window unchanged and writes nothing. Two observations in one frame collapse into
+   * one measure, which is also what a pane resize wants. Measured again with the hop in place:
+   * zero errors across seven density toggles over a 386-row windowed model, first visits included.
+   */
+  let pending = 0;
+  const measureNextFrame = (): void => {
+    if (pending !== 0) {
+      return;
+    }
+    pending = requestAnimationFrame(() => {
+      pending = 0;
+      measure();
+    });
+  };
+
   let resizeObserver: ResizeObserver | null = null;
   if (typeof ResizeObserver === "function") {
-    resizeObserver = new ResizeObserver(() => measure());
+    resizeObserver = new ResizeObserver(measureNextFrame);
     resizeObserver.observe(scroller);
+    if (list) {
+      resizeObserver.observe(list);
+    }
   }
 
   measure();
@@ -201,6 +260,10 @@ export function createVirtualWindow(options: VirtualWindowOptions): VirtualWindo
       scroller.removeEventListener("scroll", measure);
       resizeObserver?.disconnect();
       resizeObserver = null;
+      if (pending !== 0) {
+        cancelAnimationFrame(pending);
+        pending = 0;
+      }
     },
     measure,
     range: () => current,
@@ -337,12 +400,24 @@ export function revealListRow(list: HTMLElement | null, index: number, rowHeight
  * The height one row actually has, measured, with the stylesheet's declared height as the answer
  * until a row exists to measure.
  *
- * Both are needed. The DECLARED height (`styles/panels.css` gives `.layer-row` and
- * `.file-tree-item` a `block-size`) is what lets the FIRST render window anything at all, before
- * any row has been laid out. The MEASUREMENT is what stops that constant becoming a lie the day
- * someone changes the row's padding, a user zooms, or a locale's font raises the line box: a window
- * computed from a stale height does not fail loudly, it drifts, and the list quietly ends a few
- * rows short of its own scrollbar.
+ * Both are needed. The DECLARED height is what lets the FIRST render window anything at all, before
+ * any row has been laid out. It used to be `styles/panels.css`'s `.layer-row` and `.file-tree-item`
+ * rules; both trees are `jx-tree-item` now and the declaration travelled with them — `blockSize:
+ * var(--jx-control-h)`, which is 24px and matches the constants the two hosts pass. At
+ * `[data-density=comfortable]` that token is 28px while the constants stay 24, and the constant is
+ * only the answer until a row exists, so a session that STARTS comfortable is right from its second
+ * paint. (Compact used to be the other direction, 20px; it is 24px now, because WCAG 2.2 SC 2.5.8
+ * asks 24 CSS px of a target and the kit holds every density to it — ui.md §4.3.) The MEASUREMENT
+ * is what stops that constant becoming a lie the day someone changes the row's padding, a user
+ * zooms, or a locale's font raises the line box: a window computed from a stale height does not
+ * fail loudly, it drifts, and the list quietly ends a few rows short of its own scrollbar.
+ *
+ * A measurement is only as fresh as the last time something ASKED for one, and this used to be
+ * where the density switch got through: the rows shrank in place, nothing scrolled, nothing resized
+ * the scroller, and the spacers stood at the old height until the next scroll — measured in a
+ * browser as a `padbottom` of 408 (17 × 24) over rows that had shrunk to 20px, when compact still
+ * drew them at that height. The ask is now the list's own resize ({@link createVirtualWindow}
+ * observes it), which is the one event every cause of a row-height change has in common.
  */
 export function measuredRowHeight(
   list: HTMLElement | null,
@@ -371,6 +446,10 @@ export interface ListWindowWatch {
  * scroller, nothing to do". A new element — the panel remounted, or moved dock — moves the
  * listener, and a list that no longer scrolls drops it.
  *
+ * The list goes to the window as well as the scroller, and not only for the scroll offset: it is
+ * the element whose box moves when the ROWS change height, so it is what the window observes to
+ * learn that `rowHeight()` now answers differently ({@link createVirtualWindow}).
+ *
  * Returns the handle to keep, or null when nothing scrolls this list.
  */
 export function watchListWindow(

package/src/utils/canvas-media.ts

@@ -84,3 +84,75 @@ export function activeBreakpointsForWidth(
   }
   return active;
 }
+
+/**
+ * The ONE breakpoint a canvas of this width is rendering under, or `null` for Base.
+ *
+ * {@link activeBreakpointsForWidth} answers a set, because several queries genuinely match at once:
+ * a desktop-first project at 700px satisfies both `(max-width: 1024px)` and `(max-width: 768px)`.
+ * The rendering context is one value, though — `session.ui.activeMedia` is a single key — so this
+ * picks the most specific member of that set: the one whose declared width is CLOSEST to the canvas
+ * width, ties going to the narrower.
+ *
+ * Closest, rather than last-in-array, on purpose. Every matching `max` entry is at least as wide as
+ * the canvas and every matching `min` entry at most, so "closest" reads as "narrowest" for a
+ * desktop-first project and "widest" for a mobile-first one — the correct band in both. Array
+ * position would agree for those two, but {@link parseMediaEntries}'s comparator decides the whole
+ * sort from `a.type` alone, so it orders a project mixing `min-` and `max-width` arbitrarily.
+ * Distance does not depend on the sort at all.
+ *
+ * @param {{ name: string; width: number; type: string }[]} sizeBreakpoints
+ * @param {number} canvasWidth
+ * @returns {string | null}
+ */
+export function mediaForWidth(
+  sizeBreakpoints: { name: string; width: number; type: string }[],
+  canvasWidth: number,
+): string | null {
+  const active = activeBreakpointsForWidth(sizeBreakpoints, canvasWidth);
+  let best: { name: string; width: number } | null = null;
+  for (const bp of sizeBreakpoints) {
+    if (!active.has(bp.name)) {
+      continue;
+    }
+    const distance = Math.abs(bp.width - canvasWidth);
+    if (best === null) {
+      best = bp;
+      continue;
+    }
+    const bestDistance = Math.abs(best.width - canvasWidth);
+    // Ties to the NARROWER entry: at a width equidistant from a `max` and a `min` neighbour, the
+    // Tighter constraint is the one an author is checking.
+    if (distance < bestDistance || (distance === bestDistance && bp.width < best.width)) {
+      best = bp;
+    }
+  }
+  return best?.name ?? null;
+}
+
+/**
+ * Pull a dragged width onto a declared one when it comes close enough — magnetic snapping.
+ *
+ * The Edit canvas is dragged continuously, which is the point of it; landing EXACTLY on a declared
+ * breakpoint is nevertheless the single most common intent, and a pixel-perfect drag cannot deliver
+ * it. So a target within `tolerance` wins, and the caller offers Alt as the bypass — free motion
+ * stays reachable rather than being traded away for the convenience.
+ *
+ * @param {number} width
+ * @param {number[]} targets — declared breakpoint widths, plus the base width
+ * @param {number} tolerance — in px, either side
+ * @returns {number}
+ */
+export function snapEditWidth(width: number, targets: number[], tolerance = 8): number {
+  let best: number | null = null;
+  for (const target of targets) {
+    const distance = Math.abs(target - width);
+    if (distance > tolerance) {
+      continue;
+    }
+    if (best === null || distance < Math.abs(best - width)) {
+      best = target;
+    }
+  }
+  return best ?? width;
+}

package/src/utils/edit-display.ts

@@ -294,11 +294,16 @@ export function prepareForEditMode(node: JxMutableNode): JxMutableNode {
       }
       out.attributes = processed;
     } else if (k === "style") {
-      // Replace template strings in style values with empty strings
+      /* Drop template-valued style declarations. State is not live in edit mode, so the value
+         cannot be resolved; omitting the property lets the cascade answer, which is exactly what
+         the `""` this used to write meant while declarations went inline. As a RULE, `color: ` is
+         a malformed declaration instead of a no-op. Mirrored by iframe-patch's editModeStyle. */
       if (v && typeof v === "object") {
         const s: Record<string, unknown> = {};
         for (const [sk, sv] of Object.entries(v)) {
-          s[sk] = typeof sv === "string" && sv.includes("${") ? "" : sv;
+          if (typeof sv !== "string" || !sv.includes("${")) {
+            s[sk] = sv;
+          }
         }
         out.style = s;
       } else {

package/src/utils/element-selectors.ts

@@ -0,0 +1,69 @@
+/**
+ * The nested selectors the Style tab offers for a given element.
+ *
+ * `COMMON_SELECTORS` is the global base and stays exactly that: eleven states every element can be
+ * in. What it could not express is a state that only exists for SOME elements — `:popover-open` on
+ * a `<p>` is a rule that can never match, and offering it there teaches the menu to be ignored.
+ *
+ * A separate module from `store.ts` because `store.ts` imports the world and this has to be
+ * testable without a DOM. The additions are deliberately few: each one is a state the platform
+ * gives that element and nothing else, so the menu stays a map of where to look rather than a
+ * catalogue of CSS.
+ *
+ * @docs studio/design/states-and-selectors
+ */
+
+import { COMMON_SELECTORS } from "../store";
+import { displayTagName } from "@jxsuite/schema/guards";
+import { isPopover } from "@jxsuite/schema/overlays";
+import type { JxMutableNode } from "@jxsuite/schema/types";
+
+/** Form controls that carry the validity and checked states. */
+const FIELD_TAGS = new Set(["input", "select", "textarea"]);
+
+/**
+ * The states an element can be in beyond the common set.
+ *
+ * `::backdrop` is offered on a popover even though the canvas does not RENDER it (there is no
+ * backdrop pseudo-element outside the top layer, and Preview is where it appears). Offering it is
+ * still right: it is a real part of the shipped page, and the alternative — no way to author it
+ * except by typing it into the custom-selector dialog — is worse than a state you check in
+ * Preview.
+ */
+function extraSelectorsFor(node: JxMutableNode): string[] {
+  const tag = displayTagName(node.tagName).toLowerCase();
+  const out: string[] = [];
+  if (isPopover(node)) {
+    out.push(":popover-open", "::backdrop", ":popover-open::backdrop");
+  }
+  if (tag === "dialog") {
+    out.push("[open]", ":modal", "::backdrop");
+  }
+  if (tag === "details") {
+    out.push("[open]");
+  }
+  if (FIELD_TAGS.has(tag)) {
+    out.push(":checked", ":invalid", ":required", ":user-invalid");
+  }
+  if (tag === "a") {
+    out.push(":visited", ":target");
+  }
+  return out;
+}
+
+/**
+ * Every selector the menu should offer for `node`, in a stable order and without duplicates.
+ *
+ * The common set first, so the menu does not reorder itself as the selection moves; the
+ * element-specific ones after. Callers union this with what the element already DECLARES and with
+ * the active selector, so nothing an author has written can drop out of the menu.
+ *
+ * @param node The selected node, or undefined when there is no selection.
+ * @returns The offerable selectors.
+ */
+export function selectorsForNode(node: JxMutableNode | null | undefined): string[] {
+  if (!node || typeof node !== "object") {
+    return [...COMMON_SELECTORS];
+  }
+  return [...new Set([...COMMON_SELECTORS, ...extraSelectorsFor(node)])];
+}

package/src/utils/link-target.ts

@@ -33,8 +33,8 @@ const ABSOLUTE_SCHEME = /^([a-z][a-z\d+.-]*:)?\/\//i;
  * Classify a raw `href` string into a {@link LinkTarget}.
  *
  * Rules (checked in order): 1. `mailto:…` → `{ kind: "mailto", value: address }` 2. `tel:…` → `{
- * kind: "tel", value: number }` 3. `#…` → `{ kind: "anchor", value: rest }` (leading `#` stripped)
- * 4. absolute (`http(s)://…`) or protocol-relative (`//…`) → `{ kind: "external", value: href }` 5.
+ * kind: "tel", value: number }` 3. `#…` → `{ kind: "anchor", value: rest }` (leading `#` stripped) 4.
+ * absolute (`http(s)://…`) or protocol-relative (`//…`) → `{ kind: "external", value: href }` 5.
  * `/…` → `{ kind: "internal", value: path }` 6. anything else → `{ kind: "external", value: href
  * }`
  *

package/src/utils/studio-utils.ts

@@ -8,16 +8,6 @@ import { collectionForFile } from "../content/collection-match";
 import { defaultContentFormat } from "../format/format-host";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 
-/**
- * CamelCase → kebab-case for inline style attributes
- *
- * @param {string} str
- * @returns {string}
- */
-export function camelToKebab(str: string) {
-  return str.replaceAll(/[A-Z]/g, (c: string) => `-${c.toLowerCase()}`);
-}
-
 /**
  * Convert camelCase property name to "Title Case" label (e.g. "backgroundColor" → "Background
  * Color")

package/src/view.ts

@@ -27,6 +27,21 @@ import type { Tab } from "./tabs/tab";
  * timer survived three disposal sites and stayed able to replace a page with an empty parse.
  * `services/monaco-buffer.ts` owns the rule; this is the storage it needs.
  */
+/**
+ * A comparison's Monaco diff editor.
+ *
+ * Deliberately NOT a {@link MonacoSurface}: an `IStandaloneDiffEditor` is a different type, and
+ * widening the code-editor slot to a union would put a non-code editor into `buffersForTab`'s
+ * array, where `bufferIsLive`, `getValue` and `_writes` are all code-editor APIs. It carries none
+ * of that state because it has nothing to commit: both its models are read-only, and one of them is
+ * a git object that does not exist on disk.
+ *
+ * `_diffKey` is the comparison it was mounted for, so a retarget to a different file disposes it
+ * before claiming the next pair of URIs rather than throwing on a URI the previous mount still
+ * holds.
+ */
+export type DiffSurface = editor.IStandaloneDiffEditor & { _diffKey?: string };
+
 export type MonacoSurface = editor.IStandaloneCodeEditor & {
   _ignoreNextChange?: boolean;
   /** The debounced work armed over this buffer, with this editor's exact lifetime. */