@panphora/clayjs 0.6.0 → 0.6.1

package/README.md

@@ -19,8 +19,10 @@ query params on the script URL:
 <script src="/clay.js?plugins=sync,cms&exclude=indicator"></script>
 ```
 
-- `?plugins=` — add optional plugins: `sync`, `cms` (richclay, indicator, sortable, undo load by default in edit mode).
-- `?exclude=` — drop a default plugin.
+- `?plugins=` — add optional plugins: `sync`, `cms`, `undo`, `sortable`, `indicator`, `quickcrop`, `wire`.
+  Only `richclay` loads by default, and only in edit mode. `cms` brings `quickcrop` with it, because
+  the CMS uses it for `data-hcms-crop` image fields.
+- `?exclude=` — drop a plugin that would otherwise load (a default, or one another plugin pulled in).
 - `?editmode=false` — force view mode (URL param wins over everything below).
 
 ## Host attributes
@@ -52,8 +54,8 @@ clay.save();
 
 Edit mode exposes `clay.save()` (+ `clay.save.force()`), `clay.getHTML()`, `clay.addDocumentTransform(fn)`,
 `clay.onSnapshot(fn)`, `clay.toggleEditMode()`, `clay.isEditMode`, `clay.isOwner`, `clay.Mutation`,
-`clay.region`, `clay.cacheBust(el)`, plus `clay.undo` / `clay.cms` / `clay.morph` / `clay.RichClay`
-when those plugins load. View mode keeps only the always-available members (`toggleEditMode`, `isEditMode`, `isOwner`,
+`clay.region`, `clay.cacheBust(el)`, plus `clay.undo` / `clay.cms` / `clay.morph` / `clay.RichClay` /
+`clay.quickcrop` when those plugins load. View mode keeps only the always-available members (`toggleEditMode`, `isEditMode`, `isOwner`,
 `Mutation`, `region`, `ready`); edit-only members are simply absent.
 
 ## API
@@ -70,12 +72,18 @@ The contract starts at **0.3.0**: no name below changes without a major version.
 
 **`clay.js`** — `ready`, `save()`, `save.force()`, `getHTML()`, `addDocumentTransform(fn)`, `onSnapshot(fn)`,
 `toggleEditMode()`, `isEditMode`, `isOwner`, `Mutation`, `region`, `cacheBust(el)`, plus `undo` / `cms` / `morph` /
-`RichClay` when those plugins load. View mode keeps only the always-available members, as above.
+`RichClay` / `quickcrop` when those plugins load. View mode keeps only the always-available members, as above.
 
 `addDocumentTransform(fn)` runs your callback over a detached clone whenever the page
 prepares to save AND whenever it checks whether anything changed. Keep it pure and
 repeatable: it is a transform, not a "a save is happening" event.
 
+`quickcrop(file, options)` opens a crop modal over a File or Blob and resolves
+`{ blob, dataURL, width, height }`, or `null` if the person cancels. `aspect` (a number,
+or null for freeform), `type`, `quality`, `maxWidth`/`maxHeight` and `labels.confirm` are
+the options worth knowing. Its modal and injected stylesheet carry `save-remove`, so they
+never reach the saved file.
+
 `region` is the region-policy model: `resolveRegionPolicy`, `isInert`, `skipForPolicy`,
 `strictestPolicy`, the `PERSIST` and `REGION_ATTRS` token constants, and the
 `STRIP_FROM_SAVE`, `FREEZE_SELECTOR` and `STRIP_FROM_COMPARISON` selectors.

package/_headers

@@ -1,2 +1,14 @@
+# Cache-Control is declared once, on /*. Two matching blocks do not override,
+# they join: repeating this line under /src/* served every module a doubled
+# max-age, which a cache is free to treat as stale. /src/* inherits it and adds
+# only CORS.
+#
+# No stale-while-revalidate: clay.js imports ~49 unversioned module URLs, each
+# with its own freshness clock, and a view-mode load fetches a different subset
+# than an edit-mode load. A stale window lets one browser hold half the graph
+# from before a deploy and half from after, which fails silently.
+/*
+  Cache-Control: public, max-age=600
+
 /src/*
   Access-Control-Allow-Origin: *

package/clay-events.js

@@ -20,7 +20,16 @@
     });
   }
 
+  // [onrender] sweeps the whole document the moment that import resolves, and those
+  // handlers routinely reach for clay-dom's element helpers (this.val, this.exec,
+  // this.nearest). The two satellites are independent dynamic imports with nothing
+  // ordering them, so on a cold load events can win and every handler throws
+  // "Cannot read properties of undefined". By DOM ready every satellite tag has run,
+  // so clay.loaded.dom is present exactly when clay-dom.js is on the page: wait for it
+  // then, proceed when it is absent. A clay-dom that failed to load must not take
+  // events down with it, so its rejection is swallowed here rather than chained.
   clay.loaded.events = domReady()
+    .then(function () { return clay.loaded.dom && clay.loaded.dom.catch(function () {}); })
     .then(function () { return import(base + "/src/events/index.js"); })
     .catch(function (err) { console.error("clay-events failed to load:", err); throw err; });
   // Mark handled: see clay-ui.js.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panphora/clayjs",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "type": "module",
   "description": "clayjs: malleable HTML files. Save lifecycle for self-saving HTML.",
   "license": "MIT",

package/src/core/host-meta.js

@@ -0,0 +1,107 @@
+/**
+ * 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 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
+ * a numeric `spec` is a capability document. A 404, an HTML error page from a
+ * proxy, a redirect, a body that will not parse: all of them mean "bare core
+ * host", and a bare core host is fully conforming. Discovery failing must never
+ * cost a person their save, so this never throws and never rejects.
+ */
+
+import { saveToken } from "./host-attrs.js";
+
+const META_PATH = "/_/meta";
+const META_TIMEOUT_MS = 6000;
+
+// The bare-core-host answer, which is also every failure's answer.
+function bareHost() {
+  return { spec: null, extensions: [], document: null };
+}
+
+let inFlight = null;
+
+/**
+ * Ask the host what it supports, once per page.
+ *
+ * Memoizes the PROMISE rather than the value, so two pickers opened together
+ * make one request instead of two and the second waits on the first.
+ *
+ * @returns {Promise<{spec: ?number, extensions: string[], document: ?Object}>}
+ */
+export function hostMeta() {
+  if (!inFlight) inFlight = fetchMeta().catch(bareHost);
+  return inFlight;
+}
+
+/**
+ * True when the host announced this capability by name.
+ *
+ * §5: a client must not infer a host's capabilities any other way. Not from the
+ * hostname, not from the port, not by probing a route to see whether it answers.
+ *
+ * @param {string} name
+ * @returns {Promise<boolean>}
+ */
+export async function hostSupports(name) {
+  const meta = await hostMeta();
+  return meta.extensions.includes(name);
+}
+
+/** Drop the memoized answer. Tests only. */
+export function resetHostMeta() {
+  inFlight = null;
+}
+
+async function fetchMeta() {
+  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
+  // opaque origin, so it holds no cookie and gets the answer any stranger would.
+  // Without this the `document` block, which carries whether this person may
+  // upload and how large a file the host takes, is unreachable on exactly the
+  // hosts that mint tokens.
+  const path = token ? `${META_PATH}/${token}` : META_PATH;
+
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), META_TIMEOUT_MS);
+  try {
+    const res = await fetch(new URL(path, window.location.origin).href, {
+      method: "GET",
+      // Same rule as the save lane. The token IS the credential, and a host that
+      // mints per-document tokens must never send Access-Control-Allow-Credentials
+      // back, so asking for cookies gets the answer blocked before it is read.
+      credentials: token ? "omit" : "same-origin",
+      headers: { "Document-URL": window.location.href },
+      cache: "no-store",
+      // A redirect is not an answer (§5), and following one would send the
+      // Document-URL header somewhere this host did not choose.
+      redirect: "manual",
+      signal: controller.signal
+    });
+    if (!res.ok) return bareHost();
+    const text = await res.text();
+    if (!text) return bareHost();
+
+    let body;
+    try {
+      body = JSON.parse(text);
+    } catch (_) {
+      return bareHost();
+    }
+    if (!body || typeof body !== "object" || typeof body.spec !== "number") return bareHost();
+
+    return {
+      spec: body.spec,
+      extensions: Array.isArray(body.extensions) ? body.extensions : [],
+      document: body.document && typeof body.document === "object" ? body.document : null
+    };
+  } catch (_) {
+    return bareHost();
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}

package/src/core/save.js

@@ -21,11 +21,23 @@ import {
 } from "./save-core.js";
 import { captureForComparison, captureForSaveAndComparison } from "./snapshot.js";
 import { gateCaptureToken, gateClearIfUnchanged } from "../lib/dirty-gate.js";
+import { ROOT_LIBRARY_ATTRS } from "../lib/root-attrs.js";
 import { logSaveCheck, logBaseline } from "../lib/autosave-debug.js";
 
-// Reset savestatus to 'saved' in snapshots (each module cleans up its own attrs)
+// Keep this library's own root state out of the saved bytes.
+//
+// This used to write `savestatus="saved"` onto the clone instead of removing it,
+// which stopped a mid-save "saving" from being baked in but still put a library
+// attribute on disk. It is there today in four LOCAL_APPS documents. These three
+// are this tab's UI truth, re-stamped on every load by edit-mode and by the save
+// lane itself, so a stored copy is at best noise and at worst a lie: a file whose
+// disk bytes say `savestatus="saved"` reads as saved before clayjs has booted.
+//
+// Scoped to the ROOT on purpose. `savestatus` on any other element is an authored
+// attribute that `option:savestatus` reads, and stripping those would delete page
+// content. Both clones get this, so the dirty comparison sees no difference.
 addDocumentTransform(clone => {
-  clone.setAttribute('savestatus', 'saved');
+  for (const name of ROOT_LIBRARY_ATTRS) clone.removeAttribute(name);
 });
 
 // ============================================

package/src/loader-logic.js

@@ -21,11 +21,27 @@ export const PLUGIN_PATHS = {
   sortable:  { path: "plugins/sortable.js",        editOnly: true,  default: false },
   undo:      { path: "plugins/undo.js",            editOnly: true,  default: false },
   cms:       { path: "vendor/hypercms.vendor.js",  editOnly: false, default: false },
+  quickcrop: { path: "vendor/quickcrop.vendor.js", editOnly: false, default: false },
+  // editOnly, because a file picker only ever appears in edit mode: the cms
+  // 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 },
   wire:      { path: "plugins/wire.js",            editOnly: false, default: false },
   demo:      { path: "plugins/demo.js",            editOnly: false, default: false },
 };
 
-const PLUGIN_ORDER = ["richclay", "indicator", "sortable", "undo", "cms", "sync", "wire", "demo"];
+const PLUGIN_ORDER = ["richclay", "indicator", "sortable", "undo", "quickcrop", "upload", "cms", "sync", "wire", "demo"];
+
+// 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
+// finds nothing, so `plugins=cms` has to bring quickcrop with it or image crop is
+// dead with no error and no log. quickcrop loads BEFORE cms in the order above,
+// because the loader attaches each plugin's member as it lands and cms reads what
+// earlier plugins attached during its own evaluation.
+// `upload` is deliberately NOT implied by cms yet. Adding it flips how an
+// existing page behaves, from embedding an image to storing it, and that is
+// isolated into its own one-line release so it can be reverted alone.
+const IMPLIES = { cms: ["quickcrop"] };
 
 function parseCsv(params, key, enabled, apply) {
   const raw = params.get(key);
@@ -50,6 +66,11 @@ export function resolveModules(params, isEditMode) {
     if (spec.default) enabled.add(name);
   }
   parseCsv(params, "plugins", enabled, (set, name) => set.add(name));
+  // Between the two: exclude still wins, so `plugins=cms&exclude=quickcrop` opts
+  // back out of the cropper.
+  for (const name of [...enabled]) {
+    for (const implied of IMPLIES[name] || []) enabled.add(implied);
+  }
   parseCsv(params, "exclude", enabled, (set, name) => set.delete(name));
 
   const plugins = [];

package/src/loader.js

@@ -102,12 +102,16 @@ function attachPluginMember(path, mod) {
     clay.morph = mod.morph;
   } else if (path === "vendor/hypercms.vendor.js") {
     clay.cms = mod.cms || mod.default;
+  } else if (path === "plugins/upload.js") {
+    clay.upload = mod.upload || mod.default;
   } else if (path === "plugins/wire.js") {
     clay.wire = mod.wire || mod.default;
   } else if (path === "plugins/demo.js") {
     clay.demo = mod.demo;
   } else if (path === "vendor/richclay.vendor.js") {
     clay.RichClay = mod.RichClay || mod.default;
+  } else if (path === "vendor/quickcrop.vendor.js") {
+    clay.quickcrop = mod.quickcrop || mod.default;
   }
 }
 

package/src/plugins/upload.js

@@ -0,0 +1,185 @@
+/**
+ * upload.js — store a file on the host instead of embedding it (spec §9).
+ *
+ * The problem this exists for: a document that cannot upload has to put the image
+ * INSIDE itself as a data: URL. A two megabyte photo then costs 2.7 MB of base64
+ * on this save, on every future save, and in every stored version. Embedding is
+ * the right answer for a file nobody is serving, and the wrong answer everywhere
+ * else, and until now clayjs had no way to tell the difference.
+ *
+ *   const result = await clay.upload(file, { onProgress, signal });
+ *   // { ok, msg, msgType, code, uploads }
+ *
+ * The result NEVER rejects, matching the save lane. One shape from every exit,
+ * because two channels for three outcomes (stored, cannot store here, failed) is
+ * the exact pattern save-core.js documents as the source of its own past bugs: a
+ * "cannot store here" thrown as an error reads as a failure, and a caller that
+ * catches it embeds when it should have stopped, or stops when it should have
+ * embedded.
+ *
+ * Codes a caller branches on:
+ *   unsupported       this host does not store files; embedding is correct
+ *   payment-required  the host stores files, but not for this account
+ *   too-large         over the host's cap, refused here or by the host
+ *   unsupported-type  the host will not store this kind of file
+ *   timeout           no answer; the upload may or may not have landed
+ */
+
+import { hostMeta } from "../core/host-meta.js";
+import { saveToken } from "../core/host-attrs.js";
+
+const UPLOAD_PATH = "/_/upload";
+const UPLOAD_TIMEOUT_MS = 120000;
+
+function result(ok, msg, msgType, code, uploads = []) {
+  return { ok, msg, msgType, code, uploads };
+}
+
+function emit(name, detail) {
+  if (typeof document === "undefined") return;
+  document.dispatchEvent(new CustomEvent(`clay:upload-${name}`, { detail }));
+}
+
+/**
+ * Store one file on the host.
+ *
+ * @param {File|Blob} file
+ * @param {Object} [options]
+ * @param {function} [options.onProgress] - ({loaded, total, percent})
+ * @param {AbortSignal} [options.signal]
+ * @returns {Promise<{ok: boolean, msg: string, msgType: string, code: ?string, uploads: Array}>}
+ */
+export async function upload(file, { onProgress, signal } = {}) {
+  if (!file) return result(false, "No file to upload", "error", "bad-request");
+
+  const meta = await hostMeta();
+  if (!meta.extensions.includes("upload")) {
+    // Not an error. This is a document open from a plain file server, or a bare
+    // core host, and embedding is what it should do.
+    return result(false, "This host does not store uploaded files", "skipped", "unsupported");
+  }
+
+  // The one local pre-check the spec asks for, and the only reason `maxBytes` is
+  // published: refusing a 40 MB photo here costs nothing, and sending it to be
+  // refused costs the person the whole upload first. Deliberately the ONLY thing
+  // decided locally. `document.upload.allowed` is not read as a veto: it can be
+  // stale (a plan upgraded in another tab, a share link granted since load), and
+  // the host answers the real reason with its own code on the request itself.
+  const cap = meta.document?.upload?.maxBytes;
+  if (typeof cap === "number" && cap > 0 && file.size > cap) {
+    return result(false, `That file is larger than this host accepts (${cap} bytes)`, "error", "too-large");
+  }
+
+  return send(file, { onProgress, signal });
+}
+
+function send(file, { onProgress, signal }) {
+  return new Promise((resolve) => {
+    const token = saveToken();
+    const path = token ? `${UPLOAD_PATH}/${token}` : UPLOAD_PATH;
+    // Absolute against the real origin, never left relative: a <base href> in the
+    // authored document would otherwise redirect this request, and the
+    // per-document token in its path, to an origin the document chose.
+    const url = new URL(path, window.location.origin).href;
+
+    // XMLHttpRequest for one reason: fetch cannot report upload progress. A photo
+    // over a phone connection is the case this whole capability is for, and a
+    // picker that sits there saying nothing for twenty seconds reads as broken.
+    const xhr = new XMLHttpRequest();
+    let settled = false;
+
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeoutId);
+      if (signal) signal.removeEventListener("abort", onAbort);
+      resolve(value);
+    };
+
+    const fail = (msg, msgType, code) => {
+      emit("error", { msg, code });
+      finish(result(false, msg, msgType, code));
+    };
+
+    const timeoutId = setTimeout(() => {
+      xhr.abort();
+      // A timeout is not evidence the upload failed. The bytes may well have
+      // landed, so this says "we do not know" rather than asserting a failure,
+      // and the content-hash name makes the retry idempotent if the caller resends.
+      fail("Upload timed out", "unknown", "timeout");
+    }, UPLOAD_TIMEOUT_MS);
+
+    const onAbort = () => {
+      xhr.abort();
+      finish(result(false, "Upload cancelled", "skipped", "aborted"));
+    };
+    if (signal) {
+      if (signal.aborted) return onAbort();
+      signal.addEventListener("abort", onAbort);
+    }
+
+    xhr.upload.addEventListener("progress", (event) => {
+      if (!event.lengthComputable) return;
+      const detail = {
+        loaded: event.loaded,
+        total: event.total,
+        percent: Math.round((event.loaded / event.total) * 100)
+      };
+      emit("progress", detail);
+      if (onProgress) {
+        try { onProgress(detail); } catch (_) { /* a caller's drawing must not kill the upload */ }
+      }
+    });
+
+    xhr.addEventListener("load", () => {
+      let body = {};
+      try { body = JSON.parse(xhr.responseText || "{}"); } catch (_) { body = {}; }
+
+      if (xhr.status >= 200 && xhr.status < 300) {
+        const uploads = Array.isArray(body.uploads) ? body.uploads : [];
+        if (!uploads.length || typeof uploads[0]?.url !== "string") {
+          return fail("The host accepted the file but did not say where it put it", "error", "bad-response");
+        }
+        emit("done", { uploads });
+        return finish(result(true, body.msg ?? "Uploaded", body.msgType || "success", body.code ?? null, uploads));
+      }
+
+      // The host's own code when it sent one, so a caller branches on the reason
+      // rather than pattern-matching a message. Falling back to the status keeps
+      // a host that answers a bare 413 readable.
+      const code = body.code || STATUS_CODES[xhr.status] || "error";
+      return fail(body.msg || `Upload failed (${xhr.status})`, "error", code);
+    });
+
+    xhr.addEventListener("error", () => fail("Upload failed", "error", "network"));
+    xhr.addEventListener("abort", () => finish(result(false, "Upload cancelled", "skipped", "aborted")));
+
+    xhr.open("POST", url, true);
+    // The exact equivalent of the save lane's `credentials: 'omit'` in the case
+    // where the two differ: a sandboxed document is cross-origin to its own host,
+    // and asking for credentials there needs Access-Control-Allow-Credentials
+    // back, which a token-minting host must never send.
+    xhr.withCredentials = false;
+    xhr.setRequestHeader("Document-URL", window.location.href);
+
+    // FormData, so the file streams as bytes. No FileReader and no base64: a
+    // whole-file string costs a third more bytes and holds the entire file in
+    // memory twice.
+    const form = new FormData();
+    form.append("file", file, file.name || "upload");
+
+    emit("start", { name: file.name || null, size: file.size ?? null });
+    xhr.send(form);
+  });
+}
+
+const STATUS_CODES = {
+  402: "payment-required",
+  413: "too-large",
+  415: "unsupported-type",
+  401: "unauthorized",
+  403: "forbidden",
+  404: "not-found"
+};
+
+export default upload;