@panphora/sapjs 0.2.0

package/src/lint.js

@@ -0,0 +1,229 @@
+// Mount-time static analysis. Loud, attributed, teaching failures: a structural
+// contradiction halts the whole app (no listeners arm, file bytes stay frozen);
+// warnings never halt. This is the agent-authorability gate.
+
+import { parseStateDecl, rowsOf, templateOf } from "./dom.js";
+import {
+  teachForAttr, RESERVED, HTML_GLOBALS, NATIVE_BOOLEANS, didYouMean, setBeacon,
+} from "./errors.js";
+
+const NATIVE_BOOLEAN_SET = new Set(NATIVE_BOOLEANS);
+// `editmode` is a hyperclayjs platform prefix (editmode:onclick etc.), not a Sap
+// verb. It is allow-listed here so Sap stays quiet about it when co-loaded; the
+// single entry covers the whole editmode:* family, so new editmode: attributes in
+// hyperclayjs need no change. Sap has no engine branch for it (it is a no-op in Sap).
+const COLON_PREFIXES = new Set(["calc", "text", "attr", "class", "css", "set", "move", "sort", "option", "option-not", "show-when", "hide-when", "editmode"]);
+// The show-when family compares against a literal attribute value (or `|`-list),
+// never a JS expression. An expression-shaped value means the author reached for
+// show= by mistake; catch it loudly instead of failing the match silently.
+const WHEN_PREFIXES = new Set(["show-when", "hide-when", "option", "option-not"]);
+const EXPR_SHAPED = /\b(?:state|item|root)\.|===|!==|&&|\|\||[()]|^\s*!/;
+const KNOWN_BARE = new Set([
+  "sap", "scope", "items", "item", "template", "bind", "show", "effect", "invalid",
+  "detail", "state", "transient", "confirm", "default", "persist", "sortable",
+  "trigger-add", "trigger-remove", "trigger-reset", "sap-ignore", "sap-error",
+  "no-save", "no-watch", "no-undo",
+  // hyperclayjs platform region markers (canonical + legacy aliases). sapjs tolerates
+  // them so a co-loaded region attribute inside a [sap] root is never flagged a typo.
+  "no-trigger-autosave", "freeze", "mutations-ignore", "save-remove", "save-ignore", "save-freeze",
+]);
+
+function isControl(el) {
+  return el.tagName === "INPUT" || el.tagName === "SELECT" || el.tagName === "TEXTAREA";
+}
+
+function isBound(el) {
+  return el.hasAttribute("bind");
+}
+
+// Walk every element under the app, skipping inert subtrees, calling visit(el).
+function walkAll(root, visit) {
+  visit(root);
+  for (const child of root.children) descend(child);
+  function descend(el) {
+    if (el.nodeType !== 1) return;
+    if (el.hasAttribute("sap-ignore") || el.hasAttribute("template")) {
+      // still scan template descendants for structural errors, but not sap-ignore
+      if (el.hasAttribute("sap-ignore")) return;
+    }
+    visit(el);
+    for (const c of el.children) descend(c);
+  }
+}
+
+export function lintApp(root, diag) {
+  let halted = false;
+  const halt = (code, el, info) => {
+    diag.error(code, el, info);
+    halted = true;
+  };
+
+  // moustaches in any text node
+  const tw = root.ownerDocument.createTreeWalker(root, 0x4 /* NodeFilter.SHOW_TEXT */);
+  let node;
+  while ((node = tw.nextNode())) {
+    if (/\{\{.*\}\}/.test(node.nodeValue || "")) {
+      halt("E02", node.parentElement || root, {
+        problem: "moustaches in text content are not a Sap feature",
+        fix: 'move the expression onto the element: text="state.x"',
+      });
+      break;
+    }
+  }
+
+  walkAll(root, (el) => {
+    const inDetail = el.closest && el.closest("[detail]");
+
+    for (const a of [...el.attributes]) {
+      const name = a.name;
+
+      // foreign-dialect attributes
+      const teach = teachForAttr(name);
+      if (teach) {
+        halt("E01", el, {
+          attr: name, expr: a.value,
+          problem: `"${name}" is a foreign-dialect attribute; Sap has no ${name.split(/[:=]/)[0]} directive`,
+          fix: teach + " — or wrap the subtree in sap-ignore if intentional",
+        });
+        continue;
+      }
+
+      // colon-prefixed attribute checks
+      if (name.includes(":")) {
+        const prefix = name.slice(0, name.indexOf(":"));
+        if (!COLON_PREFIXES.has(prefix)) {
+          const dym = didYouMean(prefix, [...COLON_PREFIXES]);
+          diag.warn("W03", el, {
+            attr: name,
+            problem: `unknown "${prefix}:" attribute`,
+            didYouMean: dym ? `${dym}:` : null,
+          });
+        } else if (WHEN_PREFIXES.has(prefix) && EXPR_SHAPED.test(a.value)) {
+          const field = name.slice(name.indexOf(":") + 1);
+          diag.warn("W04", el, {
+            attr: name, expr: a.value,
+            problem: `${prefix}: compares the "${field}" attribute against a literal value, not a JS expression`,
+            fix: `use show="${a.value}" for an expression, or a literal like ${prefix}:${field}="overview"`,
+          });
+        }
+      } else if (
+        !KNOWN_BARE.has(name) &&
+        !HTML_GLOBALS.has(name) &&
+        !NATIVE_BOOLEAN_SET.has(name) &&
+        !/^(data-|aria-|on)/.test(name) &&
+        !(name in el)
+      ) {
+        // Bare (no-colon) attribute that looks like a typo'd Sap directive. Only
+        // warn when it is near a known directive (didYouMean returns a match) and
+        // is not a native HTML attribute (no matching IDL property), so ordinary
+        // HTML attributes never trip it.
+        const dym = didYouMean(name, [...KNOWN_BARE]);
+        if (dym) {
+          diag.warn("W03", el, { attr: name, problem: `unknown "${name}" attribute`, didYouMean: dym });
+        }
+      }
+
+      // attr:hidden redirect
+      if (name === "attr:hidden") {
+        diag.warn("W03", el, { attr: name, problem: "attr:hidden paints the wrong attribute", fix: 'use show="expr"' });
+      }
+
+      // attr:value / attr:checked / attr:selected on a bound control
+      if ((name === "attr:value" || name === "attr:checked" || name === "attr:selected") && isBound(el)) {
+        halt("E30", el, { attr: name, problem: "attr: on a bound control collides with persist ownership", fix: "remove it; bind owns this attribute" });
+      }
+
+      // effect assigning value/checked on a bound control (rule-b side door)
+      if (name === "effect" && isBound(el) && /\b(value|checked)\s*=[^=]/.test(a.value)) {
+        halt("E30", el, { attr: name, expr: a.value, problem: "effect writes value/checked on a bound control (writes a stale value with no synthetic event)", fix: "write through onclick + Sap(this) instead" });
+      }
+
+      // text / show on a form control
+      if ((name === "text" || name.startsWith("text:") || name === "show") && isControl(el)) {
+        if (name === "show") {
+          // show on a control is allowed (visibility); only text paints are the error
+        } else {
+          halt("E18", el, { attr: name, problem: "paint belongs on output elements, not form controls", fix: "move the paint to an <output> or <span>" });
+        }
+      }
+    }
+
+    // state= declarations
+    if (el.hasAttribute("state")) {
+      const decls = parseStateDecl(el.getAttribute("state"));
+      const seen = new Set();
+      for (const d of decls) {
+        if (d.name.includes("-")) {
+          halt("E08", el, { attr: "state", problem: `field "${d.name}" is not a valid identifier (the hyphen parses as subtraction)`, fix: `rename to ${d.name.replace(/-/g, "")}` });
+        }
+        if (seen.has(d.name)) halt("E04", el, { attr: "state", problem: `field "${d.name}" is declared twice in one scope` });
+        seen.add(d.name);
+        if (RESERVED.has(d.name)) halt("E05", el, { attr: "state", problem: `"${d.name}" is a reserved Sap word` });
+        if (HTML_GLOBALS.has(d.name)) halt("E06", el, { attr: "state", problem: `"${d.name}" is a global HTML attribute name; pick another field name` });
+        // dialog state=open
+        if (d.name === "open" && el.tagName === "DIALOG") {
+          halt("E33", el, { attr: "state", problem: "dialog open is transient", fix: "use showModal() — declare state= only on <details> or popovers" });
+        }
+      }
+    }
+
+    // bind matrix mount errors
+    if (isBound(el)) {
+      if (el.hasAttribute("-")) { /* noop */ }
+      if (el.tagName === "INPUT") {
+        const t = (el.getAttribute("type") || "text").toLowerCase();
+        if (t === "file") halt("E32", el, { attr: "bind", problem: "files never serialize into an HTML file", fix: 'use no-save + effect instead of bind' });
+        if (t === "password" && !el.hasAttribute("transient")) {
+          halt("E31", el, { attr: "bind", problem: "a password must never serialize into a world-readable file", fix: "add transient to the password input" });
+        }
+      } else if (el.tagName !== "SELECT" && el.tagName !== "TEXTAREA") {
+        // A bind on a leaf reads/writes textContent. On a container (element
+        // children) that is not contenteditable, the first write would wipe the
+        // subtree — that is never a valid two-way control.
+        const ce = el.getAttribute("contenteditable");
+        const editable = ce != null && ce !== "false";
+        if (!editable && el.children.length > 0) {
+          halt("E20", el, { attr: "bind", problem: "bind on a container element is not a control; a write would overwrite its children", fix: "bind a control (input/select/textarea), a contenteditable, or an empty text leaf" });
+        }
+      }
+    }
+
+    // transient + persist are opposite intents on one control: transient strips
+    // the value every pass (never serialized); persist forces it into the saved
+    // bytes and wins, leaking exactly what transient promised to drop.
+    if (el.hasAttribute("transient") && el.hasAttribute("persist")) {
+      halt("E34", el, {
+        problem: "transient and persist are opposite: persist forces the live value into the saved bytes, leaking exactly what transient drops",
+        fix: "remove one — transient to keep it out of the file, or persist to save it",
+      });
+    }
+
+    // orphan item
+    if (el.hasAttribute("item") && !el.hasAttribute("template")) {
+      const list = el.parentElement;
+      if (!list || !list.hasAttribute("items")) {
+        halt("E10", el, { problem: "an [item] must be a direct child of an [items] list", fix: "wrap it in a container with items=\"name\"" });
+      }
+    }
+
+    // nested items inside detail
+    if (el.hasAttribute("items") && inDetail) {
+      halt("E17", el, { attr: "items", problem: "nested items inside a detail panel is a v1 mount error (nested collections ship in v1.1)" });
+    }
+
+    // list with trigger-add but no template
+    if (el.hasAttribute("items")) {
+      const targeted = root.querySelector(`[trigger-add="${el.getAttribute("items")}"]`);
+      if (!templateOf(el) && rowsOf(el).length === 0 && targeted) {
+        halt("E17", el, { attr: "items", problem: `trigger-add targets items="${el.getAttribute("items")}" but it has no [item template] to clone` });
+      }
+    }
+  });
+
+  if (halted) {
+    diag.halted = true;
+    diag.haltReason = diag.errors[0] ? diag.errors[0].code : "halt";
+    setBeacon(root, diag.haltReason);
+  }
+  return !halted;
+}

