@tinacms/bridge 0.0.0-0509095-20260525122024

package/LICENSE

@@ -0,0 +1,176 @@
+                                Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/dist/click-to-focus.d.ts

@@ -0,0 +1 @@
+export declare function initClickToFocus(): void;

package/dist/config.d.ts

@@ -0,0 +1,17 @@
+export declare function setAdminOrigin(origin: string | string[]): void;
+/**
+ * Returns the canonical admin origin used as the `targetOrigin` for outbound
+ * postMessage. When multiple origins are configured the first entry wins —
+ * that's the deployment's primary admin host; the others are accepted for
+ * inbound traffic but the bridge still posts to the canonical one.
+ */
+export declare function getAdminOrigin(): string;
+/**
+ * Returns true only for postMessage events that originated from the admin
+ * iframe parent — `event.origin` matches one of the configured admin
+ * origins AND `event.source` is the parent window. Both checks are
+ * required: origin alone leaves us open to sibling frames sharing the
+ * same origin, source alone leaves us open to cross-origin parents that
+ * happen to have a handle to our window.
+ */
+export declare function isFromAdmin(event: MessageEvent): boolean;

package/dist/data-store.d.ts

@@ -0,0 +1,10 @@
+import type { DataStore } from './types';
+/**
+ * Holds the latest resolved data per form id (keyed by `hashFromQuery`-style
+ * id). `seed()` populates the initial server-rendered payload silently so
+ * the bridge doesn't trigger a refresh on page load. `set()` records edits
+ * from the admin and fires subscribers; `firstUpdate` is true only for the
+ * first admin update per id (used by island-refresh to skip the debounce
+ * on cold-start so newly-created docs reach a populated state ASAP).
+ */
+export declare function initDataStore(): DataStore;

package/dist/debug.d.ts

@@ -0,0 +1 @@
+export declare function debug(...args: unknown[]): void;

package/dist/forms.d.ts

@@ -0,0 +1,9 @@
+import type { DataStore } from './types';
+export declare const FORM_SELECTOR = "[data-tina-form]";
+export declare const FORM_ATTR = "data-tina-form";
+export declare const PRIMARY_FORM_ATTR = "data-tina-primary";
+export declare function initForms(store: DataStore): void;
+/** Diff active forms against the DOM and post the deltas. Safe to call
+ *  before init() — no-op then. */
+export declare function refreshForms(): void;
+export declare function reportQuickEdit(): void;

package/dist/forms.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export interface BridgeOptions {
+    /** Debounce for refetches after the first edit. The first refetch
+     *  fires immediately. Default 300ms. */
+    debounceMs?: number;
+    /** Allowed origin(s) of the admin parent for in-iframe postMessage.
+     *  Defaults to `window.location.origin` (same-host `/admin`). */
+    adminOrigin?: string | string[];
+}
+export declare function init(options?: BridgeOptions): void;
+/**
+ * Re-scan for `[data-tina-form]` payloads after a soft navigation
+ * (Astro view transitions, Turbo, htmx). On a prerendered page with no
+ * server-injected payloads, prime from the island endpoints first.
+ */
+export declare function refreshForms(): void;
+export { tinaField } from './tina-field';
+export type * from './types';

package/dist/index.js

