@jxsuite/studio 0.1.0 → 0.5.1

package/src/ui/panel-resize.js

@@ -0,0 +1,96 @@
+/**
+ * Panel-resize.js — Draggable resize handles for left and right sidebars.
+ *
+ * Self-initializing module. Import it and the resize handles become interactive. Persists widths to
+ * localStorage so they survive page reloads.
+ */
+
+const STORAGE_KEY = "jx-studio-panel-widths";
+const MIN_WIDTH = 160;
+const MAX_RATIO = 0.5; // max 50% of viewport
+const DEFAULT_LEFT = 240;
+const DEFAULT_RIGHT = 280;
+
+const root = document.documentElement;
+
+// ─── Restore saved widths ────────────────────────────────────────────────────
+
+try {
+  const saved = JSON.parse(localStorage.getItem(STORAGE_KEY) || "{}");
+  if (saved.left) root.style.setProperty("--panel-w-left", `${saved.left}px`);
+  if (saved.right) root.style.setProperty("--panel-w-right", `${saved.right}px`);
+} catch {
+  // ignore
+}
+
+// ─── Setup handles ───────────────────────────────────────────────────────────
+
+/**
+ * @param {HTMLElement} handle
+ * @param {string} cssVar
+ * @param {"left" | "right"} side
+ * @param {number} defaultWidth
+ */
+function setupHandle(handle, cssVar, side, defaultWidth) {
+  /** @type {{ startX: number; startWidth: number } | null} */
+  let drag = null;
+
+  handle.addEventListener("pointerdown", (e) => {
+    e.preventDefault();
+    try {
+      handle.setPointerCapture(e.pointerId);
+    } catch {
+      /* synthetic events */
+    }
+    handle.classList.add("dragging");
+    document.body.style.userSelect = "none";
+
+    const current = parseInt(getComputedStyle(root).getPropertyValue(cssVar)) || defaultWidth;
+    drag = { startX: e.clientX, startWidth: current };
+  });
+
+  handle.addEventListener("pointermove", (e) => {
+    if (!drag) return;
+    const delta = side === "left" ? e.clientX - drag.startX : drag.startX - e.clientX;
+    const maxWidth = window.innerWidth * MAX_RATIO;
+    const newWidth = Math.round(Math.min(maxWidth, Math.max(MIN_WIDTH, drag.startWidth + delta)));
+    root.style.setProperty(cssVar, `${newWidth}px`);
+  });
+
+  handle.addEventListener("pointerup", (e) => {
+    if (!drag) return;
+    drag = null;
+    try {
+      handle.releasePointerCapture(e.pointerId);
+    } catch {
+      /* synthetic events */
+    }
+    handle.classList.remove("dragging");
+    document.body.style.userSelect = "";
+    persistWidths();
+  });
+
+  handle.addEventListener("dblclick", () => {
+    root.style.setProperty(cssVar, `${defaultWidth}px`);
+    persistWidths();
+  });
+}
+
+function persistWidths() {
+  const left = parseInt(getComputedStyle(root).getPropertyValue("--panel-w-left")) || DEFAULT_LEFT;
+  const right =
+    parseInt(getComputedStyle(root).getPropertyValue("--panel-w-right")) || DEFAULT_RIGHT;
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify({ left, right }));
+  } catch {
+    // storage full or unavailable
+  }
+}
+
+// ─── Initialize ──────────────────────────────────────────────────────────────
+
+const resizeLeft = document.getElementById("resize-left");
+const resizeRight = document.getElementById("resize-right");
+
+if (resizeLeft) setupHandle(resizeLeft, "--panel-w-left", "left", DEFAULT_LEFT);
+if (resizeRight) setupHandle(resizeRight, "--panel-w-right", "right", DEFAULT_RIGHT);

package/src/ui/spectrum.js

@@ -37,10 +37,22 @@ import { Switch as SpSwitch } from "@spectrum-web-components/switch/src/Switch.j
 import { Divider } from "@spectrum-web-components/divider/src/Divider.js";
 import { Tooltip } from "@spectrum-web-components/tooltip/src/Tooltip.js";
 import { Overlay } from "@spectrum-web-components/overlay/src/Overlay.js";
