@panphora/clayjs 1.8.1 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panphora/clayjs",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "type": "module",
   "description": "clayjs: malleable HTML files. Save lifecycle for self-saving HTML.",
   "license": "MIT-0",
@@ -46,13 +46,13 @@
     "access": "public"
   },
   "scripts": {
-    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
+    "test": "node scripts/test-guard.mjs",
     "test:conformance": "UPDATE_GOLDENS=0 web-test-runner --config conformance/wtr.config.mjs",
     "conformance:update": "UPDATE_GOLDENS=1 web-test-runner --config conformance/wtr.config.mjs",
     "build:standalone": "node build.js --standalone",
     "prepack": "node build.js --standalone",
     "test:standalone": "node build.js --standalone && web-test-runner --config tests/browser/wtr.config.mjs",
-    "prepublishOnly": "npm test && npm run test:conformance && npm run test:standalone",
+    "prepublishOnly": "testbox run",
     "dev": "node tests/stub-server.mjs",
     "build": "npm run build:bevel && npm run build:skins && node build.js",
     "propagate:foundation": "node scripts/propagate-foundation.mjs",
@@ -73,9 +73,13 @@
     "esbuild": "^0.28.2",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
+    "jsdom": "^20.0.3",
+    "marked": "^18.0.14",
     "parse5": "^7.3.0",
     "playwright": "1.62.1",
-    "postcss": "^8.5.28"
+    "postcss": "^8.5.28",
+    "turndown": "^7.2.4",
+    "turndown-plugin-gfm": "^1.0.2"
   },
   "hyper": {
     "kind": "lib",

package/src/core/host-attrs.js

@@ -23,6 +23,17 @@ export const servedDocumentEtag =
     ? null
     : document.documentElement.getAttribute("documentetag") || null;
 
+// Whether the host serves this site privately, captured ONCE, for the same reason as
+// the etag above: it describes this response, and a morph may later rewrite the root.
+// null when the host said nothing (HTML Clay, Hyperclay Local, a downloaded copy) or
+// said something this library does not recognize.
+const SITE_VISIBILITIES = new Set(["private", "public"]);
+export const servedSiteVisibility = (() => {
+  if (typeof document === "undefined") return null;
+  const value = document.documentElement.getAttribute("sitevisibility");
+  return SITE_VISIBILITIES.has(value) ? value : null;
+})();
+
 let warnedAboutLegacyToken = false;
 
 /**

package/src/core/host-meta.js

@@ -1,8 +1,9 @@
 /**
  * host-meta.js — what this host can do (spec §5).
  *
- * The first discovery client clayjs has had. Not fetched at boot: the first
- * caller is the first file pick, so a page that never uploads never asks.
+ * The first discovery client clayjs has had. Not fetched at boot by core: the first
+ * caller is the first file pick, or the people plugin when a page asks for it, so a
+ * page that uses neither never asks.
  *
  * The spec's own rule about what counts as an answer is deliberately strict on
  * the way in and forgiving on the way out. Only a 2xx carrying a JSON object with
@@ -17,6 +18,29 @@ import { saveToken } from "./host-attrs.js";
 const META_PATH = "/_/meta";
 const META_TIMEOUT_MS = 6000;
 
+// How each answer came about, kept beside the answer rather than on it so its
+// shape never changes. "ok": a capability document. "none": no discovery on offer
+// (a 404, a file nobody is serving, a server that has never heard of the spec).
+// "failed": a host that should have answered did not (a 5xx, a timeout, a dropped
+// connection). Save and upload treat the last two alike; people must not, because
+// a host that failed to say who you are has not said you are nobody.
+const outcomes = new WeakMap();
+
+function settle(outcome, meta = bareHost()) {
+  outcomes.set(meta, outcome);
+  return meta;
+}
+
+/**
+ * How the discovery that produced `meta` ended: "ok", "none" or "failed".
+ *
+ * @param {Object} meta - an answer from hostMeta()
+ * @returns {"ok"|"none"|"failed"}
+ */
+export function hostMetaOutcome(meta) {
+  return outcomes.get(meta) ?? "none";
+}
+
 // The bare-core-host answer, which is also every failure's answer.
 function bareHost() {
   return { spec: null, extensions: [], document: null };
@@ -34,8 +58,9 @@ let refreshing = null;
  * `spec` and `extensions` describe the host and never change under a loaded
  * document, which is why one answer serves the whole page. The `document` block
  * does change: its `etag` ticks on every save, by anyone. A caller that needs a
- * current one passes `fresh`, which asks again and replaces the memoized answer,
- * and concurrent fresh callers still share one request.
+ * current one passes `fresh`, which asks again and replaces the memoized answer
+ * unless it failed where an earlier one succeeded, and concurrent fresh callers
+ * still share one request.
  *
  * @param {Object} [options]
  * @param {boolean} [options.fresh]
@@ -47,8 +72,15 @@ export function hostMeta({ fresh = false } = {}) {
     return inFlight;
   }
   if (!refreshing) {
+    const previous = inFlight;
     refreshing = fetchMeta().catch(bareHost).finally(() => { refreshing = null; });
-    inFlight = refreshing;
+    // The caller that asked for a fresh answer gets it, failure and all. The page keeps its
+    // last good answer: one 502 during a deploy must not turn uploads off for the session.
+    inFlight = refreshing.then(async (meta) => {
+      if (hostMetaOutcome(meta) === "ok" || !previous) return meta;
+      const last = await previous;
+      return hostMetaOutcome(last) === "ok" ? last : meta;
+    });
   }
   return refreshing;
 }
@@ -74,6 +106,9 @@ export function resetHostMeta() {
 }
 
 async function fetchMeta() {
+  // A file opened from disk has no host to ask, and fetch would only throw.
+  if (!/^https?:$/.test(window.location.protocol)) return settle("none");
+
   const token = saveToken();
   // A host that mints tokens answers discovery per token, because on a sandboxed
   // document the token is the only identity there is: the browser gives it an
@@ -99,25 +134,25 @@ async function fetchMeta() {
       redirect: "manual",
       signal: controller.signal
     });
-    if (!res.ok) return bareHost();
+    if (!res.ok) return settle(res.status >= 500 ? "failed" : "none");
     const text = await res.text();
-    if (!text) return bareHost();
+    if (!text) return settle("none");
 
     let body;
     try {
       body = JSON.parse(text);
     } catch (_) {
-      return bareHost();
+      return settle("none");
     }
-    if (!body || typeof body !== "object" || typeof body.spec !== "number") return bareHost();
+    if (!body || typeof body !== "object" || typeof body.spec !== "number") return settle("none");
 
-    return {
+    return settle("ok", {
       spec: body.spec,
       extensions: Array.isArray(body.extensions) ? body.extensions : [],
       document: body.document && typeof body.document === "object" ? body.document : null
-    };
+    });
   } catch (_) {
-    return bareHost();
+    return settle("failed");
   } finally {
     clearTimeout(timeoutId);
   }

