@panphora/clayjs 0.1.0 → 0.2.1

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() {
@@ -46,6 +47,15 @@ class LiveSync {
     this.currentFile = null;
     this.lastHtml = null;
     this.clientId = this.generateClientId();
+
+    // Per-stream resume id for the htmlclay replay server's wire contract.
+    // Regenerated on every start() (see below) so an explicit stop/start is a
+    // brand-new stream that never inherits the old baseline. Native
+    // EventSource reuses the same URL — and thus this id — on its own
+    // automatic reconnect. Deliberately NOT the sender clientId, which is the
+    // durable per-tab identity used for echo suppression.
+    this.resumeId = null;
+
     this.debounceMs = 150;
     this.debounceTimer = null;
     this.isPaused = false;
@@ -132,6 +142,21 @@ class LiveSync {
     return id;
   }
 
+  /**
+   * Generate a fresh per-stream resume id (URL-safe, well under the 128-byte
+   * wire limit). Minted on every start(), never persisted: an explicit
+   * stop/start must not reuse the previous stream's baseline.
+   */
+  generateResumeId() {
+    try {
+      const bytes = new Uint8Array(16);
+      (globalThis.crypto || window.crypto).getRandomValues(bytes);
+      return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+    } catch (e) {
+      return Math.random().toString(36).slice(2) + Date.now().toString(36);
+    }
+  }
+
   /**
    * Start the LiveSync system
    * Can be called after stop() to restart with a new file
@@ -152,9 +177,11 @@ class LiveSync {
       return;
     }
 
-    // Reset state for new connection
+    // Reset state for new connection. Resetting lastSeenSeq is a new baseline,
+    // so mint a fresh resume id — this stream must not resume the previous one.
     this.lastHtml = null;
     this.lastSeenSeq = 0;
+    this.resumeId = this.generateResumeId();
 
     console.log(`[LiveSync] Starting for: ${this.currentFile} (lane=${this.lane})`);
     this.connect();
@@ -360,7 +387,7 @@ class LiveSync {
     if (this.isDestroyed) return;
 
     const pageUrl = encodeURIComponent(window.location.href);
-    const url = `/_/live-sync/stream?page-url=${pageUrl}&lane=${this.lane}`;
+    const url = `/_/live-sync/stream?page-url=${pageUrl}&lane=${this.lane}&resume-id=${this.resumeId}`;
     this.sse = new EventSource(url);
 
     this.sse.onopen = () => {
@@ -371,6 +398,26 @@ class LiveSync {
     this.sse.onmessage = (event) => {
       const data = JSON.parse(event.data);
 
+      // Staleness check + watermark advance run FIRST — before the notification
+      // and error branches — against the high-water mark of seqs we've seen
+      // (own echoes count too, see below). Notification frames now carry a seq,
+      // so a conservative-cursor replay after reconnect must not duplicate a
+      // toast or let a later stale data frame apply an older snapshot. `seq` is
+      // optional for back-compat with older servers that don't stamp it.
+      const { seq } = data;
+      if (typeof seq === 'number' && seq <= this.lastSeenSeq) {
+        this._log(`Dropping stale message: seq=${seq}, lastSeen=${this.lastSeenSeq}`);
+        return;
+      }
+
+      // Advance the watermark before the notification/sender branches so that
+      // our own save echoes count toward "seen". Without this, a later
+      // buffered/replayed message with a smaller seq could rewind us past our
+      // local edit.
+      if (typeof seq === 'number') {
+        this.lastSeenSeq = seq;
+      }
+
       // Handle notifications (show toast, don't morph)
       if (data.type === "notification") {
         this.handleNotification(data);
@@ -384,22 +431,7 @@ class LiveSync {
         return;
       }
 
-      const { html, sender, seq, identityMap } = data;
-
-      // Staleness check runs FIRST — compared against the high-water mark of
-      // seqs we've seen (own echoes count too, see below). `seq` is optional
-      // for back-compat with older server builds that don't stamp it.
-      if (typeof seq === 'number' && seq <= this.lastSeenSeq) {
-        this._log(`Dropping stale message: seq=${seq}, lastSeen=${this.lastSeenSeq}`);
-        return;
-      }
-
-      // Advance the watermark before the sender filter so that our own save
-      // echoes count toward "seen". Without this, a later buffered/replayed
-      // peer message with a smaller seq could rewind us past our local edit.
-      if (typeof seq === 'number') {
-        this.lastSeenSeq = seq;
-      }
+      const { html, sender, identityMap } = data;
 
       // Ignore own changes — already reflected in the DOM, nothing to morph
       if (sender === this.clientId) {
@@ -639,7 +671,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;