@excom/provider-storage 0.1.0

package/support/package-meta.json

@@ -0,0 +1,99 @@
+{
+  "shortName": "provider-storage",
+  "package": {
+    "name": "@excom/provider-storage",
+    "version": "0.1.0",
+    "description": "<provider-storage> custom element",
+    "peerDependencies": {},
+    "excom": {
+      "packageType": "kit-element"
+    }
+  },
+  "demos": {
+    "simple": "<div>\n  <event-handler role=\"button\" fire-event=\"demo-seed-storage\">\n    Seed localStorage &amp; re-read\n  </event-handler>\n  <provider-storage></provider-storage>\n  <output>Not read yet — click above.</output>\n  <small role=\"note\">Same-tab writes only show up after\n    <code>key-name</code> is re-set; a write from another tab is picked up\n    live.</small>\n  <quark-sheet>\n    @use \"/demo-utils\" as *;\n\n    :scope {\n      @on demo-seed-storage (handle: seedDemoStorage);\n      @on neutron-provision (handle: setOutputFromElementData);\n    }\n  </quark-sheet>\n</div>\n"
+  },
+  "readme": "<h1 id=\"md-provider-storage\">provider-storage</h1>\n<p>Read a JSON value out of <code>localStorage</code> / <code>sessionStorage</code> into <code>provision</code>,\ndeclaratively — and keep it in sync across tabs. No app JS required to display\ncached client state.</p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Declarative read</strong> Point <code>key-name</code> at a storage key and read the result</li>\n<li><strong>Local or session</strong> <code>store-name</code> picks <code>localStorage</code> (default) /\n<code>sessionStorage</code></li>\n<li><strong>Live across tabs</strong> A write from another tab re-reads and fires\n<code>provider-storage-changed</code></li>\n<li><strong>Reactive to attributes</strong> Changing <code>key-name</code> / <code>store-name</code> re-reads\nimmediately</li>\n<li><strong>Tiny, read-only</strong> Never writes</li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<include-content data-language=\"html\"><template>&lt;provider-storage key-name=\"user-preferences\"&gt;&lt;/provider-storage&gt;\n&lt;provider-storage key-name=\"checkout-draft\" store-name=\"session\"&gt;&lt;/provider-storage&gt;</template></include-content>\n<p><strong>Read-only.</strong> It reads on every <code>key-name</code> / <code>store-name</code> set/change and never\nwrites. Removing <code>key-name</code> clears <code>provision</code> and both states.</p>\n<p><strong>Live across tabs, not within one.</strong> Browsers fire <code>storage</code> only in <em>other</em>\ntabs, so:</p>\n<ul>\n<li>A write from another tab (or a <code>clear()</code> there) re-reads and fires\n<code>provider-storage-changed</code> — no app code needed. <code>sessionStorage</code> is\nper-tab, so this only applies to <code>store-name=&quot;local&quot;</code>.</li>\n<li>A write by your own app code (<code>localStorage.setItem(...)</code>) in the same tab\nwon&#39;t appear until you re-trigger a read — re-set <code>key-name</code> (e.g. to <code>&quot;&quot;</code>\nand back) after writing.</li>\n</ul>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-seed-amp-re-read\">Seed &amp; re-read</h4>\n<p>Since this element never writes, the demo below seeds a value from a button\n(re-setting <code>key-name</code> afterward to force the same-tab re-read) so you can see\nit work without opening devtools. Open this page in a second tab and click\nthere too — this tab updates on its own.</p>\n<p><include-content data-demo=\"simple\"></include-content></p>\n",
+  "docs": {
+    "readme": "<h1 id=\"md-provider-storage\">provider-storage</h1>\n<p>Read a JSON value out of <code>localStorage</code> / <code>sessionStorage</code> into <code>provision</code>,\ndeclaratively — and keep it in sync across tabs. No app JS required to display\ncached client state.</p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Declarative read</strong> Point <code>key-name</code> at a storage key and read the result</li>\n<li><strong>Local or session</strong> <code>store-name</code> picks <code>localStorage</code> (default) /\n<code>sessionStorage</code></li>\n<li><strong>Live across tabs</strong> A write from another tab re-reads and fires\n<code>provider-storage-changed</code></li>\n<li><strong>Reactive to attributes</strong> Changing <code>key-name</code> / <code>store-name</code> re-reads\nimmediately</li>\n<li><strong>Tiny, read-only</strong> Never writes</li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<include-content data-language=\"html\"><template>&lt;provider-storage key-name=\"user-preferences\"&gt;&lt;/provider-storage&gt;\n&lt;provider-storage key-name=\"checkout-draft\" store-name=\"session\"&gt;&lt;/provider-storage&gt;</template></include-content>\n<p><strong>Read-only.</strong> It reads on every <code>key-name</code> / <code>store-name</code> set/change and never\nwrites. Removing <code>key-name</code> clears <code>provision</code> and both states.</p>\n<p><strong>Live across tabs, not within one.</strong> Browsers fire <code>storage</code> only in <em>other</em>\ntabs, so:</p>\n<ul>\n<li>A write from another tab (or a <code>clear()</code> there) re-reads and fires\n<code>provider-storage-changed</code> — no app code needed. <code>sessionStorage</code> is\nper-tab, so this only applies to <code>store-name=&quot;local&quot;</code>.</li>\n<li>A write by your own app code (<code>localStorage.setItem(...)</code>) in the same tab\nwon&#39;t appear until you re-trigger a read — re-set <code>key-name</code> (e.g. to <code>&quot;&quot;</code>\nand back) after writing.</li>\n</ul>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-seed-amp-re-read\">Seed &amp; re-read</h4>\n<p>Since this element never writes, the demo below seeds a value from a button\n(re-setting <code>key-name</code> afterward to force the same-tab re-read) so you can see\nit work without opening devtools. Open this page in a second tab and click\nthere too — this tab updates on its own.</p>\n<p><include-content data-demo=\"simple\"></include-content></p>\n"
+  },
+  "installation": {
+    "name": "@excom/provider-storage",
+    "shortName": "provider-storage",
+    "version": "0.1.0",
+    "description": "<provider-storage> custom element",
+    "packageType": "kit-element",
+    "cdn": "<script src=\"https://unpkg.com/@excom/kit-utils/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/neutron/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/provider-storage@0.1.0/dist/index.umd.min.js\"></script>",
+    "install": {
+      "npm": "npm install @excom/provider-storage"
+    },
+    "imports": {
+      "js": "import \"@excom/provider-storage\";",
+      "html": "<!-- import path to `node_modules` will depend on your build setup -->\n<script type=\"module\" src=\"/node_modules/@excom/provider-storage\"></script>\n<link rel=\"stylesheet\" href=\"/node_modules/@excom/provider-storage\">"
+    },
+    "peerDependencies": []
+  },
+  "elementApis": [
+    {
+      "tag": "provider-storage",
+      "kind": "class",
+      "attributes": [
+        {
+          "name": "key-name",
+          "type": "string",
+          "description": "Storage key to read. Setting or changing it re-reads immediately (parsed as JSON; <code>null</code> if absent). Removing it clears <code>provision</code> and both states.",
+          "fieldName": "keyName",
+          "surface": "option",
+          "values": "<storage key>"
+        },
+        {
+          "name": "store-name",
+          "type": "string",
+          "description": "Which Web Storage area to read. <code>local</code> survives the tab / browser closing and syncs across tabs; <code>session</code> is per-tab and gone when the tab closes. Changing it re-reads <code>key-name</code> from the new store.",
+          "fieldName": "storeName",
+          "surface": "option",
+          "default": "\"local\"",
+          "values": "local, session"
+        },
+        {
+          "name": "is-error",
+          "type": "boolean",
+          "description": "<code>JSON.parse</code> threw on the last read (the stored value isn&#39;t valid JSON). <code>provision</code> is <code>null</code>.",
+          "fieldName": "isError",
+          "surface": "state"
+        },
+        {
+          "name": "is-success",
+          "type": "boolean",
+          "description": "The last read (parse) succeeded — including a legitimately absent key (<code>provision</code> is <code>null</code>, not an error).",
+          "fieldName": "isSuccess",
+          "surface": "state"
+        }
+      ],
+      "events": [
+        {
+          "name": "provider-storage-changed",
+          "description": "Dispatched after a <code>storage</code> event from another tab for this element&#39;s <code>store-name</code> + <code>key-name</code> (or a <code>clear()</code> of that store) has been re-read into <code>provision</code> — so <code>provision</code>, <code>is-success</code> / <code>is-error</code> are already updated when it fires. The read also publishes <code>neutron-provision</code>, as usual.",
+          "type": "ProviderStorageChangedEvent",
+          "typeExpanded": "CustomEvent & { type: \"provider-storage-changed\"; detail: { keyName: string; oldValue: unknown; newValue: unknown; }; bubbles: true; cancelable: true; composed: true }"
+        }
+      ],
+      "slots": [],
+      "cssProperties": [],
+      "cssClasses": [],
+      "cssAliases": [],
+      "listens": [],
+      "commands": [],
+      "defaultActions": [],
+      "expectedChildren": [],
+      "provisions": [
+        {
+          "name": "provision",
+          "type": "object",
+          "description": "<code>JSON.parse(store.getItem(keyName))</code>, or <code>null</code> if the key is absent or the read failed. Not reflected as an attribute.",
+          "fieldName": "provision"
+        }
+      ]
+    }
+  ],
+  "exportedFiles": {}
+}