package/src/core/is-edit-mode.js

@@ -1,6 +1,6 @@
 import cookie from "../lib/cookie.js";
 import query from "../lib/query.js";
-import { hasSaveToken, servedStaleToken } from "./host-attrs.js";
+import { hasSaveToken, servedStaleToken, servedSiteVisibility } from "./host-attrs.js";
 
 // Edit-mode precedence: an explicit ?editmode=true|false URL param wins, then an
 // authored `viewonly` attribute on <html> (a tool page that must never save its
@@ -47,7 +47,10 @@ const isEditMode = query.editmode
 
 const isOwner = Boolean(cookie.get("isAdminOfCurrentResource"));
 
+const siteVisibility = servedSiteVisibility;
+
 export {
   isEditMode,
-  isOwner
+  isOwner,
+  siteVisibility
 }

package/src/events/onpagemutation.js

@@ -2,8 +2,10 @@
    [onpagemutation] / [onglobalmutation] - Trigger code when ANY element on the page changes
 
    Usage:
-   <span onglobalmutation="this.textContent = All('li').length">0</span>
-   <span onpagemutation="this.textContent = All('li').length">0</span>
+   <span onglobalmutation="const n = String(All('li').length); if (this.textContent !== n) this.textContent = n">0</span>
+   <span onpagemutation="const n = String(All('li').length); if (this.textContent !== n) this.textContent = n">0</span>
+
+   Guard every write: writing into the page, even the same text, is a mutation and re-runs the handler.
 
    Both attributes are equivalent - onglobalmutation is the preferred name for clarity.
 */

package/src/lib/root-attrs.js

@@ -74,7 +74,12 @@ export const HOST_IDENTITY_ATTRS = ["documentid", "htmlclayid"];
 // Kept out of SAVE_TOKEN_ATTRS on purpose: host-attrs.js returns the first name it
 // finds in that list straight into the save URL, and a version stamp is not a
 // credential.
-export const HOST_RESPONSE_ATTRS = ["documentetag"];
+//
+// `sitevisibility` is the host telling the owner's tab whether this site is served
+// privately or publicly ("private" | "public"). It describes the response, not the
+// file: the same bytes are private today and public tomorrow, so it must never be
+// written to disk, and a peer tab's copy says nothing about what this tab was served.
+export const HOST_RESPONSE_ATTRS = ["documentetag", "sitevisibility"];
 
 // What a host may have injected, and therefore what has to be stripped before a save
 // and kept out of an incoming morph. Wider than what is READ, on purpose: the old token

package/src/loader-logic.js