package/src/mount.js

@@ -0,0 +1,84 @@
+// Mount one [sap] root: lint, then (if clean) adopt the runtime stylesheet and
+// run the first synchronous pass. A halted app arms no listeners and writes nothing,
+// so its file bytes stay frozen. Returns the app record the scheduler drives.
+
+import { Diagnostics } from "./errors.js";
+import { lintApp } from "./lint.js";
+import { runPass } from "./pass.js";
+import { rehydrateControlFromAttributes } from "./control-serialize.js";
+
+const STYLE_ID = "sap-styles";
+const STYLE_TEXT =
+  "[item][template]{display:none!important}" +
+  "[hidden]{display:none!important}" +
+  "[sap-error]{outline:2px solid #e5484d;outline-offset:1px}";
+
+const styledDocs = new WeakSet();
+
+// Apply Sap's presentation rules without leaving a node in the saved file:
+// adoptedStyleSheets live in the CSSOM, not the DOM tree, so a Hyperclay save
+// never serializes them. Engines without constructable stylesheets fall back to
+// a <style> node, which does serialize but keeps the rules working everywhere.
+function injectStyles(doc) {
+  if (styledDocs.has(doc)) return;
+  const view = doc.defaultView;
+  const SheetCtor = view && view.CSSStyleSheet;
+  if (SheetCtor && "adoptedStyleSheets" in doc) {
+    try {
+      const sheet = new SheetCtor();
+      sheet.replaceSync(STYLE_TEXT);
+      doc.adoptedStyleSheets = [...doc.adoptedStyleSheets, sheet];
+      styledDocs.add(doc);
+      return;
+    } catch {
+      // Older engine: fall through to the serialized <style> node.
+    }
+  }
+  if (!doc.getElementById(STYLE_ID)) {
+    const style = doc.createElement("style");
+    style.id = STYLE_ID;
+    style.textContent = STYLE_TEXT;
+    (doc.head || doc.documentElement).appendChild(style);
+  }
+  styledDocs.add(doc);
+}
+
+let appSeq = 0;
+
+function now() {
+  return typeof performance !== "undefined" && performance.now ? performance.now() : 0;
+}
+
+export function mountApp(root) {
+  const name = root.id || root.getAttribute("sap") || `app-${appSeq++}`;
+  const diag = new Diagnostics(name);
+  const appRec = {
+    root, name, diag,
+    _state: null, _stats: null, _lastPass: null,
+    _passes: 0, _broken: false, _mountMs: 0, _mountWrites: 0,
+  };
+
+  const ok = lintApp(root, diag);
+  if (!ok) {
+    appRec.halted = true;
+    return appRec;
+  }
+
+  injectStyles(root.ownerDocument);
+
+  // Restore any persisted textarea values from data-value before the first read,
+  // so a [persist] textarea round-trips on load without a separate save step.
+  for (const ta of root.querySelectorAll("textarea[data-value]")) rehydrateControlFromAttributes(ta);
+
+  const t0 = now();
+  runPass(appRec, { trigger: "mount" });
+  appRec._mountMs = now() - t0;
+  appRec._mountWrites = appRec._stats ? appRec._stats.writes : 0;
+  if (appRec._mountWrites > 0) {
+    diag.warn("W30", root, {
+      problem: `${appRec._mountWrites} paint(s) ran at mount; the saved file was out of sync with its declared state`,
+      fix: "re-save once so the file mounts clean (a settled file writes nothing)",
+    });
+  }
+  return appRec;
+}