@@ -0,0 +1,529 @@
+let configuredAdminOrigins = [];
+function setAdminOrigin(origin) {
+  configuredAdminOrigins = Array.isArray(origin) ? [...origin] : [origin];
+}
+function getAdminOrigin() {
+  return configuredAdminOrigins[0] ?? "";
+}
+function isFromAdmin(event) {
+  if (typeof window === "undefined")
+    return false;
+  if (!configuredAdminOrigins.includes(event.origin))
+    return false;
+  return event.source === window.parent;
+}
+const ENABLED = typeof window !== "undefined";
+function debug(...args) {
+  if (!ENABLED)
+    return;
+  console.log("[@tinacms/bridge]", ...args);
+}
+const QUICK_EDIT_CSS = `
+  [data-tina-field] {
+    outline: 2px dashed rgba(34,150,254,0.5);
+    transition: box-shadow ease-out 150ms;
+  }
+  [data-tina-field]:hover {
+    box-shadow: inset 100vi 100vh rgba(34,150,254,0.3);
+    outline: 2px solid rgba(34,150,254,1);
+    cursor: pointer;
+  }
+  [data-tina-field-overlay] {
+    outline: 2px dashed rgba(34,150,254,0.5);
+    position: relative;
+  }
+  [data-tina-field-overlay]:hover {
+    cursor: pointer;
+    outline: 2px solid rgba(34,150,254,1);
+  }
+  [data-tina-field-overlay]::after {
+    content: '';
+    position: absolute;
+    inset: 0;
+    z-index: 20;
+    transition: opacity ease-out 150ms;
+    background-color: rgba(34,150,254,0.3);
+    opacity: 0;
+  }
+  [data-tina-field-overlay]:hover::after {
+    opacity: 1;
+  }
+`;
+const QUICK_EDIT_BODY_CLASS = "__tina-quick-editing-enabled";
+const QUICK_EDIT_STYLE_ID = "__tina-bridge-quick-edit-style";
+function initClickToFocus() {
+  let enabled = false;
+  document.addEventListener(
+    "click",
+    (event) => {
+      const target = event.target;
+      const tagName = target instanceof Element ? target.tagName : "?";
+      if (!enabled) {
+        debug("click ignored — quickEdit disabled", tagName);
+        return;
+      }
+      const fieldName = resolveFieldName(target);
+      if (!fieldName) {
+        debug("click ignored — no data-tina-field ancestor for", tagName);
+        return;
+      }
+      debug("click captured →", fieldName, "(target:", tagName, ")");
+      event.preventDefault();
+      event.stopPropagation();
+      window.parent.postMessage(
+        { type: "field:selected", fieldName },
+        getAdminOrigin()
+      );
+    },
+    true
+  );
+  window.addEventListener("message", (event) => {
+    if (!isFromAdmin(event))
+      return;
+    const message = event.data;
+    if (!message || message.type !== "quickEditEnabled")
+      return;
+    enabled = !!message.value;
+    if (enabled)
+      installStyle();
+    else
+      removeStyle();
+  });
+}
+function resolveFieldName(target) {
+  const el = target instanceof Element ? target : null;
+  if (!el)
+    return null;
+  const direct = readTinaField(el);
+  if (direct)
+    return direct;
+  const ancestor = el.closest("[data-tina-field], [data-tina-field-overlay]");
+  if (!ancestor)
+    return null;
+  return readTinaField(ancestor);
+}
+function readTinaField(el) {
+  for (const name of el.getAttributeNames()) {
+    if (name.startsWith("data-tina-field")) {
+      const value = el.getAttribute(name);
+      if (value)
+        return value;
+    }
+  }
+  return null;
+}
+function installStyle() {
+  if (document.getElementById(QUICK_EDIT_STYLE_ID))
+    return;
+  const style = document.createElement("style");
+  style.id = QUICK_EDIT_STYLE_ID;
+  style.textContent = QUICK_EDIT_CSS;
+  document.head.appendChild(style);
+  document.body.classList.add(QUICK_EDIT_BODY_CLASS);
+}
+function removeStyle() {
+  var _a;
+  (_a = document.getElementById(QUICK_EDIT_STYLE_ID)) == null ? void 0 : _a.remove();
+  document.body.classList.remove(QUICK_EDIT_BODY_CLASS);
+}
+function initDataStore() {
+  const data = /* @__PURE__ */ new Map();
+  const updated = /* @__PURE__ */ new Set();
+  const listeners = /* @__PURE__ */ new Set();
+  return {
+    get: (id) => data.get(id),
+    has: (id) => data.has(id),
+    seed(id, next) {
+      data.set(id, next);
+    },
+    set(id, next) {
+      const firstUpdate = !updated.has(id);
+      updated.add(id);
+      data.set(id, next);
+      for (const listener of listeners)
+        listener({ id, firstUpdate });
+    },
+    ids: () => Array.from(data.keys()),
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    }
+  };
+}
+const FORM_SELECTOR = "[data-tina-form]";
+const FORM_ATTR = "data-tina-form";
+const PRIMARY_FORM_ATTR = "data-tina-primary";
+const RETRY_INTERVAL_MS = 250;
+const MAX_ATTEMPTS = 40;
+let controller = null;
+function initForms(store) {
+  if (controller) {
+    debug("initForms called twice; ignoring");
+    return;
+  }
+  controller = {
+    store,
+    active: /* @__PURE__ */ new Map(),
+    acknowledged: /* @__PURE__ */ new Set(),
+    primaryId: null,
+    retryTimer: null,
+    attempts: 0
+  };
+  window.addEventListener("message", onAck);
+  window.addEventListener("beforeunload", onBeforeUnload);
+}
+function refreshForms$1() {
+  if (!controller) {
+    debug("refreshForms called before initForms; ignoring");
+    return;
+  }
+  const { payloads: next, primaryId } = readPayloads();
+  const nextIds = new Set(next.map((p) => p.id));
+  for (const [id] of controller.active) {
+    if (nextIds.has(id))
+      continue;
+    debug("posting close for", id);
+    window.parent.postMessage({ type: "close", id }, getAdminOrigin());
+    controller.acknowledged.delete(id);
+  }
+  for (const payload of next) {
+    controller.store.seed(payload.id, payload.data ?? {});
+  }
+  controller.active = new Map(next.map((p) => [p.id, p]));
+  controller.primaryId = primaryId && nextIds.has(primaryId) ? primaryId : null;
+  if (next.some((p) => !controller.acknowledged.has(p.id))) {
+    startAnnounceLoop();
+  }
+  reportQuickEdit();
+}
+function readPayloads() {
+  const elements = document.querySelectorAll(FORM_SELECTOR);
+  const payloads = [];
+  let primaryId = null;
+  for (const el of elements) {
+    const raw = el.getAttribute(FORM_ATTR);
+    if (!raw)
+      continue;
+    try {
+      const payload = JSON.parse(raw);
+      if (!payload.id || !payload.query)
+        continue;
+      payloads.push(payload);
+      if (primaryId === null && el.hasAttribute(PRIMARY_FORM_ATTR)) {
+        primaryId = payload.id;
+      }
+    } catch (error) {
+      debug("failed to parse form payload", error);
+    }
+  }
+  debug("discovered", payloads.length, "form(s)");
+  return { payloads, primaryId };
+}
+function onAck(event) {
+  if (!isFromAdmin(event))
+    return;
+  const msg = event.data;
+  if (!msg || typeof msg !== "object")
+    return;
+  if (msg.type !== "updateData" || typeof msg.id !== "string")
+    return;
+  if (!controller)
+    return;
+  if (!controller.acknowledged.has(msg.id)) {
+    debug("admin acked form", msg.id);
+    controller.acknowledged.add(msg.id);
+  }
+}
+function onBeforeUnload() {
+  if (!controller)
+    return;
+  for (const [id] of controller.active) {
+    window.parent.postMessage({ type: "close", id }, getAdminOrigin());
+  }
+}
+function startAnnounceLoop() {
+  if (!controller)
+    return;
+  if (controller.retryTimer) {
+    clearTimeout(controller.retryTimer);
+    controller.retryTimer = null;
+  }
+  controller.attempts = 0;
+  announce();
+}
+function announce() {
+  if (!controller)
+    return;
+  controller.attempts++;
+  const pending = [];
+  for (const [id, payload] of controller.active) {
+    if (!controller.acknowledged.has(id))
+      pending.push(payload);
+  }
+  if (pending.length === 0) {
+    debug("all forms acked after", controller.attempts, "attempt(s)");
+    controller.retryTimer = null;
+    return;
+  }
+  if (controller.attempts > MAX_ATTEMPTS) {
+    debug(
+      "giving up after",
+      MAX_ATTEMPTS,
+      "attempts; pending ids:",
+      pending.map((p) => p.id)
+    );
+    controller.retryTimer = null;
+    return;
+  }
+  for (const payload of pending) {
+    debug("posting open for", payload.id, "attempt", controller.attempts);
+    window.parent.postMessage(
+      {
+        type: "open",
+        id: payload.id,
+        query: payload.query,
+        variables: payload.variables,
+        data: payload.data
+      },
+      getAdminOrigin()
+    );
+  }
+  if (controller.primaryId && pending.some((p) => p.id === controller.primaryId)) {
+    window.parent.postMessage(
+      { type: "user-select-form", formId: controller.primaryId },
+      getAdminOrigin()
+    );
+  }
+  controller.retryTimer = setTimeout(announce, RETRY_INTERVAL_MS);
+}
+function reportQuickEdit() {
+  const hasMarkers = !!document.querySelector("[data-tina-field]");
+  window.parent.postMessage(
+    { type: "quick-edit", value: hasMarkers },
+    getAdminOrigin()
+  );
+}
+const PREVIEW_CONTENT_TYPE = "application/x-tina-preview+json";
+const PRIME_HEADER = "X-Tina-Prime";
+const ISLAND_SELECTOR = "[data-tina-island]";
+const ENDPOINT_ATTR = "data-tina-island";
+const PRIMARY_ISLAND_ATTR = "data-tina-island-primary";
+const PRIMED_FORM_ATTR = "data-tina-primed";
+function initIslandRefresh(store, options) {
+  let pendingRefresh = null;
+  const refreshAll = () => {
+    const islands = document.querySelectorAll(ISLAND_SELECTOR);
+    for (const island of islands) {
+      void refreshIsland(island, store);
+    }
+  };
+  store.subscribe(({ firstUpdate }) => {
+    if (pendingRefresh) {
+      clearTimeout(pendingRefresh);
+      pendingRefresh = null;
+    }
+    if (firstUpdate) {
+      refreshAll();
+      return;
+    }
+    pendingRefresh = setTimeout(() => {
+      pendingRefresh = null;
+      refreshAll();
+    }, options.debounceMs);
+  });
+  window.addEventListener("message", (event) => {
+    if (!isFromAdmin(event))
+      return;
+    const message = event.data;
+    if (!message || typeof message !== "object")
+      return;
+    if (message.type === "updateData" && typeof message.id === "string") {
+      if (!store.has(message.id)) {
+        debug("updateData for unknown id", message.id, "— ignoring");
+        return;
+      }
+      debug("updateData received for", message.id);
+      store.set(message.id, message.data ?? {});
+    }
+  });
+}
+async function refreshIsland(island, store) {
+  const endpoint = island.getAttribute(ENDPOINT_ATTR);
+  if (!endpoint)
+    return;
+  const overlay = {};
+  for (const id of store.ids()) {
+    const data = store.get(id);
+    if (data)
+      overlay[id] = data;
+  }
+  try {
+    debug("refreshing island", endpoint);
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": PREVIEW_CONTENT_TYPE },
+      body: JSON.stringify(overlay),
+      cache: "no-store",
+      credentials: "same-origin"
+    });
+    if (!response.ok) {
+      debug("island refetch failed", endpoint, response.status);
+      return;
+    }
+    if (!isHtmlResponse(response)) {
+      debug("island refetch wrong content-type", endpoint);
+      return;
+    }
+    const html = await response.text();
+    swapIslandHtml(island, html);
+    reportQuickEdit();
+  } catch (error) {
+    debug("island refetch error", endpoint, error);
+  }
+}
+async function primeIslands() {
+  const islands = document.querySelectorAll(ISLAND_SELECTOR);
+  const results = await Promise.all(Array.from(islands, primeIsland));
+  for (const formEl of results.flat()) {
+    formEl.setAttribute(PRIMED_FORM_ATTR, "");
+    document.body.appendChild(formEl);
+  }
+}
+async function primeIsland(island) {
+  const endpoint = island.getAttribute(ENDPOINT_ATTR);
+  if (!endpoint)
+    return [];
+  const isPrimary = island.hasAttribute(PRIMARY_ISLAND_ATTR);
+  try {
+    debug("priming island", endpoint);
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": PREVIEW_CONTENT_TYPE,
+        [PRIME_HEADER]: "1"
+      },
+      body: "{}",
+      cache: "no-store",
+      credentials: "same-origin"
+    });
+    if (!response.ok) {
+      debug("island prime failed", endpoint, response.status);
+      return [];
+    }
+    if (!isHtmlResponse(response)) {
+      debug("island prime wrong content-type", endpoint);
+      return [];
+    }
+    const template = document.createElement("template");
+    template.innerHTML = (await response.text()).trim();
+    const formEls = Array.from(
+      template.content.querySelectorAll(FORM_SELECTOR)
+    );
+    if (isPrimary && formEls[0]) {
+      formEls[0].setAttribute(PRIMARY_FORM_ATTR, "");
+    }
+    return formEls;
+  } catch (error) {
+    debug("island prime error", endpoint, error);
+    return [];
+  }
+}
+function isHtmlResponse(response) {
+  const contentType = response.headers.get("content-type") ?? "";
+  return contentType.includes("text/html");
+}
+function isAllowedSwapAttribute(name) {
+  if (name === "class" || name === "id")
+    return true;
+  return name.startsWith("data-tina-");
+}
+function swapIslandHtml(island, html) {
+  const template = document.createElement("template");
+  template.innerHTML = html.trim();
+  const replacement = template.content.firstElementChild;
+  if (replacement) {
+    for (const attr of Array.from(island.attributes)) {
+      if (attr.name === ENDPOINT_ATTR)
+        continue;
+      island.removeAttribute(attr.name);
+    }
+    for (const attr of Array.from(replacement.attributes)) {
+      if (!isAllowedSwapAttribute(attr.name))
+        continue;
+      island.setAttribute(attr.name, attr.value);
+    }
+    island.innerHTML = replacement.innerHTML;
+  } else {
+    island.innerHTML = html;
+  }
+}
+const tinaField = (object, property, index) => {
+  const contentSource = object == null ? void 0 : object._content_source;
+  if (!contentSource) {
+    return "";
+  }
+  const { queryId, path } = contentSource;
+  if (!property) {
+    return `${queryId}---${path.join(".")}`;
+  }
+  const fullPath = typeof index === "number" ? [...path, property, index] : [...path, property];
+  return `${queryId}---${fullPath.join(".")}`;
+};
+let running = false;
+function init(options = {}) {
+  if (running)
+    return;
+  if (typeof window === "undefined" || window.parent === window) {
+    debug("not in an iframe; bridge is a no-op");
+    return;
+  }
+  debug("initialising in iframe");
+  const { debounceMs = 300, adminOrigin = window.location.origin } = options;
+  setAdminOrigin(adminOrigin);
+  const store = initDataStore();
+  initIslandRefresh(store, { debounceMs });
+  initClickToFocus();
+  initForms(store);
+  running = true;
+  refreshForms();
+}
+let primingInFlight = null;
+let reprimePending = false;
+function refreshForms() {
+  if (!running) {
+    debug("refreshForms called before init() finished; ignoring");
+    return;
+  }
+  removePrimedForms();
+  const hasServerForms = document.querySelector("[data-tina-form]");
+  if (!hasServerForms && document.querySelector("[data-tina-island]")) {
+    if (primingInFlight) {
+      reprimePending = true;
+      return;
+    }
+    debug("no server-injected forms; priming from island endpoints");
+    primingInFlight = primeIslands().finally(() => {
+      primingInFlight = null;
+    });
+    void primingInFlight.then(() => {
+      if (reprimePending) {
+        reprimePending = false;
+        refreshForms();
+        return;
+      }
+      refreshForms$1();
+    });
+    return;
+  }
+  refreshForms$1();
+}
+function removePrimedForms() {
+  for (const el of document.querySelectorAll(`[${PRIMED_FORM_ATTR}]`)) {
+    el.remove();
+  }
+}
+export {
+  init,
+  refreshForms,
+  tinaField
+};

