@gallerist/plugin-hash 0.0.0-stage → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shafayet Ahmmed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# @gallerist/plugin-hash
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Gallerist plugin — deep-link the cursor to the URL hash (#g=&i=), with back/forward.
+
+Part of [Gallerist](https://github.com/shafayet9780/gallerist#readme) — a headless, framework-agnostic media viewer for grouped / nested galleries with image-space overlays and virtualized rendering.
+
+## Install
+
+```bash
+npm i @gallerist/plugin-hash
+```
+
+## Usage
+
+Tree-shakeable Gallerist plugin. Register it when you create the viewer:
+
+```ts
+import { createViewer } from '@gallerist/core'
+// import the plugin's factory from this package and pass it to `plugins`
+const viewer = createViewer({ items, plugins: [/* plugin() */] })
+```
+
+See [Plugin authoring](https://github.com/shafayet9780/gallerist/blob/main/docs/PLUGIN-AUTHORING.md).
+
+Full docs: the [monorepo README](https://github.com/shafayet9780/gallerist#readme) and [`docs/`](https://github.com/shafayet9780/gallerist/tree/main/docs).
+
+## License
+
+MIT © Shafayet Ahmmed

package/dist/index.cjs

@@ -0,0 +1,83 @@
+'use strict';
+
+// src/index.ts
+function parseHash(hash2) {
+  const out = {};
+  const raw = hash2.replace(/^#/, "");
+  const dec = (s) => {
+    try {
+      return decodeURIComponent(s);
+    } catch {
+      return s;
+    }
+  };
+  for (const part of raw.split("&")) {
+    const eq = part.indexOf("=");
+    if (eq < 0) continue;
+    const k = part.slice(0, eq);
+    const v = part.slice(eq + 1);
+    if (!v) continue;
+    if (k === "g") out.g = dec(v);
+    else if (k === "i") out.i = dec(v);
+  }
+  return out;
+}
+function formatHash(groupId, itemId) {
+  const g = `g=${encodeURIComponent(groupId)}`;
+  return itemId !== void 0 ? `${g}&i=${encodeURIComponent(itemId)}` : g;
+}
+function hash(opts = {}) {
+  return (viewer) => {
+    if (typeof window === "undefined") return { name: "hash" };
+    let lastWritten = null;
+    const offs = [];
+    const applyFromHash = () => {
+      const { g, i } = parseHash(window.location.hash);
+      if (!g) return false;
+      viewer.goToId(g, i);
+      return true;
+    };
+    const writeHash = () => {
+      const col = viewer.getCollection();
+      const cur = viewer.getState().cursor;
+      const group = col.groups[cur.g];
+      if (!group) return;
+      const item = group.items[cur.i];
+      lastWritten = formatHash(group.id, item?.id);
+      try {
+        window.history.replaceState(window.history.state, "", `#${lastWritten}`);
+      } catch {
+        window.location.hash = lastWritten;
+      }
+    };
+    const onHashChange = () => {
+      if (window.location.hash.replace(/^#/, "") === lastWritten) return;
+      applyFromHash();
+    };
+    return {
+      name: "hash",
+      init() {
+        window.addEventListener("hashchange", onHashChange);
+        offs.push(
+          viewer.on("slide", writeHash),
+          viewer.on("item", writeHash),
+          viewer.on("opened", writeHash)
+        );
+        if (parseHash(window.location.hash).g) {
+          applyFromHash();
+          if (opts.open !== false) viewer.open();
+        }
+      },
+      destroy() {
+        window.removeEventListener("hashchange", onHashChange);
+        for (const off of offs) off();
+      }
+    };
+  };
+}
+
+exports.formatHash = formatHash;
+exports.hash = hash;
+exports.parseHash = parseHash;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["hash"],"mappings":";;;AAWO,SAAS,UAAUA,KAAAA,EAA0C;AAClE,EAAA,MAAM,MAAkC,EAAC;AACzC,EAAA,MAAM,GAAA,GAAMA,KAAAA,CAAK,OAAA,CAAQ,IAAA,EAAM,EAAE,CAAA;AAGjC,EAAA,MAAM,GAAA,GAAM,CAAC,CAAA,KAAc;AACzB,IAAA,IAAI;AACF,MAAA,OAAO,mBAAmB,CAAC,CAAA;AAAA,IAC7B,CAAA,CAAA,MAAQ;AACN,MAAA,OAAO,CAAA;AAAA,IACT;AAAA,EACF,CAAA;AACA,EAAA,KAAA,MAAW,IAAA,IAAQ,GAAA,CAAI,KAAA,CAAM,GAAG,CAAA,EAAG;AAEjC,IAAA,MAAM,EAAA,GAAK,IAAA,CAAK,OAAA,CAAQ,GAAG,CAAA;AAC3B,IAAA,IAAI,KAAK,CAAA,EAAG;AACZ,IAAA,MAAM,CAAA,GAAI,IAAA,CAAK,KAAA,CAAM,CAAA,EAAG,EAAE,CAAA;AAC1B,IAAA,MAAM,CAAA,GAAI,IAAA,CAAK,KAAA,CAAM,EAAA,GAAK,CAAC,CAAA;AAC3B,IAAA,IAAI,CAAC,CAAA,EAAG;AACR,IAAA,IAAI,CAAA,KAAM,GAAA,EAAK,GAAA,CAAI,CAAA,GAAI,IAAI,CAAC,CAAA;AAAA,SAAA,IACnB,CAAA,KAAM,GAAA,EAAK,GAAA,CAAI,CAAA,GAAI,IAAI,CAAC,CAAA;AAAA,EACnC;AACA,EAAA,OAAO,GAAA;AACT;AAGO,SAAS,UAAA,CAAW,SAAiB,MAAA,EAAyB;AACnE,EAAA,MAAM,CAAA,GAAI,CAAA,EAAA,EAAK,kBAAA,CAAmB,OAAO,CAAC,CAAA,CAAA;AAC1C,EAAA,OAAO,MAAA,KAAW,SAAY,CAAA,EAAG,CAAC,MAAM,kBAAA,CAAmB,MAAM,CAAC,CAAA,CAAA,GAAK,CAAA;AACzE;AAEO,SAAS,IAAA,CAAK,IAAA,GAAoB,EAAC,EAAW;AACnD,EAAA,OAAO,CAAC,MAAA,KAAW;AACjB,IAAA,IAAI,OAAO,MAAA,KAAW,WAAA,EAAa,OAAO,EAAE,MAAM,MAAA,EAAO;AAKzD,IAAA,IAAI,WAAA,GAA6B,IAAA;AACjC,IAAA,MAAM,OAAuB,EAAC;AAE9B,IAAA,MAAM,gBAAgB,MAAe;AACnC,MAAA,MAAM,EAAE,CAAA,EAAG,CAAA,KAAM,SAAA,CAAU,MAAA,CAAO,SAAS,IAAI,CAAA;AAC/C,MAAA,IAAI,CAAC,GAAG,OAAO,KAAA;AACf,MAAA,MAAA,CAAO,MAAA,CAAO,GAAG,CAAC,CAAA;AAClB,MAAA,OAAO,IAAA;AAAA,IACT,CAAA;AAEA,IAAA,MAAM,YAAY,MAAM;AACtB,MAAA,MAAM,GAAA,GAAM,OAAO,aAAA,EAAc;AACjC,MAAA,MAAM,GAAA,GAAM,MAAA,CAAO,QAAA,EAAS,CAAE,MAAA;AAC9B,MAAA,MAAM,KAAA,GAAQ,GAAA,CAAI,MAAA,CAAO,GAAA,CAAI,CAAC,CAAA;AAC9B,MAAA,IAAI,CAAC,KAAA,EAAO;AACZ,MAAA,MAAM,IAAA,GAAO,KAAA,CAAM,KAAA,CAAM,GAAA,CAAI,CAAC,CAAA;AAC9B,MAAA,WAAA,GAAc,UAAA,CAAW,KAAA,CAAM,EAAA,EAAI,IAAA,EAAM,EAAE,CAAA;AAI3C,MAAA,IAAI;AACF,QAAA,MAAA,CAAO,OAAA,CAAQ,aAAa,MAAA,CAAO,OAAA,CAAQ,OAAO,EAAA,EAAI,CAAA,CAAA,EAAI,WAAW,CAAA,CAAE,CAAA;AAAA,MACzE,CAAA,CAAA,MAAQ;AACN,QAAA,MAAA,CAAO,SAAS,IAAA,GAAO,WAAA;AAAA,MACzB;AAAA,IACF,CAAA;AAEA,IAAA,MAAM,eAAe,MAAM;AACzB,MAAA,IAAI,OAAO,QAAA,CAAS,IAAA,CAAK,QAAQ,IAAA,EAAM,EAAE,MAAM,WAAA,EAAa;AAC5D,MAAA,aAAA,EAAc;AAAA,IAChB,CAAA;AAEA,IAAA,OAAO;AAAA,MACL,IAAA,EAAM,MAAA;AAAA,MACN,IAAA,GAAO;AACL,QAAA,MAAA,CAAO,gBAAA,CAAiB,cAAc,YAAY,CAAA;AAClD,QAAA,IAAA,CAAK,IAAA;AAAA,UACH,MAAA,CAAO,EAAA,CAAG,OAAA,EAAS,SAAS,CAAA;AAAA,UAC5B,MAAA,CAAO,EAAA,CAAG,MAAA,EAAQ,SAAS,CAAA;AAAA,UAC3B,MAAA,CAAO,EAAA,CAAG,QAAA,EAAU,SAAS;AAAA,SAC/B;AACA,QAAA,IAAI,SAAA,CAAU,MAAA,CAAO,QAAA,CAAS,IAAI,EAAE,CAAA,EAAG;AACrC,UAAA,aAAA,EAAc;AACd,UAAA,IAAI,IAAA,CAAK,IAAA,KAAS,KAAA,EAAO,MAAA,CAAO,IAAA,EAAK;AAAA,QACvC;AAAA,MACF,CAAA;AAAA,MACA,OAAA,GAAU;AACR,QAAA,MAAA,CAAO,mBAAA,CAAoB,cAAc,YAAY,CAAA;AACrD,QAAA,KAAA,MAAW,GAAA,IAAO,MAAM,GAAA,EAAI;AAAA,MAC9B;AAAA,KACF;AAAA,EACF,CAAA;AACF","file":"index.cjs","sourcesContent":["// @gallerist/plugin-hash — deep-link the cursor to the URL hash `#g=<groupId>&i=<itemId>` (spec §14, §16).\n// Client-only (SSR-guarded); reflects nav into the URL and applies the URL on load + back/forward.\n\nimport type { Plugin } from '@gallerist/core'\n\nexport interface HashOptions {\n  /** open the viewer on load if a hash is present (default true). */\n  open?: boolean\n}\n\n/** Parse a location.hash like \"#g=mon-2&i=s3\" → { g, i } (values URL-decoded). */\nexport function parseHash(hash: string): { g?: string; i?: string } {\n  const out: { g?: string; i?: string } = {}\n  const raw = hash.replace(/^#/, '')\n  // The hash is untrusted (any user can edit the address bar): tolerate a malformed percent\n  // escape instead of throwing URIError (I-PL1).\n  const dec = (s: string) => {\n    try {\n      return decodeURIComponent(s)\n    } catch {\n      return s\n    }\n  }\n  for (const part of raw.split('&')) {\n    // Split on the FIRST '=' only so ids may legitimately contain '=' (e.g. base64 padding) (I-PL2).\n    const eq = part.indexOf('=')\n    if (eq < 0) continue\n    const k = part.slice(0, eq)\n    const v = part.slice(eq + 1)\n    if (!v) continue\n    if (k === 'g') out.g = dec(v)\n    else if (k === 'i') out.i = dec(v)\n  }\n  return out\n}\n\n/** Format a group/item id pair into a hash body \"g=<id>&i=<id>\" (no leading #). */\nexport function formatHash(groupId: string, itemId?: string): string {\n  const g = `g=${encodeURIComponent(groupId)}`\n  return itemId !== undefined ? `${g}&i=${encodeURIComponent(itemId)}` : g\n}\n\nexport function hash(opts: HashOptions = {}): Plugin {\n  return (viewer) => {\n    if (typeof window === 'undefined') return { name: 'hash' } // SSR no-op\n\n    // Track the last value we wrote and ignore matching hashchange events. Robust to the browser\n    // coalescing / firing hashchange asynchronously (a boolean latch can get stuck and then swallow\n    // a genuine back/forward); comparing the value can't (review T9).\n    let lastWritten: string | null = null\n    const offs: (() => void)[] = []\n\n    const applyFromHash = (): boolean => {\n      const { g, i } = parseHash(window.location.hash)\n      if (!g) return false\n      viewer.goToId(g, i)\n      return true\n    }\n\n    const writeHash = () => {\n      const col = viewer.getCollection()\n      const cur = viewer.getState().cursor\n      const group = col.groups[cur.g]\n      if (!group) return\n      const item = group.items[cur.i]\n      lastWritten = formatHash(group.id, item?.id)\n      // Replace, don't push: assigning location.hash stacks a new history entry on every nav,\n      // trapping the Back button (press Back N times to leave). replaceState keeps the URL\n      // shareable without polluting history (I-PL3). Falls back where history is restricted.\n      try {\n        window.history.replaceState(window.history.state, '', `#${lastWritten}`)\n      } catch {\n        window.location.hash = lastWritten\n      }\n    }\n\n    const onHashChange = () => {\n      if (window.location.hash.replace(/^#/, '') === lastWritten) return // our own write\n      applyFromHash()\n    }\n\n    return {\n      name: 'hash',\n      init() {\n        window.addEventListener('hashchange', onHashChange)\n        offs.push(\n          viewer.on('slide', writeHash),\n          viewer.on('item', writeHash),\n          viewer.on('opened', writeHash),\n        )\n        if (parseHash(window.location.hash).g) {\n          applyFromHash()\n          if (opts.open !== false) viewer.open()\n        }\n      },\n      destroy() {\n        window.removeEventListener('hashchange', onHashChange)\n        for (const off of offs) off()\n      },\n    }\n  }\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,16 @@
+import { Plugin } from '@gallerist/core';
+
+interface HashOptions {
+    /** open the viewer on load if a hash is present (default true). */
+    open?: boolean;
+}
+/** Parse a location.hash like "#g=mon-2&i=s3" → { g, i } (values URL-decoded). */
+declare function parseHash(hash: string): {
+    g?: string;
+    i?: string;
+};
+/** Format a group/item id pair into a hash body "g=<id>&i=<id>" (no leading #). */
+declare function formatHash(groupId: string, itemId?: string): string;
+declare function hash(opts?: HashOptions): Plugin;
+
+export { type HashOptions, formatHash, hash, parseHash };

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import { Plugin } from '@gallerist/core';
+
+interface HashOptions {
+    /** open the viewer on load if a hash is present (default true). */
+    open?: boolean;
+}
+/** Parse a location.hash like "#g=mon-2&i=s3" → { g, i } (values URL-decoded). */
+declare function parseHash(hash: string): {
+    g?: string;
+    i?: string;
+};
+/** Format a group/item id pair into a hash body "g=<id>&i=<id>" (no leading #). */
+declare function formatHash(groupId: string, itemId?: string): string;
+declare function hash(opts?: HashOptions): Plugin;
+
+export { type HashOptions, formatHash, hash, parseHash };

package/dist/index.js

@@ -0,0 +1,79 @@
+// src/index.ts
+function parseHash(hash2) {
+  const out = {};
+  const raw = hash2.replace(/^#/, "");
+  const dec = (s) => {
+    try {
+      return decodeURIComponent(s);
+    } catch {
+      return s;
+    }
+  };
+  for (const part of raw.split("&")) {
+    const eq = part.indexOf("=");
+    if (eq < 0) continue;
+    const k = part.slice(0, eq);
+    const v = part.slice(eq + 1);
+    if (!v) continue;
+    if (k === "g") out.g = dec(v);
+    else if (k === "i") out.i = dec(v);
+  }
+  return out;
+}
+function formatHash(groupId, itemId) {
+  const g = `g=${encodeURIComponent(groupId)}`;
+  return itemId !== void 0 ? `${g}&i=${encodeURIComponent(itemId)}` : g;
+}
+function hash(opts = {}) {
+  return (viewer) => {
+    if (typeof window === "undefined") return { name: "hash" };
+    let lastWritten = null;
+    const offs = [];
+    const applyFromHash = () => {
+      const { g, i } = parseHash(window.location.hash);
+      if (!g) return false;
+      viewer.goToId(g, i);
+      return true;
+    };
+    const writeHash = () => {
+      const col = viewer.getCollection();
+      const cur = viewer.getState().cursor;
+      const group = col.groups[cur.g];
+      if (!group) return;
+      const item = group.items[cur.i];
+      lastWritten = formatHash(group.id, item?.id);
+      try {
+        window.history.replaceState(window.history.state, "", `#${lastWritten}`);
+      } catch {
+        window.location.hash = lastWritten;
+      }
+    };
+    const onHashChange = () => {
+      if (window.location.hash.replace(/^#/, "") === lastWritten) return;
+      applyFromHash();
+    };
+    return {
+      name: "hash",
+      init() {
+        window.addEventListener("hashchange", onHashChange);
+        offs.push(
+          viewer.on("slide", writeHash),
+          viewer.on("item", writeHash),
+          viewer.on("opened", writeHash)
+        );
+        if (parseHash(window.location.hash).g) {
+          applyFromHash();
+          if (opts.open !== false) viewer.open();
+        }
+      },
+      destroy() {
+        window.removeEventListener("hashchange", onHashChange);
+        for (const off of offs) off();
+      }
+    };
+  };
+}
+
+export { formatHash, hash, parseHash };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["hash"],"mappings":";AAWO,SAAS,UAAUA,KAAAA,EAA0C;AAClE,EAAA,MAAM,MAAkC,EAAC;AACzC,EAAA,MAAM,GAAA,GAAMA,KAAAA,CAAK,OAAA,CAAQ,IAAA,EAAM,EAAE,CAAA;AAGjC,EAAA,MAAM,GAAA,GAAM,CAAC,CAAA,KAAc;AACzB,IAAA,IAAI;AACF,MAAA,OAAO,mBAAmB,CAAC,CAAA;AAAA,IAC7B,CAAA,CAAA,MAAQ;AACN,MAAA,OAAO,CAAA;AAAA,IACT;AAAA,EACF,CAAA;AACA,EAAA,KAAA,MAAW,IAAA,IAAQ,GAAA,CAAI,KAAA,CAAM,GAAG,CAAA,EAAG;AAEjC,IAAA,MAAM,EAAA,GAAK,IAAA,CAAK,OAAA,CAAQ,GAAG,CAAA;AAC3B,IAAA,IAAI,KAAK,CAAA,EAAG;AACZ,IAAA,MAAM,CAAA,GAAI,IAAA,CAAK,KAAA,CAAM,CAAA,EAAG,EAAE,CAAA;AAC1B,IAAA,MAAM,CAAA,GAAI,IAAA,CAAK,KAAA,CAAM,EAAA,GAAK,CAAC,CAAA;AAC3B,IAAA,IAAI,CAAC,CAAA,EAAG;AACR,IAAA,IAAI,CAAA,KAAM,GAAA,EAAK,GAAA,CAAI,CAAA,GAAI,IAAI,CAAC,CAAA;AAAA,SAAA,IACnB,CAAA,KAAM,GAAA,EAAK,GAAA,CAAI,CAAA,GAAI,IAAI,CAAC,CAAA;AAAA,EACnC;AACA,EAAA,OAAO,GAAA;AACT;AAGO,SAAS,UAAA,CAAW,SAAiB,MAAA,EAAyB;AACnE,EAAA,MAAM,CAAA,GAAI,CAAA,EAAA,EAAK,kBAAA,CAAmB,OAAO,CAAC,CAAA,CAAA;AAC1C,EAAA,OAAO,MAAA,KAAW,SAAY,CAAA,EAAG,CAAC,MAAM,kBAAA,CAAmB,MAAM,CAAC,CAAA,CAAA,GAAK,CAAA;AACzE;AAEO,SAAS,IAAA,CAAK,IAAA,GAAoB,EAAC,EAAW;AACnD,EAAA,OAAO,CAAC,MAAA,KAAW;AACjB,IAAA,IAAI,OAAO,MAAA,KAAW,WAAA,EAAa,OAAO,EAAE,MAAM,MAAA,EAAO;AAKzD,IAAA,IAAI,WAAA,GAA6B,IAAA;AACjC,IAAA,MAAM,OAAuB,EAAC;AAE9B,IAAA,MAAM,gBAAgB,MAAe;AACnC,MAAA,MAAM,EAAE,CAAA,EAAG,CAAA,KAAM,SAAA,CAAU,MAAA,CAAO,SAAS,IAAI,CAAA;AAC/C,MAAA,IAAI,CAAC,GAAG,OAAO,KAAA;AACf,MAAA,MAAA,CAAO,MAAA,CAAO,GAAG,CAAC,CAAA;AAClB,MAAA,OAAO,IAAA;AAAA,IACT,CAAA;AAEA,IAAA,MAAM,YAAY,MAAM;AACtB,MAAA,MAAM,GAAA,GAAM,OAAO,aAAA,EAAc;AACjC,MAAA,MAAM,GAAA,GAAM,MAAA,CAAO,QAAA,EAAS,CAAE,MAAA;AAC9B,MAAA,MAAM,KAAA,GAAQ,GAAA,CAAI,MAAA,CAAO,GAAA,CAAI,CAAC,CAAA;AAC9B,MAAA,IAAI,CAAC,KAAA,EAAO;AACZ,MAAA,MAAM,IAAA,GAAO,KAAA,CAAM,KAAA,CAAM,GAAA,CAAI,CAAC,CAAA;AAC9B,MAAA,WAAA,GAAc,UAAA,CAAW,KAAA,CAAM,EAAA,EAAI,IAAA,EAAM,EAAE,CAAA;AAI3C,MAAA,IAAI;AACF,QAAA,MAAA,CAAO,OAAA,CAAQ,aAAa,MAAA,CAAO,OAAA,CAAQ,OAAO,EAAA,EAAI,CAAA,CAAA,EAAI,WAAW,CAAA,CAAE,CAAA;AAAA,MACzE,CAAA,CAAA,MAAQ;AACN,QAAA,MAAA,CAAO,SAAS,IAAA,GAAO,WAAA;AAAA,MACzB;AAAA,IACF,CAAA;AAEA,IAAA,MAAM,eAAe,MAAM;AACzB,MAAA,IAAI,OAAO,QAAA,CAAS,IAAA,CAAK,QAAQ,IAAA,EAAM,EAAE,MAAM,WAAA,EAAa;AAC5D,MAAA,aAAA,EAAc;AAAA,IAChB,CAAA;AAEA,IAAA,OAAO;AAAA,MACL,IAAA,EAAM,MAAA;AAAA,MACN,IAAA,GAAO;AACL,QAAA,MAAA,CAAO,gBAAA,CAAiB,cAAc,YAAY,CAAA;AAClD,QAAA,IAAA,CAAK,IAAA;AAAA,UACH,MAAA,CAAO,EAAA,CAAG,OAAA,EAAS,SAAS,CAAA;AAAA,UAC5B,MAAA,CAAO,EAAA,CAAG,MAAA,EAAQ,SAAS,CAAA;AAAA,UAC3B,MAAA,CAAO,EAAA,CAAG,QAAA,EAAU,SAAS;AAAA,SAC/B;AACA,QAAA,IAAI,SAAA,CAAU,MAAA,CAAO,QAAA,CAAS,IAAI,EAAE,CAAA,EAAG;AACrC,UAAA,aAAA,EAAc;AACd,UAAA,IAAI,IAAA,CAAK,IAAA,KAAS,KAAA,EAAO,MAAA,CAAO,IAAA,EAAK;AAAA,QACvC;AAAA,MACF,CAAA;AAAA,MACA,OAAA,GAAU;AACR,QAAA,MAAA,CAAO,mBAAA,CAAoB,cAAc,YAAY,CAAA;AACrD,QAAA,KAAA,MAAW,GAAA,IAAO,MAAM,GAAA,EAAI;AAAA,MAC9B;AAAA,KACF;AAAA,EACF,CAAA;AACF","file":"index.js","sourcesContent":["// @gallerist/plugin-hash — deep-link the cursor to the URL hash `#g=<groupId>&i=<itemId>` (spec §14, §16).\n// Client-only (SSR-guarded); reflects nav into the URL and applies the URL on load + back/forward.\n\nimport type { Plugin } from '@gallerist/core'\n\nexport interface HashOptions {\n  /** open the viewer on load if a hash is present (default true). */\n  open?: boolean\n}\n\n/** Parse a location.hash like \"#g=mon-2&i=s3\" → { g, i } (values URL-decoded). */\nexport function parseHash(hash: string): { g?: string; i?: string } {\n  const out: { g?: string; i?: string } = {}\n  const raw = hash.replace(/^#/, '')\n  // The hash is untrusted (any user can edit the address bar): tolerate a malformed percent\n  // escape instead of throwing URIError (I-PL1).\n  const dec = (s: string) => {\n    try {\n      return decodeURIComponent(s)\n    } catch {\n      return s\n    }\n  }\n  for (const part of raw.split('&')) {\n    // Split on the FIRST '=' only so ids may legitimately contain '=' (e.g. base64 padding) (I-PL2).\n    const eq = part.indexOf('=')\n    if (eq < 0) continue\n    const k = part.slice(0, eq)\n    const v = part.slice(eq + 1)\n    if (!v) continue\n    if (k === 'g') out.g = dec(v)\n    else if (k === 'i') out.i = dec(v)\n  }\n  return out\n}\n\n/** Format a group/item id pair into a hash body \"g=<id>&i=<id>\" (no leading #). */\nexport function formatHash(groupId: string, itemId?: string): string {\n  const g = `g=${encodeURIComponent(groupId)}`\n  return itemId !== undefined ? `${g}&i=${encodeURIComponent(itemId)}` : g\n}\n\nexport function hash(opts: HashOptions = {}): Plugin {\n  return (viewer) => {\n    if (typeof window === 'undefined') return { name: 'hash' } // SSR no-op\n\n    // Track the last value we wrote and ignore matching hashchange events. Robust to the browser\n    // coalescing / firing hashchange asynchronously (a boolean latch can get stuck and then swallow\n    // a genuine back/forward); comparing the value can't (review T9).\n    let lastWritten: string | null = null\n    const offs: (() => void)[] = []\n\n    const applyFromHash = (): boolean => {\n      const { g, i } = parseHash(window.location.hash)\n      if (!g) return false\n      viewer.goToId(g, i)\n      return true\n    }\n\n    const writeHash = () => {\n      const col = viewer.getCollection()\n      const cur = viewer.getState().cursor\n      const group = col.groups[cur.g]\n      if (!group) return\n      const item = group.items[cur.i]\n      lastWritten = formatHash(group.id, item?.id)\n      // Replace, don't push: assigning location.hash stacks a new history entry on every nav,\n      // trapping the Back button (press Back N times to leave). replaceState keeps the URL\n      // shareable without polluting history (I-PL3). Falls back where history is restricted.\n      try {\n        window.history.replaceState(window.history.state, '', `#${lastWritten}`)\n      } catch {\n        window.location.hash = lastWritten\n      }\n    }\n\n    const onHashChange = () => {\n      if (window.location.hash.replace(/^#/, '') === lastWritten) return // our own write\n      applyFromHash()\n    }\n\n    return {\n      name: 'hash',\n      init() {\n        window.addEventListener('hashchange', onHashChange)\n        offs.push(\n          viewer.on('slide', writeHash),\n          viewer.on('item', writeHash),\n          viewer.on('opened', writeHash),\n        )\n        if (parseHash(window.location.hash).g) {\n          applyFromHash()\n          if (opts.open !== false) viewer.open()\n        }\n      },\n      destroy() {\n        window.removeEventListener('hashchange', onHashChange)\n        for (const off of offs) off()\n      },\n    }\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@gallerist/plugin-hash",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.1",
+  "description": "Gallerist plugin — deep-link the cursor to the URL hash (#g=&i=), with back/forward.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "peerDependencies": {
+    "@gallerist/core": ">=0.3.0 <1"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "@gallerist/core": "0.3.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shafayet9780/gallerist.git",
+    "directory": "packages/plugin-hash"
+  },
+  "homepage": "https://github.com/shafayet9780/gallerist#readme",
+  "bugs": {
+    "url": "https://github.com/shafayet9780/gallerist/issues"
+  },
+  "author": "Shafayet Ahmmed",
+  "keywords": [
+    "lightbox",
+    "gallery",
+    "image-viewer",
+    "media-viewer",
+    "photo-gallery",
+    "carousel",
+    "zoom",
+    "pan",
+    "overlays",
+    "headless",
+    "framework-agnostic",
+    "virtualized",
+    "nested-gallery"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
 }