package/src/mutation-bridge.js

@@ -0,0 +1,195 @@
+// Universal DOM-mutation reactivity: sapjs re-derives when the page changes by ANY
+// means, not just its own delegated events. Two interchangeable backends sit behind
+// one MutationSource seam:
+//
+//   - hubSource:    when window.hyperclay.Mutation is present, ride the platform's
+//                   central, pause-gated observer. The hub already coordinates the
+//                   live-sync / undo pause windows, so we inherit them for free.
+//   - nativeSource: standalone, a sapjs-owned MutationObserver on document.body.
+//
+// Self-paint suppression: every pass runs inside withDomMutationPaused(), so a pass's
+// own DOM writes are vacuumed away from the bridge and never schedule another pass:
+//   - hub:    Mutation.pause()/resume() — the hub drains the pass's records to its
+//             NON-pausable consumers only, so our pausable subscription never sees them.
+//   - native: observer.takeRecords() at the pause boundary discards the pass's records
+//             before the browser delivers them.
+//
+// Exactly one source is active at a time. A native source CEDES to a hub that arrives
+// late (teardown + re-subscribe), so the two never observe at once. Degrades to a
+// plain no-op when neither a hub nor a MutationObserver is present.
+
+let activeSource = null;
+let installed = false;
+let lateHubListener = null;
+
+function hubSource(M) {
+  let unsub = null;
+  return {
+    kind: "hub",
+    subscribe(onChanges) {
+      // pausable (the default) is load-bearing: it is WHY the hub's resume()-drain
+      // routes our own pass's writes to non-pausable consumers only, excluding us.
+      const ret = M.onAnyChange({ debounce: 0, require: "observed" }, onChanges);
+      if (typeof ret === "function") unsub = ret;
+    },
+    suppress(fn) {
+      M.pause(); // bridges undo.pause + gates the pausable lanes (autosave included)
+      try { return fn(); } finally { M.resume(); }
+    },
+    teardown() { if (unsub) { try { unsub(); } catch { /* ignore */ } unsub = null; } },
+  };
+}
+
+function nativeSource() {
+  let observer = null;
+  return {
+    kind: "native",
+    subscribe(onChanges) {
+      observer = new MutationObserver((records) => onChanges(changesFromRecords(records)));
+      const target = (typeof document !== "undefined" && document.body) ||
+        (typeof document !== "undefined" && document.documentElement);
+      if (target) {
+        observer.observe(target, { childList: true, subtree: true, attributes: true, characterData: true });
+      }
+    },
+    suppress(fn) {
+      // No hub to gate us: drop our own pass's records before the browser delivers them.
+      // Pause undo too if it somehow exists hub-less (presence-guarded; normally it does not).
+      const u = typeof window !== "undefined" && window.hyperclay && window.hyperclay.undo;
+      if (u && u.pause) u.pause();
+      try {
+        return fn();
+      } finally {
+        if (observer) observer.takeRecords();
+        if (u && u.resume) u.resume();
+      }
+    },
+    teardown() { if (observer) { observer.disconnect(); observer = null; } },
+  };
+}
+
+// Normalize MutationRecords into the hub's change shape { type, element, parent },
+// mirroring the hub's added-subtree expansion and removed-node parent resolution, and
+// skipping sap-inert subtrees (sap-ignore / template) — the standalone analogue of the
+// hub's intake isInert drop.
+function changesFromRecords(records) {
+  const out = [];
+  for (const rec of records) {
+    if (rec.type === "attributes") {
+      const el = rec.target;
+      if (el && el.nodeType === 1 && !inertSubtree(el)) out.push({ type: "attribute", element: el });
+    } else if (rec.type === "characterData") {
+      const el = rec.target && rec.target.parentElement;
+      if (el && !inertSubtree(el)) out.push({ type: "characterData", element: el });
+    } else if (rec.type === "childList") {
+      for (const node of rec.addedNodes) {
+        if (node.nodeType !== 1 || inertSubtree(node)) continue;
+        out.push({ type: "add", element: node });
+        if (node.querySelectorAll) {
+          for (const desc of node.querySelectorAll("*")) {
+            if (!inertSubtree(desc)) out.push({ type: "add", element: desc });
+          }
+        }
+      }
+      for (const node of rec.removedNodes) {
+        if (node.nodeType !== 1) continue;
+        out.push({ type: "remove", element: node, parent: rec.target });
+      }
+    }
+  }
+  return out;
+}
+
+function inertSubtree(el) {
+  return !!(el.closest && el.closest("[sap-ignore],[template]"));
+}
+
+// Shared by both backends: resolve each change to its owning [sap] app and schedule it
+// once. Prune apps whose roots have left the DOM (keeps the per-batch cost O(apps), not
+// a full-document re-scan), and re-mount when a fresh [sap] root is injected.
+function scheduleAffectedApps(runtime, changes) {
+  runtime.pruneDisconnected();
+  const affected = new Set();
+  let needRemount = false;
+  for (const c of changes) {
+    const target = c.type === "remove" ? c.parent : c.element; // a removed node is detached
+    const app = target && runtime.appFor(target);
+    if (app) affected.add(app);
+    if (c.type === "add" && c.element && c.element.nodeType === 1 &&
+        c.element.hasAttribute && c.element.hasAttribute("sap") &&
+        !(runtime.isRegistered && runtime.isRegistered(c.element))) {
+      needRemount = true; // an injected [sap] root
+    }
+  }
+  if (needRemount) runtime.remountIfPresent();
+  for (const app of affected) if (app.root.isConnected) runtime.schedule(app, "mutation");
+}
+
+// The single suppression entry point. pass.js wraps the whole pass in this; it delegates
+// to the active source. With no source yet (pre-install / no DOM), it preserves the
+// historical undo-pause-if-present behavior so derived writes still stay off the undo stack.
+export function withDomMutationPaused(fn) {
+  if (activeSource) return activeSource.suppress(fn);
+  const u = typeof window !== "undefined" && window.hyperclay && window.hyperclay.undo;
+  if (u && u.pause && u.resume) {
+    u.pause();
+    try { return fn(); } finally { u.resume(); }
+  }
+  return fn();
+}
+
+function activate(source, runtime) {
+  installed = true;
+  activeSource = source;
+  source.subscribe((changes) => scheduleAffectedApps(runtime, changes));
+}
+
+// Idempotent. Called from mountAll/mount; re-arms after resetMutationBridge().
+export function installMutationBridge(runtime) {
+  if (installed) return;
+  if (typeof window === "undefined" || typeof document === "undefined") return;
+  const w = window;
+  const M = w.hyperclay && w.hyperclay.Mutation;
+
+  if (M && typeof M.onAnyChange === "function") { activate(hubSource(M), runtime); return; }
+
+  // No usable Mutation hub yet. We do NOT treat a bare window.hyperclay as a promise that
+  // a hub is coming: another library may merely own that namespace (e.g. a consent shim)
+  // and never publish a Mutation hub, which would strand us in a permanent wait with dead
+  // reactivity. So observe natively now and CEDE to a real hub if one arrives later
+  // (teardown + re-subscribe on the document-dispatched hyperclay:mutation-ready — a
+  // window-dispatched event is ignored, matching the hub's own target). The handoff is
+  // safe: passes are idempotent, so the brief pre-hub native window costs at most a little
+  // redundant work, never correctness, and the two never observe simultaneously.
+  if (typeof MutationObserver === "function") {
+    activate(nativeSource(), runtime);
+    lateHubListener = function onLateHub() {
+      const M2 = w.hyperclay && w.hyperclay.Mutation;
+      if (!M2) return;
+      document.removeEventListener("hyperclay:mutation-ready", lateHubListener);
+      lateHubListener = null;
+      if (activeSource) activeSource.teardown();
+      installed = false;
+      activate(hubSource(M2), runtime);
+    };
+    document.addEventListener("hyperclay:mutation-ready", lateHubListener);
+  }
+  // else: no DOM observer (SSR / ancient) -> event-only, exactly as before.
+}
+
+// Tear down and re-arm. Sap._reset() calls this so each test gets a fresh bridge that
+// reflects the current window.hyperclay; production never calls it.
+export function resetMutationBridge() {
+  if (activeSource) { try { activeSource.teardown(); } catch { /* ignore */ } }
+  if (lateHubListener && typeof document !== "undefined") {
+    document.removeEventListener("hyperclay:mutation-ready", lateHubListener);
+  }
+  activeSource = null;
+  installed = false;
+  lateHubListener = null;
+}
+
+// Test hook: which backend is active ("hub" | "native" | null).
+export function _activeSourceKind() {
+  return activeSource ? activeSource.kind : null;
+}