package/dist/island-refresh.d.ts

@@ -0,0 +1,22 @@
+import type { DataStore } from './types';
+/**
+ * Listen for admin `updateData` events and re-fetch every island on the
+ * page with the unsaved data POSTed as a JSON body. POST (vs header)
+ * avoids the ~8KB Latin-1 cap. Refetches collapse into one debounced
+ * pass (every refresh re-renders every island).
+ */
+export interface IslandRefreshOptions {
+    debounceMs: number;
+}
+/** Marks a `[data-tina-form]` div that a prime pass appended (vs. one the
+ *  server injected), so a later re-scan can drop it before re-priming. */
+export declare const PRIMED_FORM_ATTR = "data-tina-primed";
+export declare function initIslandRefresh(store: DataStore, options: IslandRefreshOptions): void;
+/**
+ * Hydrate `[data-tina-form]` payloads for prerendered pages by hitting
+ * each island endpoint with the prime header set; the endpoint prepends
+ * payloads to the region HTML. The caller follows up with refreshForms()
+ * to announce them. Region HTML isn't swapped — canonical data is
+ * already on the page; the first real `updateData` handles updates.
+ */
+export declare function primeIslands(): Promise<void>;

package/dist/island-refresh.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/metadata.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Canonical content-source metadata helpers.
+ *
+ * `addMetadata` walks a query result and stamps every non-system object with
+ * `_content_source: { queryId, path }`. The pair is what `tinaField()` reads
+ * to build the `data-tina-field` markers the admin uses for click-to-focus.
+ *
+ * `hashFromQuery` derives the queryId from `JSON.stringify({ query, variables })`.
+ * Both ends of the wire (page render, admin sidebar) hash the same string so
+ * overlay updates address the same form.
+ *
+ * One source of truth for React (useTina), Astro (server-side overlay), and
+ * any future framework integration. Kept dependency-free so it runs in any
+ * runtime — browser, Node, edge.
+ */
+export declare const addMetadata: <T>(id: string, obj: T, path?: (string | number)[]) => T;
+/**
+ * Rudimentary string hash. Both ends of the wire derive the queryId from
+ * the same JSON.stringify({ query, variables }) — collisions are theoretically
+ * possible but vanishingly rare in practice.
+ */
+export declare const hashFromQuery: (input: string) => string;