+import { OverlayTrigger } from "@spectrum-web-components/overlay/src/OverlayTrigger.js";
+import { Dialog } from "@spectrum-web-components/dialog/src/Dialog.js";
+import { DialogWrapper } from "@spectrum-web-components/dialog/src/DialogWrapper.js";
+import { HelpText } from "@spectrum-web-components/help-text/src/HelpText.js";
+import { Button } from "@spectrum-web-components/button/src/Button.js";
+import { Underlay } from "@spectrum-web-components/underlay/src/Underlay.js";
 import { PickerButton } from "@spectrum-web-components/picker-button/src/PickerButton.js";
 import { Accordion } from "@spectrum-web-components/accordion/src/Accordion.js";
 import { AccordionItem } from "@spectrum-web-components/accordion/src/AccordionItem.js";
 import { ActionBar } from "@spectrum-web-components/action-bar/src/ActionBar.js";
+import { Table } from "@spectrum-web-components/table/src/Table.js";
+import { TableHead } from "@spectrum-web-components/table/src/TableHead.js";
+import { TableHeadCell } from "@spectrum-web-components/table/src/TableHeadCell.js";
+import { TableBody } from "@spectrum-web-components/table/src/TableBody.js";
+import { TableRow } from "@spectrum-web-components/table/src/TableRow.js";
+import { TableCell } from "@spectrum-web-components/table/src/TableCell.js";
 
 // Icons
 import { IconFolder } from "@spectrum-web-components/icons-workflow/src/elements/IconFolder.js";
@@ -49,8 +61,10 @@ import { IconDocument } from "@spectrum-web-components/icons-workflow/src/elemen
 import { IconFileCode } from "@spectrum-web-components/icons-workflow/src/elements/IconFileCode.js";
 import { IconFileTxt } from "@spectrum-web-components/icons-workflow/src/elements/IconFileTxt.js";
 import { IconImage } from "@spectrum-web-components/icons-workflow/src/elements/IconImage.js";
+import { IconFileSingleWebPage } from "@spectrum-web-components/icons-workflow/src/elements/IconFileSingleWebPage.js";
 import { IconRefresh } from "@spectrum-web-components/icons-workflow/src/elements/IconRefresh.js";
 import { IconAdd } from "@spectrum-web-components/icons-workflow/src/elements/IconAdd.js";
+import { IconUpload } from "@spectrum-web-components/icons-workflow/src/elements/IconUpload.js";
 import { IconLayers } from "@spectrum-web-components/icons-workflow/src/elements/IconLayers.js";
 import { IconViewGrid } from "@spectrum-web-components/icons-workflow/src/elements/IconViewGrid.js";
 import { IconBrackets } from "@spectrum-web-components/icons-workflow/src/elements/IconBrackets.js";
@@ -69,6 +83,7 @@ import { IconExport } from "@spectrum-web-components/icons-workflow/src/elements
 import { IconPreview } from "@spectrum-web-components/icons-workflow/src/elements/IconPreview.js";
 import { IconCode } from "@spectrum-web-components/icons-workflow/src/elements/IconCode.js";
 import { IconBrush } from "@spectrum-web-components/icons-workflow/src/elements/IconBrush.js";
+import { IconGears } from "@spectrum-web-components/icons-workflow/src/elements/IconGears.js";
 import { IconBack } from "@spectrum-web-components/icons-workflow/src/elements/IconBack.js";
 import { IconProperties } from "@spectrum-web-components/icons-workflow/src/elements/IconProperties.js";
 import { IconEvent } from "@spectrum-web-components/icons-workflow/src/elements/IconEvent.js";
@@ -103,6 +118,7 @@ import { IconBox } from "@spectrum-web-components/icons-workflow/src/elements/Ic
 import { IconVisibility } from "@spectrum-web-components/icons-workflow/src/elements/IconVisibility.js";
 import { IconVisibilityOff } from "@spectrum-web-components/icons-workflow/src/elements/IconVisibilityOff.js";
 import { IconArtboard } from "@spectrum-web-components/icons-workflow/src/elements/IconArtboard.js";
