@panphora/clayjs 0.1.0 → 0.2.0

package/src/options/options.js

@@ -0,0 +1,253 @@
+/**
+ * Option Visibility
+ *
+ * Shows/hides elements based on `option:` and `option-not:` attributes.
+ *
+ * SYNTAX:
+ *   option:name="value"       - Show when ancestor has name="value"
+ *   show-when:name="value"    - Same as option: (the canonical, sapjs-aligned spelling)
+ *   option:name="a|b|c"       - Show when ancestor has name="a" OR "b" OR "c"
+ *   option:name=""            - Show when ancestor has name="" (empty value)
+ *   option:name="|saved"      - Show when ancestor has name="" OR name="saved"
+ *   hide-when:name="value"    - Inverse of show-when: hide WHEN ancestor has name="value"
+ *   option-not:name="value"   - Show when ancestor has name attr but ≠ "value"
+ *   option-not:name="a|b"     - Show when ancestor has name attr but ≠ "a" AND ≠ "b"
+ *
+ * show-when:/hide-when: are honored identically here and in sapjs, so visibility
+ * authored against either library just works. option:/option-not: stay permanent
+ * aliases.
+ *
+ * EXAMPLES:
+ *   <div view="kanban">
+ *     <button option:view="kanban">Visible when view=kanban</button>
+ *     <button option:view="list">Hidden</button>
+ *   </div>
+ *
+ * The ancestor carries the plain attribute (view="kanban"); descendants opt in with
+ * option:view / option-not:view. editmode/pageowner are stamped on <html> by clay.js,
+ * so option:/show-when:editmode is an edit-mode bridge that sapjs honors too.
+ *
+ *   <div savestatus="error">
+ *     <span option:savestatus="saved|error">Visible (matches error)</span>
+ *     <span option-not:savestatus="saving">Visible (error ≠ saving)</span>
+ *   </div>
+ *
+ * HOW IT WORKS:
+ * Uses a single conditional-hide rule per pattern. Elements get `display: none !important`
+ * ONLY when they are NOT inside a matching ancestor scope. When the ancestor condition
+ * IS met, the hide rule doesn't match, so the author's original display value
+ * (flex, grid, block, etc.) applies naturally — no recovery needed.
+ *
+ * BROWSER SUPPORT:
+ * Requires `:is()` and `:not()` with selector lists (~96% of browsers, 2021+).
+ * Falls back gracefully - elements remain visible if unsupported.
+ *
+ * TRADEOFFS:
+ * - Pro: Pure CSS after generation, zero JS overhead for toggling
+ * - Pro: No @layer or revert-layer — works with any author CSS (layered or unlayered)
+ * - Pro: One rule per pattern instead of two
+ * - Con: Pipe character `|` cannot be used as a literal value (reserved as OR delimiter)
+ */
+
+import Mutation from "../lib/mutation.js";
+import insertStyles from "../dom/insert-style-tag.js";
+
+const STYLE_NAME = 'option-visibility';
+
+// The visibility prefixes, longest-disambiguating first. show-when/option are the
+// "show when match" pair; hide-when is its inverse; option-not is "present but not
+// match". All four compile to ancestor-attribute CSS below.
+const OPTION_PREFIXES = [
+  { prefix: 'option-not', kind: 'show-not' },
+  { prefix: 'option', kind: 'show' },
+  { prefix: 'show-when', kind: 'show' },
+  { prefix: 'hide-when', kind: 'hide' },
+];
+
+/**
+ * Parse an option:/option-not:/show-when:/hide-when: attribute into a pattern object.
+ * Pure function for easy testing.
+ *
+ * @param {string} attrName - Attribute name (e.g., 'show-when:editmode', 'option-not:status')
+ * @param {string} attrValue - Attribute value (e.g., 'true', 'a|b|c')
+ * @returns {Object|null} Pattern object or null if not a valid visibility attribute
+ */
+export function parseOptionAttribute(attrName, attrValue) {
+  let match = null;
+  for (const p of OPTION_PREFIXES) {
+    if (attrName.startsWith(p.prefix + ':')) { match = p; break; }
+  }
+  if (!match) return null;
+
+  const name = attrName.slice(match.prefix.length + 1);
+  const rawValue = attrValue;
+  // Split by pipe, keep empty strings (they match empty attribute values)
+  const values = rawValue.split('|');
+
+  return { name, rawValue, values, kind: match.kind, prefix: match.prefix, negated: match.kind === 'show-not' };
+}
+
+const optionVisibility = {
+  debug: false,
+  _started: false,
+  _unsubscribe: null,
+
+  log(...args) {
+    if (this.debug) console.log('[OptionVisibility]', ...args);
+  },
+
+  /**
+   * Find all unique option:/option-not: patterns using XPath
+   * Returns array of { name, rawValue, values, negated }
+   */
+  findOptionAttributes() {
+    const patterns = new Map();
+
+    try {
+      const snapshot = document.evaluate(
+        '//*[@*[starts-with(name(), "option:") or starts-with(name(), "option-not:") or starts-with(name(), "show-when:") or starts-with(name(), "hide-when:")]]',
+        document.documentElement,
+        null,
+        XPathResult.UNORDERED_NODE_SNAPSHOT_TYPE,
+        null
+      );
+
+      for (let i = 0; i < snapshot.snapshotLength; i++) {
+        const el = snapshot.snapshotItem(i);
+        for (const attr of el.attributes) {
+          const pattern = parseOptionAttribute(attr.name, attr.value);
+          if (!pattern) continue;
+
+          // key includes the prefix so each authored spelling gets its own rule
+          // (option:tab and show-when:tab target different attributes, same scope).
+          const key = `${pattern.prefix}:${pattern.name}=${pattern.rawValue}`;
+          if (!patterns.has(key)) {
+            patterns.set(key, pattern);
+          }
+        }
+      }
+    } catch (error) {
+      this.log('XPath error, falling back to empty', error);
+    }
+
+    return [...patterns.values()];
+  },
+
+  /**
+   * Generate CSS rules for conditional hiding.
+   *
+   * Each pattern produces a single rule that hides the element ONLY when
+   * it's NOT inside a matching ancestor scope. When the condition IS met,
+   * the rule doesn't match, so the author's original display value applies.
+   */
+  generateCSS(patterns) {
+    if (!patterns.length) return '';
+
+    return patterns.map((pattern) => {
+      const { name, rawValue, values } = pattern;
+      // Tolerate the legacy {negated} pattern shape so external callers keep working.
+      const kind = pattern.kind || (pattern.negated ? 'show-not' : 'show');
+      const prefix = pattern.prefix || (kind === 'show-not' ? 'option-not' : kind === 'hide' ? 'hide-when' : 'option');
+      const safeName = CSS.escape(name);
+      const safeRawValue = CSS.escape(rawValue);
+      const safePrefix = CSS.escape(prefix);
+      const attrSelector = `[${safePrefix}\\:${safeName}="${safeRawValue}"]`;
+
+      // The "matching scope": an ancestor (or self) carries name="value".
+      const self = values.map(v => `[${safeName}="${CSS.escape(v)}"]`);
+      const desc = values.map(v => `[${safeName}="${CSS.escape(v)}"] *`);
+      const matchScope = [...self, ...desc].join(',');
+
+      if (kind === 'hide') {
+        // hide-when: hide WHEN inside a matching scope — the inverse selector shape.
+        return `${attrSelector}:is(${matchScope}){display:none!important}`;
+      }
+
+      let scopeSelectors;
+      if (kind === 'show-not') {
+        // option-not: active when ancestor has attr but NOT any of the values
+        const notList = values.map(v => `[${safeName}="${CSS.escape(v)}"]`).join(',');
+        const scope = `[${safeName}]:not(${notList})`;
+        scopeSelectors = `${scope},${scope} *`;
+      } else {
+        // option / show-when: active when ancestor has ANY of the values
+        scopeSelectors = matchScope;
+      }
+
+      return `${attrSelector}:not(:is(${scopeSelectors})){display:none!important}`;
+    }).join('');
+  },
+
+  /**
+   * Update the style element with current rules
+   */
+  update() {
+    try {
+      const attributes = this.findOptionAttributes();
+      const css = this.generateCSS(attributes);
+      insertStyles(STYLE_NAME, css, (style) => {
+        style.setAttribute('clay', 'no-watch');
+      });
+      this.log(`Generated ${attributes.length} rules`);
+    } catch (error) {
+      console.error('[OptionVisibility] Error generating rules:', error);
+    }
+  },
+
+  start() {
+    if (this._started) return;
+
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', () => this.start(), { once: true });
+      return;
+    }
+
+    this._started = true;
+
+    this.update();
+
+    // selectorFilter only triggers on option:/option-not: attribute changes (new patterns).
+    // Ancestor attribute changes (e.g., editmode="true" -> "false") are handled
+    // automatically by the browser - CSS rules re-evaluate when attributes change.
+    this._unsubscribe = Mutation.onAnyChange({
+      debounce: 200,
+      selectorFilter: el => [...el.attributes].some(attr =>
+        attr.name.startsWith('option:') || attr.name.startsWith('option-not:') ||
+        attr.name.startsWith('show-when:') || attr.name.startsWith('hide-when:')
+      ),
+      omitChangeDetails: true,
+      require: 'observed',
+      pausable: false
+    }, () => this.update());
+
+    this.log('Started');
+  },
+
+  stop() {
+    if (!this._started) return;
+
+    this._started = false;
+
+    if (this._unsubscribe) {
+      this._unsubscribe();
+      this._unsubscribe = null;
+    }
+
+    const style = document.querySelector(`style[data-name="${STYLE_NAME}"]`);
+    if (style) style.remove();
+
+    this.log('Stopped');
+  }
+};
+
+// vendor-compat mirror: sap reads window.hyperclay.optionVisibility at runtime.
+window.hyperclay = window.hyperclay || {};
+window.hyperclay.optionVisibility = optionVisibility;
+
+export default optionVisibility;
+
+export function init() {
+  optionVisibility.start();
+}
+
+init();