package/dist/metadata.js

@@ -0,0 +1,66 @@
+const SYSTEM_KEYS = /* @__PURE__ */ new Set([
+  "__typename",
+  "_sys",
+  "_internalSys",
+  "_values",
+  "_internalValues",
+  "_content_source",
+  "_tina_metadata"
+]);
+const addMetadata = (id, obj, path = []) => {
+  if (obj === null)
+    return obj;
+  if (isScalarOrUndefined(obj))
+    return obj;
+  if (obj instanceof String)
+    return obj.valueOf();
+  if (Array.isArray(obj)) {
+    return obj.map(
+      (item, index) => addMetadata(id, item, [...path, index])
+    );
+  }
+  const next = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (SYSTEM_KEYS.has(key)) {
+      next[key] = value;
+    } else {
+      next[key] = addMetadata(id, value, [...path, key]);
+    }
+  }
+  if (next && typeof next === "object" && "type" in next && next.type === "root") {
+    return next;
+  }
+  return { ...next, _content_source: { queryId: id, path } };
+};
+function isScalarOrUndefined(value) {
+  const type = typeof value;
+  if (type === "string")
+    return true;
+  if (type === "number")
+    return true;
+  if (type === "boolean")
+    return true;
+  if (type === "undefined")
+    return true;
+  if (value == null)
+    return true;
+  if (value instanceof String)
+    return true;
+  if (value instanceof Number)
+    return true;
+  if (value instanceof Boolean)
+    return true;
+  return false;
+}
+const hashFromQuery = (input) => {
+  let hash = 0;
+  for (let i = 0; i < input.length; i++) {
+    const char = input.charCodeAt(i);
+    hash = (hash << 5) - hash + char & 4294967295;
+  }
+  return Math.abs(hash).toString(36);
+};
+export {
+  addMetadata,
+  hashFromQuery
+};