package/support/tests/__snapshots__/simple.view.test.ts.snap

@@ -0,0 +1,23 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`simple view > seeds storage and prints the provision > complexity 1`] = `
+{
+  "attributeRuns": 0,
+  "closest": 0,
+  "getVar": 0,
+  "importNode": 0,
+  "listenerRuns": 0,
+  "matches": 0,
+  "parentElement": 0,
+  "quarkRuns": 0,
+  "queryScopeCost": 0,
+  "querySelectorAll": 0,
+  "removeAttribute": 0,
+  "ruleRuns": 0,
+  "schedulePaint": 0,
+  "setAttribute": 3,
+  "setVar": 0,
+  "textContent": 1,
+  "variableRuns": 0,
+}
+`;

package/support/tests/provider-storage.test.ts

@@ -0,0 +1,520 @@
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  fixture,
+  it,
+  vi,
+  waitForEvent,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import "../../index";
+import type { ProviderStorageChangedEvent } from "../../index";
+
+const mount = (attrs = "") =>
+  fixture<HTMLProviderStorageElement>(
+    `<provider-storage ${attrs}></provider-storage>`,
+  );
+
+/** Simulate another tab writing `key` in `storageArea`. */
+const otherTabWrites = (
+  key: string | null,
+  newValue: unknown,
+  storageArea: Storage = localStorage,
+) => {
+  const oldValue = key === null ? null : storageArea.getItem(key);
+  if (key === null) {
+    storageArea.clear();
+  } else if (newValue === null) {
+    storageArea.removeItem(key);
+  } else {
+    storageArea.setItem(key, JSON.stringify(newValue));
+  }
+  window.dispatchEvent(
+    new StorageEvent("storage", {
+      key,
+      oldValue,
+      newValue: key === null || newValue === null ? null : JSON.stringify(newValue),
+      storageArea,
+    }),
+  );
+};
+
+const flushDisconnect = () => new Promise<void>((r) => queueMicrotask(r));
+
+describe("provider-storage", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+    localStorage.clear();
+    sessionStorage.clear();
+  });
+
+  it("reads data from localStorage", () => {
+    const store = new Map<string, string>();
+    vi.stubGlobal("localStorage", {
+      getItem: (key: string) => store.get(key) ?? null,
+      setItem: (key: string, value: string) => store.set(key, value),
+    });
+    store.set("test-key", JSON.stringify({ ok: true }));
+
+    const el = mount();
+    el.setAttribute("key-name", "test-key");
+
+    expect(el).dom.to.equalTag(
+      `<provider-storage is-success key-name="test-key"></provider-storage>`,
+    );
+    expect(el.provision).toEqual({ ok: true });
+  });
+
+  describe("reading", () => {
+    beforeEach(() => {
+      localStorage.setItem("prefs", JSON.stringify({ theme: "dark" }));
+      localStorage.setItem("count", "42");
+      localStorage.setItem(
+        "nested",
+        JSON.stringify({ a: { b: [1, 2, { c: "d" }] } }),
+      );
+    });
+
+    it("does nothing until key-name is set", () => {
+      const el = mount();
+      expect(el).dom.to.equalTag(`<provider-storage></provider-storage>`);
+      expect(el.provision).toBe(null);
+      expect(el.isSuccess).toBeFalsy();
+      expect(el.isError).toBeFalsy();
+    });
+
+    it("reads on connect when key-name is present in the markup", () => {
+      const el = mount(`key-name="prefs"`);
+      expect(el).dom.to.equalTag(
+        `<provider-storage is-success key-name="prefs"></provider-storage>`,
+      );
+      expect(el.provision).toEqual({ theme: "dark" });
+    });
+
+    it("parses primitives and nested structures", () => {
+      const el = mount(`key-name="count"`);
+      expect(el.provision).toBe(42);
+
+      el.keyName = "nested";
+      expect(el.provision).toEqual({ a: { b: [1, 2, { c: "d" }] } });
+    });
+
+    it("reads null for a missing key and still reports success", () => {
+      const el = mount(`key-name="does-not-exist"`);
+      expect(el).dom.to.equalTag(
+        `<provider-storage is-success key-name="does-not-exist"></provider-storage>`,
+      );
+      expect(el.provision).toBe(null);
+      expect(el.isError).toBe(false);
+    });
+
+    it("re-reads when key-name changes", () => {
+      const el = mount(`key-name="prefs"`);
+      expect(el.provision).toEqual({ theme: "dark" });
+
+      el.setAttribute("key-name", "count");
+      expect(el.provision).toBe(42);
+
+      el.keyName = "prefs";
+      expect(el.provision).toEqual({ theme: "dark" });
+    });
+
+    it("re-reads the current value when key-name is toggled off and on", () => {
+      const el = mount(`key-name="prefs"`);
+      expect(el.provision).toEqual({ theme: "dark" });
+
+      // a same-tab write is not picked up on its own…
+      localStorage.setItem("prefs", JSON.stringify({ theme: "light" }));
+      expect(el.provision).toEqual({ theme: "dark" });
+
+      // …until key-name is re-set (the documented workaround)
+      el.keyName = "";
+      el.keyName = "prefs";
+      expect(el.provision).toEqual({ theme: "light" });
+    });
+
+    it("clears provision and both states when key-name is removed", () => {
+      const el = mount(`key-name="prefs"`);
+      expect(el.provision).toEqual({ theme: "dark" });
+
+      el.removeAttribute("key-name");
+
+      expect(el).dom.to.equalTag(`<provider-storage></provider-storage>`);
+      expect(el.provision).toBe(null);
+      expect(el.isSuccess).toBe(false);
+      expect(el.isError).toBe(false);
+    });
+
+    it("clears is-error too when key-name is removed", () => {
+      vi.spyOn(console, "error").mockImplementation(() => {});
+      localStorage.setItem("broken", "{not json");
+      const el = mount(`key-name="broken"`);
+      expect(el.isError).toBe(true);
+
+      el.keyName = null as unknown as string;
+
+      expect(el).dom.to.equalTag(`<provider-storage></provider-storage>`);
+      expect(el.isError).toBe(false);
+    });
+
+    it("never writes to either store", () => {
+      const setSpy = vi.spyOn(Storage.prototype, "setItem");
+      const removeSpy = vi.spyOn(Storage.prototype, "removeItem");
+      const clearSpy = vi.spyOn(Storage.prototype, "clear");
+
+      const el = mount(`key-name="prefs"`);
+      el.keyName = "count";
+      el.storeName = "session";
+      el.removeAttribute("key-name");
+      el.remove();
+
+      expect(setSpy).not.toHaveBeenCalled();
+      expect(removeSpy).not.toHaveBeenCalled();
+      expect(clearSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("store-name", () => {
+    beforeEach(() => {
+      localStorage.setItem("prefs", JSON.stringify({ from: "local" }));
+      sessionStorage.setItem("prefs", JSON.stringify({ from: "session" }));
+    });
+
+    it("defaults to localStorage", () => {
+      const el = mount(`key-name="prefs"`);
+      expect(el.provision).toEqual({ from: "local" });
+      expect(el.storeName).toBeFalsy();
+    });
+
+    it("reads sessionStorage with store-name=\"session\"", () => {
+      const el = mount(`key-name="prefs" store-name="session"`);
+      expect(el).dom.to.equalTag(
+        `<provider-storage is-success key-name="prefs" store-name="session"></provider-storage>`,
+      );
+      expect(el.provision).toEqual({ from: "session" });
+    });
+
+    it("treats an explicit store-name=\"local\" as localStorage", () => {
+      const el = mount(`key-name="prefs" store-name="local"`);
+      expect(el.provision).toEqual({ from: "local" });
+    });
+
+    it("re-reads from the other store when store-name changes", () => {
+      const el = mount(`key-name="prefs"`);
+      expect(el.provision).toEqual({ from: "local" });
+
+      el.setAttribute("store-name", "session");
+      expect(el.provision).toEqual({ from: "session" });
+
+      el.storeName = "local";
+      expect(el.provision).toEqual({ from: "local" });
+    });
+
+    it("falls back to localStorage when store-name is removed", () => {
+      const el = mount(`key-name="prefs" store-name="session"`);
+      expect(el.provision).toEqual({ from: "session" });
+
+      el.removeAttribute("store-name");
+      expect(el.provision).toEqual({ from: "local" });
+      expect(el.isSuccess).toBe(true);
+    });
+
+    it("does not read when store-name is set without key-name", () => {
+      const el = mount(`store-name="session"`);
+      const spy = vi.fn();
+      el.addEventListener("neutron-provision", spy);
+
+      el.storeName = "local";
+
+      expect(spy).not.toHaveBeenCalled();
+      expect(el.isSuccess).toBeFalsy();
+      expect(el.provision).toBe(null);
+    });
+
+    it("reads a missing session key as null", () => {
+      const el = mount(`key-name="nope" store-name="session"`);
+      expect(el.provision).toBe(null);
+      expect(el.isSuccess).toBe(true);
+    });
+  });
+
+  describe("errors", () => {
+    it("sets is-error when the stored value is not valid JSON", () => {
+      const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+      localStorage.setItem("broken", "{not json");
+
+      const el = mount(`key-name="broken"`);
+
+      expect(el).dom.to.equalTag(
+        `<provider-storage is-error key-name="broken"></provider-storage>`,
+      );
+      expect(el.isSuccess).toBe(false);
+      expect(el.provision).toBe(null);
+      expect(errorSpy).toHaveBeenCalledTimes(1);
+      expect(errorSpy.mock.calls[0].join(" ")).toMatch(/provider-storage/);
+    });
+
+    it("nulls the provision when a later read fails", () => {
+      vi.spyOn(console, "error").mockImplementation(() => {});
+      localStorage.setItem("good", JSON.stringify(["a"]));
+      localStorage.setItem("bad", "undefined");
+
+      const el = mount(`key-name="good"`);
+      expect(el.provision).toEqual(["a"]);
+
+      el.keyName = "bad";
+      expect(el.isError).toBe(true);
+      expect(el.isSuccess).toBe(false);
+      expect(el.provision).toBe(null);
+    });
+
+    it("recovers from an error when key-name moves to a valid key", () => {
+      vi.spyOn(console, "error").mockImplementation(() => {});
+      localStorage.setItem("bad", "<html>");
+      localStorage.setItem("good", "true");
+
+      const el = mount(`key-name="bad"`);
+      expect(el.isError).toBe(true);
+
+      el.keyName = "good";
+      expect(el).dom.to.equalTag(
+        `<provider-storage is-success key-name="good"></provider-storage>`,
+      );
+      expect(el.provision).toBe(true);
+    });
+  });
+
+  describe("provision", () => {
+    it("publishes every read with neutron-provision", async () => {
+      localStorage.setItem("prefs", JSON.stringify({ theme: "dark" }));
+      const el = mount();
+
+      await waitForEvent(el, "neutron-provision", () => {
+        el.setAttribute("key-name", "prefs");
+      });
+      expect(el.provision).toEqual({ theme: "dark" });
+    });
+
+    it("bubbles neutron-provision to ancestors", () => {
+      localStorage.setItem("prefs", "1");
+      const el = mount();
+      const spy = vi.fn();
+      el.parentElement!.addEventListener("neutron-provision", spy);
+
+      el.keyName = "prefs";
+
+      expect(spy).toHaveBeenCalledTimes(1);
+      expect((spy.mock.calls[0][0] as Event).target).toBe(el);
+    });
+  });
+
+  describe("storage events (other tabs)", () => {
+    beforeEach(() => {
+      localStorage.setItem("prefs", JSON.stringify({ theme: "dark" }));
+    });
+
+    it("re-reads and fires provider-storage-changed when another tab writes the key", () => {
+      const el = mount(`key-name="prefs"`);
+      const seenAtChanged: unknown[] = [];
+      const changed = vi.fn(() => seenAtChanged.push(el.provision));
+      const provisioned = vi.fn();
+      el.addEventListener("provider-storage-changed", changed);
+      el.addEventListener("neutron-provision", provisioned);
+
+      otherTabWrites("prefs", { theme: "light" });
+
+      expect(el.provision).toEqual({ theme: "light" });
+      expect(el.isSuccess).toBe(true);
+      expect(changed).toHaveBeenCalledTimes(1);
+      const e = changed.mock.calls[0][0] as ProviderStorageChangedEvent;
+      expect(e.detail).toEqual({
+        keyName: "prefs",
+        oldValue: { theme: "dark" },
+        newValue: { theme: "light" },
+      });
+      // provision + state are already applied when the changed event fires…
+      expect(seenAtChanged).toEqual([{ theme: "light" }]);
+      // …and the read is still published like any other
+      expect(provisioned).toHaveBeenCalledTimes(1);
+    });
+
+    it("bubbles provider-storage-changed to ancestors", () => {
+      const el = mount(`key-name="prefs"`);
+      const spy = vi.fn();
+      el.parentElement!.addEventListener("provider-storage-changed", spy);
+
+      otherTabWrites("prefs", 2);
+
+      expect(spy).toHaveBeenCalledTimes(1);
+      expect((spy.mock.calls[0][0] as Event).target).toBe(el);
+      expect((spy.mock.calls[0][0] as CustomEvent).detail.newValue).toBe(2);
+    });
+
+    it("reports null when another tab removes the key", () => {
+      const el = mount(`key-name="prefs"`);
+      const spy = vi.fn();
+      el.addEventListener("provider-storage-changed", spy);
+
+      otherTabWrites("prefs", null);
+
+      expect(el.provision).toBe(null);
+      expect(el.isSuccess).toBe(true);
+      expect(spy.mock.calls[0][0].detail).toEqual({
+        keyName: "prefs",
+        oldValue: { theme: "dark" },
+        newValue: null,
+      });
+    });
+
+    it("treats a clear() in another tab (key === null) as a change", () => {
+      const el = mount(`key-name="prefs"`);
+      const spy = vi.fn();
+      el.addEventListener("provider-storage-changed", spy);
+
+      otherTabWrites(null, null);
+
+      expect(el.provision).toBe(null);
+      expect(spy).toHaveBeenCalledTimes(1);
+      expect(spy.mock.calls[0][0].detail.newValue).toBe(null);
+    });
+
+    it("ignores writes to other keys", () => {
+      const el = mount(`key-name="prefs"`);
+      const changed = vi.fn();
+      const provisioned = vi.fn();
+      el.addEventListener("provider-storage-changed", changed);
+      el.addEventListener("neutron-provision", provisioned);
+
+      otherTabWrites("other", { x: 1 });
+
+      expect(changed).not.toHaveBeenCalled();
+      expect(provisioned).not.toHaveBeenCalled();
+      expect(el.provision).toEqual({ theme: "dark" });
+    });
+
+    it("ignores writes to the same key in the other store", () => {
+      sessionStorage.setItem("prefs", JSON.stringify({ from: "session" }));
+      const local = mount(`key-name="prefs"`);
+      const session = fixture<HTMLProviderStorageElement>(
+        `<provider-storage key-name="prefs" store-name="session"></provider-storage>`,
+      );
+      const localSpy = vi.fn();
+      const sessionSpy = vi.fn();
+      local.addEventListener("provider-storage-changed", localSpy);
+      session.addEventListener("provider-storage-changed", sessionSpy);
+
+      otherTabWrites("prefs", { from: "session-2" }, sessionStorage);
+
+      expect(localSpy).not.toHaveBeenCalled();
+      expect(local.provision).toEqual({ theme: "dark" });
+      expect(sessionSpy).toHaveBeenCalledTimes(1);
+      expect(session.provision).toEqual({ from: "session-2" });
+
+      otherTabWrites("prefs", { theme: "light" }, localStorage);
+
+      expect(localSpy).toHaveBeenCalledTimes(1);
+      expect(sessionSpy).toHaveBeenCalledTimes(1);
+      expect(local.provision).toEqual({ theme: "light" });
+    });
+
+    it("ignores storage events while key-name is unset", () => {
+      const el = mount();
+      const spy = vi.fn();
+      el.addEventListener("provider-storage-changed", spy);
+
+      otherTabWrites("prefs", { theme: "light" });
+
+      expect(spy).not.toHaveBeenCalled();
+      expect(el.provision).toBe(null);
+    });
+
+    it("sets is-error and a null provision when the other tab wrote invalid JSON", () => {
+      vi.spyOn(console, "error").mockImplementation(() => {});
+      const el = mount(`key-name="prefs"`);
+      const spy = vi.fn();
+      el.addEventListener("provider-storage-changed", spy);
+
+      localStorage.setItem("prefs", "{nope");
+      window.dispatchEvent(
+        new StorageEvent("storage", {
+          key: "prefs",
+          oldValue: JSON.stringify({ theme: "dark" }),
+          newValue: "{nope",
+          storageArea: localStorage,
+        }),
+      );
+
+      expect(el).dom.to.equalTag(
+        `<provider-storage is-error key-name="prefs"></provider-storage>`,
+      );
+      expect(el.provision).toBe(null);
+      expect(spy.mock.calls[0][0].detail).toEqual({
+        keyName: "prefs",
+        oldValue: { theme: "dark" },
+        newValue: null,
+      });
+    });
+
+    it("listens on window once per element while connected", () => {
+      const addSpy = vi.spyOn(window, "addEventListener");
+      mount(`key-name="prefs"`);
+      expect(
+        addSpy.mock.calls.filter(([type]) => type === "storage"),
+      ).toHaveLength(1);
+    });
+
+    it("stops listening once disconnected", async () => {
+      const removeSpy = vi.spyOn(window, "removeEventListener");
+      const el = mount(`key-name="prefs"`);
+      const spy = vi.fn();
+      el.addEventListener("provider-storage-changed", spy);
+
+      el.remove();
+      await flushDisconnect();
+
+      expect(
+        removeSpy.mock.calls.filter(([type]) => type === "storage"),
+      ).toHaveLength(1);
+
+      otherTabWrites("prefs", { theme: "light" });
+      expect(spy).not.toHaveBeenCalled();
+      expect(el.provision).toEqual({ theme: "dark" });
+    });
+
+    it("keeps listening across a synchronous move", async () => {
+      const el = mount(`key-name="prefs"`);
+      const spy = vi.fn();
+      el.addEventListener("provider-storage-changed", spy);
+      const newParent = document.createElement("section");
+      document.body.append(newParent);
+
+      newParent.append(el); // disconnect + connect in the same tick
+      await flushDisconnect();
+
+      otherTabWrites("prefs", { theme: "light" });
+      expect(spy).toHaveBeenCalledTimes(1);
+      expect(el.provision).toEqual({ theme: "light" });
+
+      // and only once, no duplicate listener after the move
+      otherTabWrites("prefs", { theme: "dark" });
+      expect(spy).toHaveBeenCalledTimes(2);
+    });
+
+    it("listens again after a later re-insert", async () => {
+      const el = mount(`key-name="prefs"`);
+      const spy = vi.fn();
+      el.addEventListener("provider-storage-changed", spy);
+
+      el.remove();
+      await flushDisconnect();
+      document.body.append(el);
+
+      otherTabWrites("prefs", { theme: "light" });
+      expect(spy).toHaveBeenCalledTimes(1);
+      expect(el.provision).toEqual({ theme: "light" });
+    });
+  });
+});