package/src/plugins/demo.js

@@ -0,0 +1,124 @@
+// Browser-backed demo mode: the page saves into the visitor's localStorage
+// instead of a server, and restores itself on the next load. Setup:
+//
+//   <html autosave demo-key="my-page-v1">          <!-- both attributes optional -->
+//   <script>window.clayEditMode = true;</script>   <!-- before the clay.js tag -->
+//   <script src="https://clayjs.com/clay.js?plugins=demo"></script>
+//
+// The fetch shim answers POST /_/save the way a clayjs server would, so the
+// whole real pipeline (savestatus, events, autosave, ⌘S) runs unchanged. The
+// stored body comes from the clay:snapshot-ready clone (pre-strip, the same
+// source live-sync morphs from), not the POSTed payload: the payload has
+// richclay's runtime state stripped, and morphing toward it would disable the
+// live editors. richclay chrome and squire artifacts are dropped from storage
+// because richclay recreates them. The shim answers after a short delay:
+// localStorage is instant, and the saving state only shows past save.js's
+// 500ms debounce, so an instant answer would keep it invisible.
+//
+// The storage key includes <html demo-key> (fallback: the page's pathname).
+// Bump the attribute whenever the page's authored content changes, or
+// returning visitors' old saved bodies morph over the new page.
+
+import { morph } from "../vendor/hyper-morph.vendor.js";
+
+const KEY = "clay:demo:" +
+  (document.documentElement.getAttribute("demo-key") || window.location.pathname);
+const LATENCY_MS = 800;
+const CHROME_SELECTOR = [
+  "[save-remove]",
+  "[data-richclay-toolbar]",
+  "[data-richclay-menu]",
+  "[data-richclay-dialog]",
+  "[data-richclay-live]",
+  "[data-richclay-float]",
+  "#squire-selection-start",
+  "#squire-selection-end",
+  ".squire-image-resize-container",
+].join(",");
+
+let failNextSave = false;
+let snapshotBody = null;
+
+document.addEventListener("clay:snapshot-ready", (event) => {
+  snapshotBody = event.detail.documentElement.querySelector("body")?.outerHTML || null;
+});
+
+function postedHtml(raw) {
+  const text = typeof raw === "string" ? raw : "";
+  try {
+    const envelope = JSON.parse(text);
+    if (envelope && typeof envelope === "object") {
+      return envelope.snapshotHtml || envelope.content || text;
+    }
+  } catch {}
+  return text;
+}
+
+const realFetch = window.fetch.bind(window);
+
+function isSaveUrl(input) {
+  const target = typeof input === "string" ? input : (input && input.url) || "";
+  try {
+    const path = new URL(target, window.location.href).pathname;
+    return path === "/_/save" || path.startsWith("/_/save/");
+  } catch {
+    return false;
+  }
+}
+
+window.fetch = (url, options = {}) => {
+  const method = (options.method || (url && url.method) || "GET").toUpperCase();
+  if (method !== "POST" || !isSaveUrl(url)) {
+    return realFetch(url, options);
+  }
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      if (failNextSave) {
+        failNextSave = false;
+        resolve(new Response(JSON.stringify({ msg: "Server not responding", msgType: "error" }), {
+          status: 503,
+          headers: { "Content-Type": "application/json" },
+        }));
+        return;
+      }
+      const html = snapshotBody || postedHtml(options.body);
+      const doc = new DOMParser().parseFromString(html, "text/html");
+      doc.querySelectorAll(CHROME_SELECTOR).forEach((node) => node.remove());
+      try {
+        localStorage.setItem(KEY, doc.body.outerHTML);
+      } catch {
+        resolve(new Response(JSON.stringify({ msg: "Couldn't save in this browser (storage is full or blocked)", msgType: "error" }), {
+          status: 507,
+          headers: { "Content-Type": "application/json" },
+        }));
+        return;
+      }
+      resolve(new Response(JSON.stringify({ msg: "Saved in your browser", msgType: "success" }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      }));
+    }, LATENCY_MS);
+  });
+};
+
+async function restore() {
+  const saved = localStorage.getItem(KEY);
+  if (!saved) return;
+  const doc = new DOMParser().parseFromString(saved, "text/html");
+  await morph(document.body, doc.body, {
+    morphStyle: "outerHTML",
+    ignoreActiveValue: true,
+    scripts: { handle: true, matchMode: "smart" },
+  });
+}
+
+export const ready = restore();
+
+export const demo = {
+  key: KEY,
+  failNext() { failNextSave = true; },
+  reset() {
+    localStorage.removeItem(KEY);
+    window.location.reload();
+  },
+};