package/dist/preview.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Server-side helpers for the X-Tina-Preview channel. The bridge POSTs
+ * island refetches with body `{ [queryId]: data, ... }`; handlers read
+ * their slice via `readOverlay(request, queryId)`.
+ */
+export declare const PREVIEW_HEADER = "X-Tina-Preview";
+export declare const PREVIEW_CONTENT_TYPE = "application/x-tina-preview+json";
+/** Set on the one-time prime refetch for prerendered pages; the endpoint
+ *  prepends `<div data-tina-form>` payloads to the region HTML. */
+export declare const PRIME_HEADER = "X-Tina-Prime";
+export interface PreviewEnvelope {
+    [queryId: string]: unknown;
+}
+export declare function readOverlay<T>(request: Request, queryId: string): Promise<T | undefined>;
+/** Read and parse the full overlay envelope (every form on the page). */
+export declare function readEnvelope(request: Request): Promise<PreviewEnvelope | undefined>;

package/dist/preview.js

@@ -0,0 +1,45 @@
+const PREVIEW_HEADER = "X-Tina-Preview";
+const PREVIEW_CONTENT_TYPE = "application/x-tina-preview+json";
+const PRIME_HEADER = "X-Tina-Prime";
+const MAX_ENVELOPE_BYTES = 1e6;
+async function readOverlay(request, queryId) {
+  const envelope = await readEnvelope(request);
+  if (!envelope)
+    return void 0;
+  const value = envelope[queryId];
+  return value === void 0 ? void 0 : value;
+}
+const envelopeCache = /* @__PURE__ */ new WeakMap();
+function readEnvelope(request) {
+  let cached = envelopeCache.get(request);
+  if (!cached) {
+    cached = parseEnvelope(request);
+    envelopeCache.set(request, cached);
+  }
+  return cached;
+}
+async function parseEnvelope(request) {
+  const contentType = request.headers.get("content-type") ?? "";
+  if (!contentType.includes(PREVIEW_CONTENT_TYPE))
+    return void 0;
+  const declaredLength = Number(request.headers.get("content-length") ?? "0");
+  if (declaredLength > MAX_ENVELOPE_BYTES)
+    return void 0;
+  try {
+    const text = await request.text();
+    if (!text)
+      return void 0;
+    if (text.length > MAX_ENVELOPE_BYTES)
+      return void 0;
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+export {
+  PREVIEW_CONTENT_TYPE,
+  PREVIEW_HEADER,
+  PRIME_HEADER,
+  readEnvelope,
+  readOverlay
+};

package/dist/preview.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/quick-edit-css.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared CSS for the quick-edit outline. Used by both the vanilla bridge
+ * (click-to-focus.ts) and the React `useTina` hook (packages/tinacms/src/react.tsx),
+ * so the visible affordance is identical regardless of which integration
+ * the consumer is running.
+ */
+export declare const QUICK_EDIT_CSS = "\n  [data-tina-field] {\n    outline: 2px dashed rgba(34,150,254,0.5);\n    transition: box-shadow ease-out 150ms;\n  }\n  [data-tina-field]:hover {\n    box-shadow: inset 100vi 100vh rgba(34,150,254,0.3);\n    outline: 2px solid rgba(34,150,254,1);\n    cursor: pointer;\n  }\n  [data-tina-field-overlay] {\n    outline: 2px dashed rgba(34,150,254,0.5);\n    position: relative;\n  }\n  [data-tina-field-overlay]:hover {\n    cursor: pointer;\n    outline: 2px solid rgba(34,150,254,1);\n  }\n  [data-tina-field-overlay]::after {\n    content: '';\n    position: absolute;\n    inset: 0;\n    z-index: 20;\n    transition: opacity ease-out 150ms;\n    background-color: rgba(34,150,254,0.3);\n    opacity: 0;\n  }\n  [data-tina-field-overlay]:hover::after {\n    opacity: 1;\n  }\n";
+export declare const QUICK_EDIT_BODY_CLASS = "__tina-quick-editing-enabled";
+export declare const QUICK_EDIT_STYLE_ID = "__tina-bridge-quick-edit-style";

package/dist/quick-edit-css.js

@@ -0,0 +1,38 @@
+const QUICK_EDIT_CSS = `
+  [data-tina-field] {
+    outline: 2px dashed rgba(34,150,254,0.5);
+    transition: box-shadow ease-out 150ms;
+  }
+  [data-tina-field]:hover {
+    box-shadow: inset 100vi 100vh rgba(34,150,254,0.3);
+    outline: 2px solid rgba(34,150,254,1);
+    cursor: pointer;
+  }
+  [data-tina-field-overlay] {
+    outline: 2px dashed rgba(34,150,254,0.5);
+    position: relative;
+  }
+  [data-tina-field-overlay]:hover {
+    cursor: pointer;
+    outline: 2px solid rgba(34,150,254,1);
+  }
+  [data-tina-field-overlay]::after {
+    content: '';
+    position: absolute;
+    inset: 0;
+    z-index: 20;
+    transition: opacity ease-out 150ms;
+    background-color: rgba(34,150,254,0.3);
+    opacity: 0;
+  }
+  [data-tina-field-overlay]:hover::after {
+    opacity: 1;
+  }
+`;
+const QUICK_EDIT_BODY_CLASS = "__tina-quick-editing-enabled";
+const QUICK_EDIT_STYLE_ID = "__tina-bridge-quick-edit-style";
+export {
+  QUICK_EDIT_BODY_CLASS,
+  QUICK_EDIT_CSS,
+  QUICK_EDIT_STYLE_ID
+};

package/dist/refresh-forms.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tina-field.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Generate a field identifier for Tina to associate DOM elements with form fields.
+ * Format: "queryId---path.to.field" or "queryId---path.to.array.index"
+ *
+ * Canonical implementation. The React-side `tinacms/tina-field` and Astro-side
+ * `@tinacms/astro/tina-field` both re-export from here so non-React frontends
+ * can consume it without pulling tinacms (and its React deps) into their bundle.
+ */
+export declare const tinaField: <T extends {
+    _content_source?: {
+        queryId: string;
+        path: (number | string)[];
+    };
+} | Record<string, unknown> | null | undefined>(object: T, property?: keyof Omit<NonNullable<T>, "__typename" | "_sys">, index?: number) => string;

package/dist/tina-field.js

@@ -0,0 +1,15 @@
+const tinaField = (object, property, index) => {
+  const contentSource = object == null ? void 0 : object._content_source;
+  if (!contentSource) {
+    return "";
+  }
+  const { queryId, path } = contentSource;
+  if (!property) {
+    return `${queryId}---${path.join(".")}`;
+  }
+  const fullPath = typeof index === "number" ? [...path, property, index] : [...path, property];
+  return `${queryId}---${fullPath.join(".")}`;
+};
+export {
+  tinaField
+};

package/dist/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * postMessage protocol shared between this bridge and the TinaCMS admin
+ * (packages/@tinacms/app). Mirrors the messages emitted by useTina in
+ * packages/tinacms/src/react.tsx so the admin sees identical traffic.
+ */
+export type BridgeOutgoing = {
+    type: 'isEditMode';
+} | {
+    type: 'open';
+    id: string;
+    query: string;
+    variables: object;
+    data: object;
+} | {
+    type: 'close';
+    id: string;
+} | {
+    type: 'url-changed';
+} | {
+    type: 'field:selected';
+    fieldName: string;
+} | {
+    type: 'quick-edit';
+    value: boolean;
+} | {
+    type: 'user-select-form';
+    formId: string;
+};
+export type BridgeIncoming = {
+    type: 'tina:editMode';
+} | {
+    type: 'updateData';
+    id: string;
+    data: object;
+} | {
+    type: 'quickEditEnabled';
+    value: boolean;
+};
+export interface FormPayload {
+    id: string;
+    query: string;
+    variables: object;
+    data: object;
+}
+export interface DataStore {
+    /** Latest resolved data per form id. */
+    get(id: string): object | undefined;
+    /** Whether a form id has been seeded or set. */
+    has(id: string): boolean;
+    /** Populate without notifying subscribers (used for the initial seed). */
+    seed(id: string, data: object): void;
+    /** Replace cached data for a form and notify subscribers. */
+    set(id: string, data: object): void;
+    /** All known form ids. */
+    ids(): string[];
+    /** Subscribe to data updates. Returns unsubscribe. */
+    subscribe(listener: (event: {
+        id: string;
+        firstUpdate: boolean;
+    }) => void): () => void;
+}

package/dist/types.test-d.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@tinacms/bridge",
+  "version": "0.0.0-0509095-20260525122024",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "package.json",
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./tina-field": {
+      "types": "./dist/tina-field.d.ts",
+      "default": "./dist/tina-field.js"
+    },
+    "./preview": {
+      "types": "./dist/preview.d.ts",
+      "default": "./dist/preview.js"
+    },
+    "./metadata": {
+      "types": "./dist/metadata.d.ts",
+      "default": "./dist/metadata.js"
+    },
+    "./quick-edit-css": {
+      "types": "./dist/quick-edit-css.d.ts",
+      "default": "./dist/quick-edit-css.js"
+    }
+  },
+  "license": "Apache-2.0",
+  "buildConfig": {
+    "entryPoints": [
+      "src/index.ts",
+      "src/tina-field.ts",
+      "src/preview.ts",
+      "src/metadata.ts",
+      "src/quick-edit-css.ts"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.1",
+    "happy-dom": "15.10.2",
+    "typescript": "^5.7.3",
+    "vite": "^5.4.14",
+    "vitest": "^2.1.9",
+    "@tinacms/scripts": "1.6.1"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "url": "https://github.com/tinacms/tinacms.git",
+    "directory": "packages/@tinacms/bridge"
+  },
+  "scripts": {
+    "types": "tsc",
+    "build": "tinacms-scripts build",
+    "test": "vitest run",
+    "test-watch": "vitest"
+  }
+}