+import { IconViewList } from "@spectrum-web-components/icons-workflow/src/elements/IconViewList.js";
 
 // Inline formatting icons
 import { IconTextBold } from "@spectrum-web-components/icons-workflow/src/elements/IconTextBold.js";
@@ -114,7 +130,8 @@ import { IconTextSubscript } from "@spectrum-web-components/icons-workflow/src/e
 import { IconLink } from "@spectrum-web-components/icons-workflow/src/elements/IconLink.js";
 
 // Custom studio components
-import { JxStyledCombobox } from "./jx-styled-combobox.js";
+import { JxValueSelector } from "./value-selector.js";
+import { JxColorPopover } from "./color-selector.js";
 
 // UI icons (used internally by Spectrum components like accordion, picker, combobox)
 import { IconChevron100 } from "@spectrum-web-components/icons-ui/src/elements/IconChevron100.js";
@@ -151,18 +168,32 @@ const components = [
   ["sp-divider", Divider],
   ["sp-tooltip", Tooltip],
   ["sp-overlay", Overlay],
+  ["overlay-trigger", OverlayTrigger],
+  ["sp-dialog", Dialog],
+  ["sp-dialog-wrapper", DialogWrapper],
+  ["sp-help-text", HelpText],
+  ["sp-button", Button],
+  ["sp-underlay", Underlay],
   ["sp-picker-button", PickerButton],
   ["sp-accordion", Accordion],
   ["sp-accordion-item", AccordionItem],
   ["sp-action-bar", ActionBar],
+  ["sp-table", Table],
+  ["sp-table-head", TableHead],
+  ["sp-table-head-cell", TableHeadCell],
+  ["sp-table-body", TableBody],
+  ["sp-table-row", TableRow],
+  ["sp-table-cell", TableCell],
   ["sp-icon-folder", IconFolder],
   ["sp-icon-folder-open", IconFolderOpen],
   ["sp-icon-document", IconDocument],
   ["sp-icon-file-code", IconFileCode],
   ["sp-icon-file-txt", IconFileTxt],
   ["sp-icon-image", IconImage],
+  ["sp-icon-file-single-web-page", IconFileSingleWebPage],
   ["sp-icon-refresh", IconRefresh],
   ["sp-icon-add", IconAdd],
+  ["sp-icon-upload", IconUpload],
   ["sp-icon-layers", IconLayers],
   ["sp-icon-view-grid", IconViewGrid],
   ["sp-icon-brackets", IconBrackets],
@@ -181,6 +212,7 @@ const components = [
   ["sp-icon-preview", IconPreview],
   ["sp-icon-code", IconCode],
   ["sp-icon-brush", IconBrush],
+  ["sp-icon-gears", IconGears],
   ["sp-icon-back", IconBack],
   ["sp-icon-properties", IconProperties],
   ["sp-icon-event", IconEvent],
@@ -213,6 +245,7 @@ const components = [
   ["sp-icon-visibility", IconVisibility],
   ["sp-icon-visibility-off", IconVisibilityOff],
   ["sp-icon-artboard", IconArtboard],
+  ["sp-icon-view-list", IconViewList],
   ["sp-icon-text-bold", IconTextBold],
   ["sp-icon-text-italic", IconTextItalic],
   ["sp-icon-text-underline", IconTextUnderline],
@@ -223,7 +256,8 @@ const components = [
   // UI icons (internal component chrome)
   ["sp-icon-chevron100", IconChevron100],
   // Custom studio components
-  ["jx-styled-combobox", JxStyledCombobox],
+  ["jx-value-selector", JxValueSelector],
+  ["jx-color-popover", JxColorPopover],
 ];
 
 for (const [tag, ctor] of /** @type {[string, CustomElementConstructor][]} */ (components)) {

package/src/ui/unit-selector.js

@@ -0,0 +1,106 @@
+/**
+ * Unit-selector.js — Number + unit picker widget.
+ *
+ * Renders a text field for numeric input paired with a unit picker dropdown. Handles keywords
+ * (auto, inherit, etc.) alongside numeric+unit values.
+ */
+
+import { html, nothing } from "lit-html";
+import { live } from "lit-html/directives/live.js";
+import { classMap } from "lit-html/directives/class-map.js";
+import { debouncedStyleCommit } from "../store.js";
+
+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.
+ *
+ * @param {any} entry — css-meta entry with $units and $keywords arrays
+ * @param {string} prop — property key (for debounce namespace)
+ * @param {any} value — current value (e.g. "12px", "auto", "")
+ * @param {(val: string) => void} onChange — commit callback
+ * @returns {any}
+ */
+export function renderUnitSelector(
+  /** @type {any} */ entry,
+  /** @type {any} */ prop,
+  /** @type {any} */ value,
+  /** @type {any} */ onChange,
+  /** @type {string} */ placeholder = "",
+) {
+  const units = entry.$units || [];
+  const keywords = entry.$keywords || [];
+  const strVal = String(value ?? "");
+  const match = strVal.match(UNIT_RE);
+  const isKeyword = !match && strVal !== "" && keywords.includes(strVal);
+  const isNumericVal = (/** @type {any} */ v) => /^-?\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 !== "") {
+    const num = parseFloat(strVal);
+    displayValue = isNaN(num) ? strVal : String(num);
+  } else displayValue = "";
+
+  const isExpression = isKeyword || (displayValue !== "" && !isNumericVal(displayValue));
+  const hasUnits = units.length > 0 || keywords.length > 0;
+  const btnId = `style-unit-${prop}`;
+
+  return html`
+    <div class="style-input-number-unit">
+      <div class=${classMap({ "input-group": true, "is-expression": isExpression })}>
+        <sp-textfield
+          size="s"
+          placeholder=${placeholder || "0"}
+          .value=${live(displayValue)}
+          @input=${debouncedStyleCommit(`nui:${prop}`, 400, (/** @type {any} */ e) => {
+            const val = (e.target.value ?? "").trim();
+            if (val === "") {
+              onChange("");
+              return;
+            }
+            if (isNumericVal(val)) onChange(units.length > 0 ? val + currentUnit : val);
+            else onChange(val);
+          })}
+        ></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=${(/** @type {any} */ e) => {
+                      const chosen = e.target.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(
+                      (/** @type {any} */ u) => 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(
+                      (/** @type {any} */ kw) =>
+                        html`<sp-menu-item value=${kw}>${kw}</sp-menu-item>`,
+                    )}
+                  </sp-menu>
+                </sp-popover>
+              </sp-overlay>
+            `
+          : nothing}
+      </div>
+    </div>
+  `;
+}

package/src/ui/{jx-styled-combobox.js → value-selector.js}

@@ -1,15 +1,15 @@
 /**
- * Jx-styled-combobox — Dual-mode styled combobox custom element.
+ * Value Selector — Dual-mode styled combobox custom element.
  *
  * Renders as sp-picker when the current value matches a predefined option, or as a textfield +
  * dropdown overlay (manual combobox) when it doesn't. Both modes share identical styled menu items,
  * ensuring visual consistency.
  *
- * Usage: html`<jx-styled-combobox size="s" .value=${"italic"} placeholder="normal" .options=${[{
+ * Usage: html`<jx-value-selector size="s" .value=${"italic"} placeholder="normal" .options=${[{
  * value: "italic", label: "Italic", style: "font-style: italic" }]} @change=${handler}
  * @input=${handler}
  *
- * > </jx-styled-combobox>`
+ * > </jx-value-selector>`
  *
  * Options format: { value: string, label: string, style?: string } — menu item { divider: true } —
  * menu divider
@@ -20,7 +20,7 @@ import { live } from "lit/directives/live.js";
 
 /** @typedef {{ value: string; label: string; style?: string } | { divider: true }} ComboOption */
 
-export class JxStyledCombobox extends LitElement {
+export class JxValueSelector extends LitElement {
   static properties = {
     value: { type: String },
     placeholder: { type: String },
@@ -71,14 +71,14 @@ export class JxStyledCombobox extends LitElement {
 
   /** Picker mode: sp-picker @change handler */
   _handlePickerChange(/** @type {any} */ e) {
-    e.stopPropagation(); // prevent sp-picker's raw event from reaching consumer
+    e.stopPropagation();
     this.value = e.target.value;
     this.dispatchEvent(new Event("change", { bubbles: true, composed: true }));
   }
 
   /** Combobox mode: sp-menu @change handler */
   _handleMenuChange(/** @type {any} */ e) {
-    e.stopPropagation(); // prevent sp-menu's raw event from reaching consumer
+    e.stopPropagation();
     if (!e.target.value) return;
     this.value = e.target.value;
     this.dispatchEvent(new Event("change", { bubbles: true, composed: true }));
@@ -86,7 +86,7 @@ export class JxStyledCombobox extends LitElement {
 
   /** Combobox mode: textfield @input handler */
   _handleInput(/** @type {any} */ e) {
-    e.stopPropagation(); // prevent sp-textfield's raw event from reaching consumer
+    e.stopPropagation();
     this.value = e.target.value;
     this.dispatchEvent(new Event("input", { bubbles: true, composed: true }));
   }

package/src/ui/widgets.js

@@ -0,0 +1,106 @@
+/**
+ * Widgets.js — Widget type dispatcher and simple widget renderers.
+ *
+ * This module provides `widgetForType()` which dispatches to the appropriate widget based on the
+ * inferred type from css-meta/schema entries, plus the simpler widget renderers (text, number,
+ * select/combobox).
+ *
+ * Complex widgets are imported from their dedicated modules: - renderColorSelector →
+ * ui/color-selector.js - renderUnitSelector → ui/unit-selector.js - renderButtonGroup →
+ * ui/button-group.js
+ */
+
+import { html } from "lit-html";
+import { live } from "lit-html/directives/live.js";
+import { ifDefined } from "lit-html/directives/if-defined.js";
+import { debouncedStyleCommit } from "../store.js";
+import { renderColorSelector } from "./color-selector.js";
+import { renderUnitSelector } from "./unit-selector.js";
+import { renderButtonGroup } from "./button-group.js";
+import { renderMediaPicker } from "./media-picker.js";
+
+/**
+ * Render a plain text input widget.
+ *
+ * @param {string} prop
+ * @param {any} value
+ * @param {(val: string) => void} onChange
+ * @param {string} [placeholder]
+ * @returns {any}
+ */
+export function renderTextInput(prop, value, onChange, placeholder = "") {
+  return html`
+    <sp-textfield
+      size="s"
+      placeholder=${placeholder}
+      .value=${live(value || "")}
+      @input=${debouncedStyleCommit(`text:${prop}`, 400, (/** @type {any} */ e) =>
+        onChange(e.target.value),
+      )}
+    ></sp-textfield>
+  `;
+}
+
+/**
+ * Render a number input widget (sp-number-field).
+ *
+ * @param {any} entry
+ * @param {string} prop
+ * @param {any} value
+ * @param {(val: any) => void} onChange
+ * @returns {any}
+ */
+export function renderNumberInput(entry, prop, value, onChange, placeholder = "") {
+  return html`
+    <sp-number-field
+      size="s"
+      hide-stepper
+      .value=${live(value !== undefined && value !== "" ? Number(value) : undefined)}
+      placeholder=${placeholder}
+      min=${ifDefined(entry.minimum)}
+      max=${ifDefined(entry.maximum)}
+      step=${ifDefined(entry.maximum !== undefined && entry.maximum <= 1 ? 0.1 : undefined)}
+      @change=${debouncedStyleCommit(`num:${prop}`, 400, (/** @type {any} */ e) => {
+        const v = e.target.value;
+        if (v === undefined || isNaN(v)) onChange("");
+        else onChange(Number(v));
+      })}
+    ></sp-number-field>
+  `;
+}
+
+/**
+ * Dispatch to the appropriate widget based on inferred type.
+ *
+ * @param {string} type — one of: button-group, color, number-unit, number, select, combobox, text
+ * @param {any} entry — css-meta or schema entry
+ * @param {string} prop — property key
+ * @param {any} value — current value
+ * @param {(val: any) => void} onCommit — commit callback
+ * @param {{ placeholder?: string; renderSelect?: Function; renderCombobox?: Function }} [opts]
+ * @returns {any}
+ */
+export function widgetForType(type, entry, prop, value, onCommit, opts = {}) {
+  switch (type) {
+    case "button-group":
+      return renderButtonGroup(entry, prop, value, onCommit);
+    case "color":
+      return renderColorSelector(prop, value, onCommit);
+    case "number-unit":
+      return renderUnitSelector(entry, prop, value, onCommit, opts.placeholder);
+    case "number":
+      return renderNumberInput(entry, prop, value, onCommit, opts.placeholder);
+    case "media":
+      return renderMediaPicker(prop, value, onCommit);
+    case "select":
+      // Allow caller to override select rendering (e.g. for typography preview)
+      if (opts.renderSelect) return opts.renderSelect(entry, prop, value, onCommit);
+      return renderTextInput(prop, value, onCommit, opts.placeholder);
+    case "combobox":
+      // Allow caller to override combobox rendering (e.g. for font family)
+      if (opts.renderCombobox) return opts.renderCombobox(entry, prop, value, onCommit);
+      return renderTextInput(prop, value, onCommit, opts.placeholder);
+    default:
+      return renderTextInput(prop, value, onCommit, opts.placeholder);
+  }
+}

package/src/utils/canvas-media.js

@@ -0,0 +1,151 @@
+/** Canvas media/breakpoint utilities — pure functions extracted for testability. */
+
+/**
+ * Classify $media entries into size breakpoints (get a canvas each) and feature queries (rendered
+ * as toolbar toggles).
+ *
+ * @param {Record<string, string> | null | undefined} mediaDef
+ * @returns {{
+ *   sizeBreakpoints: { name: string; query: string; width: number; type: string }[];
+ *   featureQueries: { name: string; query: string }[];
+ *   baseWidth: number;
+ * }}
+ */
+export function parseMediaEntries(mediaDef) {
+  if (!mediaDef) return { sizeBreakpoints: [], featureQueries: [], baseWidth: 320 };
+  const sizes = [],
+    features = [];
+  let baseWidth = 320;
+  for (const [name, query] of Object.entries(mediaDef)) {
+    if (name === "--") {
+      const wm = String(query).match(/^(\d+)\s*px$/);
+      baseWidth = wm ? parseFloat(wm[1]) : 320;
+      continue;
+    }
+    const minMatch = query.match(/min-width:\s*([\d.]+)px/);
+    const maxMatch = query.match(/max-width:\s*([\d.]+)px/);
+    if (minMatch) sizes.push({ name, query, width: parseFloat(minMatch[1]), type: "min" });
+    else if (maxMatch) sizes.push({ name, query, width: parseFloat(maxMatch[1]), type: "max" });
+    else features.push({ name, query });
+  }
+  sizes.sort((a, b) => (a.type === "min" ? a.width - b.width : b.width - a.width));
+  return { sizeBreakpoints: sizes, featureQueries: features, baseWidth };
+}
+
+/**
+ * Compute which named breakpoints are active at a given canvas width.
+ *
+ * @param {{ name: string; width: number; type: string }[]} sizeBreakpoints
+ * @param {number} canvasWidth
+ * @returns {Set<string>}
+ */
+export function activeBreakpointsForWidth(sizeBreakpoints, canvasWidth) {
+  const active = new Set();
+  for (const bp of sizeBreakpoints) {
+    if (bp.type === "min" && canvasWidth >= bp.width) active.add(bp.name);
+    else if (bp.type === "max" && canvasWidth <= bp.width) active.add(bp.name);
+  }
+  return active;
+}
+
+/**
+ * Apply styles to a canvas element, including active media overrides. Base (flat) styles applied
+ * first, then matching media overrides in source order.
+ *
+ * @param {HTMLElement} el
+ * @param {Record<string, any>} styleDef
+ * @param {Set<string>} activeBreakpoints
+ * @param {Record<string, boolean>} featureToggles
+ */
+export function applyCanvasStyle(el, styleDef, activeBreakpoints, featureToggles) {
+  if (!styleDef || typeof styleDef !== "object") return;
+  for (const [prop, val] of Object.entries(styleDef)) {
+    if (typeof val === "string" || typeof val === "number") {
+      try {
+        if (prop.startsWith("--")) el.style.setProperty(prop, String(val));
+        else /** @type {any} */ (el.style)[prop] = val;
+      } catch {}
+    }
+  }
+  for (const [key, val] of Object.entries(styleDef)) {
+    if (!key.startsWith("@") || typeof val !== "object") continue;
+    const mediaName = key.slice(1);
+    if (mediaName === "--") continue;
+    if (activeBreakpoints.has(mediaName) || featureToggles[mediaName]) {
+      for (const [prop, v] of Object.entries(/** @type {any} */ (val))) {
+        if (typeof v === "string" || typeof v === "number") {
+          try {
+            if (prop.startsWith("--")) el.style.setProperty(prop, String(v));
+            else /** @type {any} */ (el.style)[prop] = v;
+          } catch {}
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Scan stylesheets for @media rules matching active breakpoints, collecting the CSS declarations
+ * that should be applied as inline overrides per data-jx element.
+ *
+ * Returns a Map of data-jx uid → Map of CSS property → value.
+ *
+ * @param {Iterable<CSSStyleSheet>} styleSheets
+ * @param {Set<string>} activeBreakpoints
+ * @returns {Map<string, Map<string, string>>}
+ */
+export function collectMediaOverrides(styleSheets, activeBreakpoints) {
+  /** @type {Map<string, Map<string, string>>} */
+  const overrides = new Map();
+  if (!activeBreakpoints.size) return overrides;
+
+  for (const sheet of styleSheets) {
+    /** @type {CSSRuleList | null} */
+    let rules;
+    try {
+      rules = sheet.cssRules;
+    } catch {
+      continue;
+    }
+    if (!rules) continue;
+    for (let ri = 0; ri < rules.length; ri++) {
+      const rule = rules[ri];
+      if (!(rule instanceof CSSMediaRule)) continue;
+      if (!activeBreakpoints.has(rule.conditionText)) continue;
+      for (let mi = 0; mi < rule.cssRules.length; mi++) {
+        const mediaRule = rule.cssRules[mi];
+        if (!(mediaRule instanceof CSSStyleRule)) continue;
+        const selector = mediaRule.selectorText;
+        const jxMatch = selector.match(/\[data-jx="([^"]+)"\]/);
+        if (!jxMatch) continue;
+        const uid = jxMatch[1];
+        if (!overrides.has(uid)) overrides.set(uid, new Map());
+        const props = /** @type {Map<string, string>} */ (overrides.get(uid));
+        for (let i = 0; i < mediaRule.style.length; i++) {
+          const prop = mediaRule.style[i];
+          props.set(prop, mediaRule.style.getPropertyValue(prop));
+        }
+      }
+    }
+  }
+  return overrides;
+}
+
+/**
+ * Apply collected media overrides to elements within a canvas.
+ *
+ * @param {Element} canvasEl
+ * @param {Map<string, Map<string, string>>} overrides
+ */
+export function applyOverridesToCanvas(canvasEl, overrides) {
+  for (const [uid, props] of overrides) {
+    const els = canvasEl.querySelectorAll(`[data-jx="${uid}"]`);
+    for (const el of els) {
+      for (const [prop, val] of props) {
+        try {
+          /** @type {HTMLElement} */ (el).style.setProperty(prop, val);
+        } catch {}
+      }
+    }
+  }
+}