@@ -36,6 +36,8 @@ export const PLUGIN_PATHS = {
   // injects its own editing toggle there and clayjs's edit-mode signal is a
   // superset of the cms's, so the plugin is present exactly when it can be used.
   upload:    { path: "plugins/upload.js",          editOnly: true,  default: false },
+  // Who is editing and who wrote what. Not editOnly: a reader still sees names.
+  people:    { path: "plugins/people.js",          editOnly: false, default: false },
   wire:      { path: "plugins/wire.js",            editOnly: false, default: false },
   // Edit mode only: the AI comment box is an editing gesture. Opt in with
   // `plugins=ai-edit`; it stays dormant on any host that does not list a ready
@@ -89,6 +91,7 @@ export const MODULES = {
   "plugins/cms.js":             () => import("./plugins/cms.js"),
   "plugins/quickcrop.js":       () => import("./plugins/quickcrop.js"),
   "plugins/upload.js":          () => import("./plugins/upload.js"),
+  "plugins/people.js":          () => import("./plugins/people.js"),
   "plugins/wire.js":            () => import("./plugins/wire.js"),
   "plugins/ai-edit.js":         () => import("./plugins/ai-edit.js"),
   "plugins/demo.js":            () => import("./plugins/demo.js"),
@@ -97,7 +100,7 @@ export const MODULES = {
 
 // `source` is last on purpose: its install captures a save clone, so it wants every
 // plugin that registers a document transform to have registered it first.
-const PLUGIN_ORDER = ["richclay", "indicator", "sortable", "undo", "quickcrop", "upload", "cms", "sync", "wire", "ai-edit", "demo", "source"];
+const PLUGIN_ORDER = ["richclay", "indicator", "sortable", "undo", "quickcrop", "upload", "people", "cms", "sync", "wire", "ai-edit", "demo", "source"];
 
 // A plugin that cannot do its whole job alone. hypercms reads the cropper through
 // a capability lookup (`clay.quickcrop`) and silently uploads the raw file when it

package/src/loader.js

@@ -1,5 +1,6 @@
 import { resolveModules, MODULES } from "./loader-logic.js";
 import onDomReady from "./lib/dom-ready.js";
+import { initTheme } from "./ui/theme.js";
 
 function domReady() {
   return new Promise((resolve) => onDomReady(resolve));
@@ -11,12 +12,14 @@ function domReady() {
 // previous release. A call shape that differs between them leaves the page with
 // no clayjs at all.
 export async function boot(base, params, readyResolve) {
+  initTheme();
+
   await domReady();                                    // Mutation observes document.body
                                                        // unconditionally, and a <head> placement
                                                        // would otherwise observe null
 
   const editMode = await MODULES["core/is-edit-mode.js"]();
-  const { isEditMode, isOwner } = editMode;
+  const { isEditMode, isOwner, siteVisibility } = editMode;
 
   // richclay's vendor build detects edit mode via this legacy global; set it
   // before any plugin import so its autoInit sees the right value. Overwrite
@@ -33,7 +36,7 @@ export async function boot(base, params, readyResolve) {
     loaded[path] = await MODULES[path](); // sequential: order is load-bearing
   }
 
-  assembleCore(loaded, { isEditMode, isOwner }, regionPolicy); // window.clay MUST be assembled
+  assembleCore(loaded, { isEditMode, isOwner, siteVisibility }, regionPolicy); // window.clay MUST be assembled
                                                                // before any plugin import
 
   for (const path of plan.plugins) {
@@ -65,7 +68,7 @@ export async function boot(base, params, readyResolve) {
   document.dispatchEvent(new CustomEvent("clay:ready", { detail: { clay: window.clay } }));
 }
 
-function assembleCore(loaded, { isEditMode, isOwner }, regionPolicy) {
+function assembleCore(loaded, { isEditMode, isOwner, siteVisibility }, regionPolicy) {
   const clay = window.clay;
 
   const mutation = loaded["lib/mutation.js"];
@@ -75,6 +78,7 @@ function assembleCore(loaded, { isEditMode, isOwner }, regionPolicy) {
     toggleEditMode: editModeMod.toggleEditMode,
     isEditMode,
     isOwner,
+    siteVisibility,
     Mutation: mutation.default,
     region: regionPolicy.windowRegionShape,
   });
@@ -124,6 +128,10 @@ function attachPluginMember(path, mod, loaded) {
     clay.cms = mod.cms || mod.default;
   } else if (path === "plugins/upload.js") {
     clay.upload = mod.upload || mod.default;
+  } else if (path === "plugins/people.js") {
+    clay.people = mod.people;
+    clay.author = mod.author;
+    Object.defineProperty(clay, "me", { get: mod.currentMe, configurable: true, enumerable: true });
   } else if (path === "plugins/wire.js") {
     clay.wire = mod.wire || mod.default;
   } else if (path === "plugins/ai-edit.js") {