package/src/sync/live-sync.js

@@ -39,6 +39,7 @@ import { HyperMorph, morph } from "../vendor/hyper-morph.vendor.js";
 import Mutation from "../lib/mutation.js";
 import { isSnapshotRemoved } from "../lib/region-policy.js";
 import { isEditMode } from "../core/is-edit-mode.js";
+import { mergeTagRecognizers } from "./merge-tags.js";
 
 class LiveSync {
   constructor() {
@@ -639,7 +640,17 @@ class LiveSync {
         morphStyle: 'outerHTML',
         ignoreActiveValue: true,
         head: { style: 'merge' },
-        scripts: { handle: true, matchMode: 'smart' },
+        // mergeBase: mergeable script tags ([merge] + rules tags) three-way
+        // merge against the last synced state instead of being clobbered by
+        // the incoming save; lastHtml is exactly that base (set after every
+        // own save and every applied morph). Null on the first update →
+        // two-way merge, which still keeps local-only keys.
+        scripts: {
+          handle: true,
+          matchMode: 'smart',
+          mergeBase: this.lastHtml,
+          mergeTags: mergeTagRecognizers
+        },
         key,
         callbacks: { afterNodeMorphed }
       });

package/src/sync/merge-tags.js

@@ -0,0 +1,36 @@
+/**
+ * merge-tags.js — extra mergeable script-tag recognizers for hyper-morph.
+ *
+ * hyper-morph's built-in recognizer handles `merge="<name>"` tags with
+ * relaxed JSON. This adds the Hyperclay rules-tag family (hypercms and
+ * hyper-html-api): `script[data-rules-name][data-rules-version]`, whose
+ * bodies use the rules dialect (unquoted selector barewords become strings).
+ * Identity is the version plus the sorted name-token list, so token order
+ * never matters and differing schema versions never pair. Parsing goes
+ * through hyper-morph's parseRulesRelaxed, the canonical port of the
+ * engine's parseRelaxed, so the tags merge exactly as they load.
+ *
+ * Pass as `scripts: { mergeTags: mergeTagRecognizers }` on morph configs.
+ */
+
+import { HyperMorph } from "../vendor/hyper-morph.vendor.js";
+
+export const mergeTagRecognizers = [
+  {
+    match: (el) => el.hasAttribute("data-rules-name"),
+    identity: (el) => {
+      const names = (el.getAttribute("data-rules-name") || "")
+        .split(/\s+/)
+        .filter(Boolean)
+        .sort()
+        .join(" ");
+      if (!names) return null;
+      return (
+        "rules:" + (el.getAttribute("data-rules-version") || "") + ":" + names
+      );
+    },
+    parse: HyperMorph.parseRulesRelaxed,
+  },
+];
+
+export default mergeTagRecognizers;

package/src/ui/dialogs.js

@@ -0,0 +1,206 @@
+import themodal from "./modal.js";
+import onDomReady from "../lib/dom-ready.js";
+import toast from "./toast.js";
+import copyToClipboard from "../utils/copy-to-clipboard.js";
+
+const CLOSE_BUTTON_SVG = `<svg viewBox="0 0 134 134" fill="none" xmlns="http://www.w3.org/2000/svg"><path class="micromodal__close-bg" d="M132 132.5 1 1.5h131v131Z" /><path class="micromodal__close-x" fill-rule="evenodd" clip-rule="evenodd" d="M0 0h3v1.5h1.5V3H6v1.5h1.5V6H9v1.5h1.5V9H12v1.5h1.5V12H15v1.5h1.5V15H18v1.5h1.5V18H21v1.5h1.5V21H24v1.5h1.5V24H27v1.5h1.5V27H30v1.5h1.5V30H33v1.5h1.5V33H36v1.5h1.5V36H39v1.5h1.5V39H42v1.5h1.5V42H45v1.5h1.5V45H48v1.5h1.5V48H51v1.5h1.5V51H54v1.5h1.5V54H57v1.5h1.5V57H60v1.5h1.5V60H63v1.5h1.5V63H66v1.5h1.5V66H69v1.5h1.5V69H72v1.5h1.5V72H75v1.5h1.5V75H78v1.5h1.5V78H81v1.5h1.5V81H84v1.5h1.5V84H87v1.5h1.5V87H90v1.5h1.5V90H93v1.5h1.5V93H96v1.5h1.5V96H99v1.5h1.5V99h1.5v1.5h1.5v1.5h1.5v1.5h1.5v1.5h1.5v1.5h1.5v1.5h1.5v1.5h1.5v1.5h1.5v1.5h1.5v1.5h1.5v1.5h1.5v1.5h1.5v1.5h1.5v1.5h1.5v1.5h1.5v1.5h1.5v1.5h1.5v1.5h1.5v1.5h1.5v1.5h1.5v1.5h1.5v3h-3V132H129v-1.5h-1.5V129H126v-1.5h-1.5V126H123v-1.5h-1.5V123H120v-1.5h-1.5V120H117v-1.5h-1.5V117H114v-1.5h-1.5V114H111v-1.5h-1.5V111H108v-1.5h-1.5V108H105v-1.5h-1.5V105H102v-1.5h-1.5V102H99v-1.5h-1.5V99H96v-1.5h-1.5V96H93v-1.5h-1.5V93H90v-1.5h-1.5V90H87v-1.5h-1.5V87H84v-1.5h-1.5V84H81v-1.5h-1.5V81H78v-1.5h-1.5V78H75v-1.5h-1.5V75H72v-1.5h-1.5V72H69v-1.5h-1.5V69H66v-1.5h-1.5V66H63v-1.5h-1.5V63H60v-1.5h-1.5V60H57v-1.5h-1.5V57H54v-1.5h-1.5V54H51v-1.5h-1.5V51H48v-1.5h-1.5V48H45v-1.5h-1.5V45H42v-1.5h-1.5V42H39v-1.5h-1.5V39H36v-1.5h-1.5V36H33v-1.5h-1.5V33H30v-1.5h-1.5V30H27v-1.5h-1.5V27H24v-1.5h-1.5V24H21v-1.5h-1.5V21H18v-1.5h-1.5V18H15v-1.5h-1.5V15H12v-1.5h-1.5V12H9v-1.5H7.5V9H6V7.5H4.5V6H3V4.5H1.5V3H0V0ZM108.8 22h5.2v5.1h-2.6v2.6H109v2.6h-2.6v2.6h-2.6v2.5h-2.6v5.2h2.6V45h2.6v2.6h2.6v2.6h2.5v2.6h2.6V58h-5.1v-2.6h-2.6V53h-2.6v-2.6h-2.6v-2.6h-2.5v-2.6h-5.2v2.6H91v2.6h-2.6v2.6h-2.6v2.5h-2.6V58H78v-5.1h2.6v-2.6H83v-2.6h2.6v-2.6h2.6v-2.5h2.6v-5.2h-2.6V35h-2.6v-2.6h-2.6v-2.6h-2.5v-2.6H78V22h5.2v2.6h2.5V27h2.6v2.6h2.6v2.6h2.5v2.6h5.2v-2.6h2.5v-2.6h2.6v-2.6h2.6v-2.5h2.5V22Z" /></svg>`;
+const CONFIRM_BUTTON_SVG = `<div style="width: 28px;"><svg viewBox="0 0 60 33" fill="none" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M34.5 0.75H43.5V5.25H49V9.75H54.5V14.25H60V18.75H54.5V23.25H49V27.75H43.5V32.25H34.5V27.75H40V23.25H45.5V18.75H0V14.25H45.5V9.75H40V5.25H34.5V0.75Z" fill="white"/></svg></div>`;
+
+function createModal(promptText, yesCallback, extraContent = "", includeInput = false, defaultValue = "") {
+  const inputHtml = includeInput
+    ? `<div><input class="micromodal__input" type="text" value="${defaultValue}" required></div>`
+    : "";
+
+  themodal.html = `<div>
+    <div class="micromodal__heading">${promptText}</div>
+    ${inputHtml}
+    ${extraContent}
+  </div>`;
+  themodal.closeHtml = CLOSE_BUTTON_SVG;
+  themodal.yes = CONFIRM_BUTTON_SVG;
+
+  const promise = new Promise((resolve, reject) => {
+    themodal.onYes(() => {
+      let promptResult;
+      if (includeInput) {
+        promptResult = document.querySelector(".micromodal__input").value;
+        if (!promptResult) return false; // keep modal open on empty input
+      }
+      // Run the validation callback synchronously so a throw can keep the
+      // modal open (callers rely on this — e.g. delete-site confirms by
+      // throwing when the typed name doesn't match).
+      if (yesCallback) {
+        try {
+          yesCallback(promptResult);
+        } catch (err) {
+          toast(err.message || 'An error occurred', 'error');
+          return false; // keep modal open, user can retry
+        }
+      }
+      // Defer resolve so downstream .then() handlers don't fire inside this
+      // modal's onYes loop — themodal is a singleton, and chained ask()/
+      // consent() calls need a clean themodal to set up their state.
+      setTimeout(() => resolve(promptResult), 0);
+      return true; // allow modal to close
+    });
+
+    themodal.onNo = () => {
+      setTimeout(reject, 0);
+    };
+  });
+
+  themodal.open();
+
+  setTimeout(() => {
+    const modalContainer = document.querySelector('.micromodal-parent');
+    if (modalContainer) {
+      modalContainer.addEventListener('click', (event) => {
+        const btn = event.target.closest('[data-copy]');
+        if (btn) {
+          copyToClipboard(btn.dataset.copy);
+          toast('Copied', 'success');
+        }
+      });
+    }
+  }, 0);
+
+  // Fire-and-forget callers (e.g. consent(msg, cb) with no await) don't consume
+  // the reject path; dismissal now rejects, so swallow it here to avoid an
+  // unhandled rejection. Awaiters still observe the rejection via their await.
+  promise.catch(() => {});
+
+  return promise;
+}
+
+// Public API functions
+export function ask(promptText, yesCallback, defaultValue = "", extraContent = "") {
+  return createModal(promptText, yesCallback, extraContent, true, defaultValue);
+}
+
+export function consent(promptText, yesCallback, extraContent = "") {
+  return createModal(promptText, yesCallback, extraContent, false);
+}
+
+/**
+ * Display an informational modal with a title and optional content paragraphs
+ * @param {string} promptText - The title/heading text
+ * @param {...string} content - Additional content paragraphs (variadic)
+ * @returns {Promise} Resolves when user confirms, rejects on close
+ */
+export function tell(promptText, ...content) {
+  const contentHtml = content.length > 0
+    ? content.map(c => `<div class="micromodal__tell-content">${c}</div>`).join("")
+    : "";
+
+  themodal.html = `<div class="micromodal__tell">
+    <div class="micromodal__tell-title">${promptText}</div>
+    ${contentHtml}
+  </div>`;
+  themodal.closeHtml = CLOSE_BUTTON_SVG;
+  themodal.yes = CONFIRM_BUTTON_SVG;
+
+  const promise = new Promise((resolve, reject) => {
+    themodal.onYes(() => {
+      setTimeout(resolve, 0);
+      return true;
+    });
+
+    themodal.onNo = () => {
+      setTimeout(reject, 0);
+    };
+  });
+
+  themodal.open();
+
+  // See createModal: swallow the reject for fire-and-forget tell() callers;
+  // awaiters still observe it via their await.
+  promise.catch(() => {});
+
+  return promise;
+}
+
+/**
+ * Display a modal with a code snippet and copy functionality
+ * @param {string} title - The modal heading
+ * @param {string} content - The code to display
+ * @param {string} extraContent - Optional raw HTML rendered below the copy button.
+ *   Callers style their own container; use `<div class="snippet-warning">…</div>`
+ *   for the standard yellow-bordered warning box.
+ */
+export function snippet(title, content, extraContent = '') {
+
+  // Create the modal content with copy button
+  const modalContent = `
+    <div class="snippet-code-block">
+      <pre>${content}</pre>
+    </div>
+
+    <button type="button" class="micromodal__secondary-btn copy-snippet-btn" style="margin-bottom: 14px;">copy</button>
+
+    ${extraContent || ''}
+  `;
+
+  // Use the existing modal system
+  themodal.html = `<div>
+    <div class="micromodal__heading">${title}</div>
+    ${modalContent}
+  </div>`;
+
+  themodal.closeHtml = CLOSE_BUTTON_SVG;
+  themodal.yes = '';
+
+  const promise = new Promise((resolve) => {
+    // Local copy function
+    const handleCopy = function(event) {
+      if (event.target.closest('.copy-snippet-btn')) {
+        copyToClipboard(content);
+        toast('Copied to clipboard!', 'success');
+      }
+    };
+
+    // Add event listener to the modal container after it opens
+    setTimeout(() => {
+      const modalContainer = document.querySelector('.micromodal-parent');
+      if (modalContainer) {
+        modalContainer.addEventListener('click', handleCopy);
+      }
+    }, 0);
+
+    themodal.onYes(() => {
+      // Clean up the event listener synchronously — the DOM may be torn down
+      // before our deferred resolve fires otherwise.
+      const modalContainer = document.querySelector('.micromodal-parent');
+      if (modalContainer) {
+        modalContainer.removeEventListener('click', handleCopy);
+      }
+      setTimeout(resolve, 0);
+      return true;
+    });
+
+    themodal.onNo = () => {
+      const modalContainer = document.querySelector('.micromodal-parent');
+      if (modalContainer) {
+        modalContainer.removeEventListener('click', handleCopy);
+      }
+      setTimeout(resolve, 0);
+    };
+  });
+
+  themodal.open();
+
+  return promise;
+}
+
+// Auto-initialize - cleanup any leftover modal elements
+export function init() {
+  onDomReady(() => {
+    const micromodalParentElem = document.querySelector(".micromodal-parent");
+    if (micromodalParentElem) {
+      micromodalParentElem.remove();
+      document.body.style.overflow = "";
+    }
+  });
+}
+
+// Auto-init when module is imported
+init();

package/src/ui/index.js

@@ -0,0 +1,37 @@
+import toast, { toastPersistent } from "./toast.js";
+import themodal from "./modal.js";
+import { ask, consent, tell, snippet } from "./dialogs.js";
+
+// Attach the public surface explicitly (§2.3). We do NOT rely on toast.js /
+// dialogs.js evaluation side effects — their window auto-exports are stripped.
+const clay = (window.clay = window.clay || {});
+clay.toast = toast;
+clay.toastPersistent = toastPersistent;
+clay.ask = ask;
+clay.confirm = consent;   // hyperclayjs `consent` → clayjs `clay.confirm`
+clay.tell = tell;
+clay.snippet = snippet;
+clay.modal = themodal;
+
+// Toast globals are a carve-out because core's live-sync soft-reads exactly these
+// names. Only set them when absent, honoring "already have a toast library? keep yours".
+if (typeof window.toast === "undefined") window.toast = toast;
+if (typeof window.toastPersistent === "undefined") window.toastPersistent = toastPersistent;
+
+// vendor-compat mirror: sap reads window.hyperclay.consent (the legacy name for
+// clay.confirm). Never CREATE window.hyperclay here: sap's mutation bridge treats
+// any truthy window.hyperclay as "a hub is coming" and waits forever for it. Core
+// creates the object (with Mutation) and fires clay:mutation-ready; attach then.
+function mirrorConsent() {
+  if (window.hyperclay && !window.hyperclay.consent) window.hyperclay.consent = consent;
+}
+if (window.hyperclay) mirrorConsent();
+else document.addEventListener("clay:mutation-ready", mirrorConsent, { once: true });
+
+// Automatic save feedback. clay:save-saving stays deliberately silent (a toast for
+// a sub-second transient is noise). Keep your own toast lib? The events are public.
+document.addEventListener("clay:save-saved", () => toast("Saved", "success"));
+document.addEventListener("clay:save-error", () => toastPersistent("Couldn't save", "error"));
+document.addEventListener("clay:save-offline", () => toastPersistent("Offline, not saved", "warning"));
+
+export { toast, toastPersistent, ask, consent, tell, snippet, themodal };