@mentra/miniapp 3.2.1-beta.373 → 3.2.1-beta.386

package/dist/react/index.d.ts

@@ -10,6 +10,7 @@ export type { MiniappHeaderProps } from "./MiniappHeader";
 export { MentraProvider } from "./MentraProvider";
 export type { MentraProviderProps } from "./MentraProvider";
 export { useRpc, type RpcCallable } from "./useRpc";
+export { useHistoryState, type SetHistoryState } from "./useHistoryState";
 export { StreamPreview } from "./StreamPreview";
 export type { StreamPreviewProps, StreamPreviewStatus, PreviewFit, PreviewConnectionState } from "./StreamPreview";
 //# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,WAAW,EAAC,MAAM,eAAe,CAAA;AACzC,YAAY,EAAC,iBAAiB,EAAC,MAAM,eAAe,CAAA;AACpD,OAAO,EAAC,cAAc,EAAC,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAC,eAAe,EAAC,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAC,qBAAqB,EAAC,MAAM,yBAAyB,CAAA;AAC7D,YAAY,EAAC,4BAA4B,EAAC,MAAM,yBAAyB,CAAA;AACzE,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAA;AAC7C,YAAY,EAAC,kBAAkB,EAAC,MAAM,iBAAiB,CAAA;AACvD,OAAO,EAAC,cAAc,EAAC,MAAM,kBAAkB,CAAA;AAC/C,YAAY,EAAC,mBAAmB,EAAC,MAAM,kBAAkB,CAAA;AACzD,OAAO,EAAC,MAAM,EAAE,KAAK,WAAW,EAAC,MAAM,UAAU,CAAA;AACjD,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAA;AAC7C,YAAY,EAAC,kBAAkB,EAAE,mBAAmB,EAAE,UAAU,EAAE,sBAAsB,EAAC,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,WAAW,EAAC,MAAM,eAAe,CAAA;AACzC,YAAY,EAAC,iBAAiB,EAAC,MAAM,eAAe,CAAA;AACpD,OAAO,EAAC,cAAc,EAAC,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAC,eAAe,EAAC,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAC,qBAAqB,EAAC,MAAM,yBAAyB,CAAA;AAC7D,YAAY,EAAC,4BAA4B,EAAC,MAAM,yBAAyB,CAAA;AACzE,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAA;AAC7C,YAAY,EAAC,kBAAkB,EAAC,MAAM,iBAAiB,CAAA;AACvD,OAAO,EAAC,cAAc,EAAC,MAAM,kBAAkB,CAAA;AAC/C,YAAY,EAAC,mBAAmB,EAAC,MAAM,kBAAkB,CAAA;AACzD,OAAO,EAAC,MAAM,EAAE,KAAK,WAAW,EAAC,MAAM,UAAU,CAAA;AACjD,OAAO,EAAC,eAAe,EAAE,KAAK,eAAe,EAAC,MAAM,mBAAmB,CAAA;AACvE,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAA;AAC7C,YAAY,EAAC,kBAAkB,EAAE,mBAAmB,EAAE,UAAU,EAAE,sBAAsB,EAAC,MAAM,iBAAiB,CAAA"}

package/dist/react/index.js

@@ -6,5 +6,6 @@ export { useCapsuleHeaderStyle } from "./useCapsuleHeaderStyle";
 export { MiniappHeader } from "./MiniappHeader";
 export { MentraProvider } from "./MentraProvider";
 export { useRpc } from "./useRpc";
+export { useHistoryState } from "./useHistoryState";
 export { StreamPreview } from "./StreamPreview";
 //# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,WAAW,EAAC,MAAM,eAAe,CAAA;AAEzC,OAAO,EAAC,cAAc,EAAC,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAC,eAAe,EAAC,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAC,qBAAqB,EAAC,MAAM,yBAAyB,CAAA;AAE7D,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAA;AAE7C,OAAO,EAAC,cAAc,EAAC,MAAM,kBAAkB,CAAA;AAE/C,OAAO,EAAC,MAAM,EAAmB,MAAM,UAAU,CAAA;AACjD,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,WAAW,EAAC,MAAM,eAAe,CAAA;AAEzC,OAAO,EAAC,cAAc,EAAC,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAAC,eAAe,EAAC,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAC,YAAY,EAAC,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAC,qBAAqB,EAAC,MAAM,yBAAyB,CAAA;AAE7D,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAA;AAE7C,OAAO,EAAC,cAAc,EAAC,MAAM,kBAAkB,CAAA;AAE/C,OAAO,EAAC,MAAM,EAAmB,MAAM,UAAU,CAAA;AACjD,OAAO,EAAC,eAAe,EAAuB,MAAM,mBAAmB,CAAA;AACvE,OAAO,EAAC,aAAa,EAAC,MAAM,iBAAiB,CAAA"}

package/dist/react/useHistoryState.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview useHistoryState — `useState` whose changes are browser history
+ * entries, so the phone's back gesture steps back through them.
+ *
+ * The host sends the back gesture (iOS edge swipe, Android back) to the
+ * miniapp's WebView history first, and minimizes the miniapp only once that
+ * history is empty. Screens, tabs and dialogs kept in plain React state never
+ * create history, so back skips past them and minimizes the whole miniapp.
+ * This hook keeps its value in `history.state` instead:
+ *
+ * - Setting a new value pushes a history entry. Back pops it, and the hook
+ *   re-renders with the previous value.
+ * - Setting the value back to what it was before its latest change(s) goes
+ *   back instead of pushing. Closing a dialog with its own button therefore
+ *   consumes the dialog's entry, and the next back gesture does not reopen it.
+ *
+ * Routers in hash or browser mode (react-router's `HashRouter`, wouter's
+ * `useHashLocation`) already create history for pages; use this hook for UI
+ * state that is not a route. Every hook on the page shares one history entry
+ * per step, and `key` names the value within it, so components passing the
+ * same key share the same value. Values are stored as structured clones.
+ */
+export type SetHistoryState<T> = (value: T | ((previous: T) => T)) => void;
+/**
+ * Like `useState`, but each change is a history entry that the phone's back
+ * gesture undoes. `key` names the value in history state and must be unique
+ * per piece of state on the page.
+ *
+ * ```tsx
+ * const [tab, setTab] = useHistoryState<"home" | "settings">("tab", "home")
+ * const [pickerOpen, setPickerOpen] = useHistoryState("languagePicker", false)
+ * ```
+ */
+export declare function useHistoryState<T>(key: string, initialValue: T): [T, SetHistoryState<T>];
+//# sourceMappingURL=useHistoryState.d.ts.map

package/dist/react/useHistoryState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHistoryState.d.ts","sourceRoot":"","sources":["../../src/react/useHistoryState.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAyFH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,CAAA;AAE1E;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,CAYxF"}

package/dist/react/useHistoryState.js

@@ -0,0 +1,117 @@
+/**
+ * @fileoverview useHistoryState — `useState` whose changes are browser history
+ * entries, so the phone's back gesture steps back through them.
+ *
+ * The host sends the back gesture (iOS edge swipe, Android back) to the
+ * miniapp's WebView history first, and minimizes the miniapp only once that
+ * history is empty. Screens, tabs and dialogs kept in plain React state never
+ * create history, so back skips past them and minimizes the whole miniapp.
+ * This hook keeps its value in `history.state` instead:
+ *
+ * - Setting a new value pushes a history entry. Back pops it, and the hook
+ *   re-renders with the previous value.
+ * - Setting the value back to what it was before its latest change(s) goes
+ *   back instead of pushing. Closing a dialog with its own button therefore
+ *   consumes the dialog's entry, and the next back gesture does not reopen it.
+ *
+ * Routers in hash or browser mode (react-router's `HashRouter`, wouter's
+ * `useHashLocation`) already create history for pages; use this hook for UI
+ * state that is not a route. Every hook on the page shares one history entry
+ * per step, and `key` names the value within it, so components passing the
+ * same key share the same value. Values are stored as structured clones.
+ */
+import { useCallback, useRef, useSyncExternalStore } from "react";
+const STATE_KEY = "__mentraHistoryState";
+const EMPTY = { values: {}, trail: [] };
+let cachedState = null;
+let cachedEntry = EMPTY;
+/** This hook's slice of the current entry, cached so snapshots stay referentially stable. */
+function currentEntry() {
+    if (typeof window === "undefined")
+        return EMPTY;
+    const state = window.history.state;
+    if (state !== cachedState) {
+        cachedState = state;
+        cachedEntry = state?.[STATE_KEY] ?? EMPTY;
+    }
+    return cachedEntry;
+}
+const listeners = new Set();
+let boundWindow = null;
+// history.go() lands later, on popstate. A change applied before then would
+// push on top of the entry being left, and the traversal would pop that push
+// instead, so changes wait in order until the traversal lands.
+let traversing = false;
+const pending = [];
+function notify() {
+    listeners.forEach((listener) => listener());
+}
+function flush() {
+    while (!traversing && pending.length > 0)
+        pending.shift()();
+}
+function onPopState() {
+    traversing = false;
+    notify();
+    // Let every popstate listener, including the host's history bridge, see the
+    // landed entry before a waiting change pushes the next one.
+    setTimeout(flush, 0);
+}
+function subscribe(listener) {
+    if (boundWindow !== window) {
+        boundWindow?.removeEventListener("popstate", onPopState);
+        window.addEventListener("popstate", onPopState);
+        boundWindow = window;
+        traversing = false;
+        pending.length = 0;
+    }
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+function whenSettled(change) {
+    if (traversing || pending.length > 0)
+        pending.push(change);
+    else
+        change();
+}
+function apply(key, initialValue, update) {
+    const { values, trail } = currentEntry();
+    const current = key in values ? values[key] : initialValue;
+    const next = typeof update === "function" ? update(current) : update;
+    if (Object.is(current, next))
+        return;
+    for (let index = trail.length - 1; index >= 0 && trail[index].key === key; index--) {
+        if (Object.is(trail[index].previous, next)) {
+            traversing = true;
+            window.history.go(index - trail.length);
+            return;
+        }
+    }
+    // Keep other fields (a router's index, the host's depth marker) on the new entry.
+    const state = window.history.state;
+    const base = state !== null && typeof state === "object" ? state : {};
+    const entry = { values: { ...values, [key]: next }, trail: [...trail, { key, previous: current }] };
+    window.history.pushState({ ...base, [STATE_KEY]: entry }, "");
+    notify();
+}
+/**
+ * Like `useState`, but each change is a history entry that the phone's back
+ * gesture undoes. `key` names the value in history state and must be unique
+ * per piece of state on the page.
+ *
+ * ```tsx
+ * const [tab, setTab] = useHistoryState<"home" | "settings">("tab", "home")
+ * const [pickerOpen, setPickerOpen] = useHistoryState("languagePicker", false)
+ * ```
+ */
+export function useHistoryState(key, initialValue) {
+    const initialRef = useRef(initialValue);
+    const read = () => {
+        const { values } = currentEntry();
+        return (key in values ? values[key] : initialRef.current);
+    };
+    const value = useSyncExternalStore(subscribe, read, () => initialRef.current);
+    const setValue = useCallback((update) => whenSettled(() => apply(key, initialRef.current, update)), [key]);
+    return [value, setValue];
+}
+//# sourceMappingURL=useHistoryState.js.map

package/dist/react/useHistoryState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHistoryState.js","sourceRoot":"","sources":["../../src/react/useHistoryState.ts"],"names":[],"mappings":"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"}

package/dist/ui/index.d.ts

@@ -69,6 +69,7 @@ export { useConnected } from "../react/useConnected";
 export { useSafeArea } from "../react/useSafeArea";
 export { useCapsuleHeaderStyle } from "../react/useCapsuleHeaderStyle";
 export { useRpc, type RpcCallable } from "../react/useRpc";
+export { useHistoryState, type SetHistoryState } from "../react/useHistoryState";
 export { StreamPreview } from "../react/StreamPreview";
 export type { StreamPreviewProps, StreamPreviewStatus, PreviewFit, PreviewConnectionState } from "../react/StreamPreview";
 /**

package/dist/ui/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAC,MAAM,eAAe,CAAA;AAC3E,YAAY,EAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAE,iBAAiB,EAAC,MAAM,eAAe,CAAA;AACnG,OAAO,EAAC,cAAc,EAAE,qBAAqB,EAAC,MAAM,eAAe,CAAA;AAEnE,MAAM,WAAW,cAAc,CAAC,SAAS,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAChF;;;;OAIG;IACH,IAAI,CAAC,CAAC,SAAS,MAAM,SAAS,GAAG,MAAM,EACrC,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,KAAK,GAAG,CAAC,EACrD,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,GACpB,IAAI,CAAA;IAEP;;;OAGG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,SAAS,GAAG,MAAM,EACnC,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,KAAK,GAAG,CAAC,EACrD,EAAE,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,GAClC,MAAM,IAAI,CAAA;IAEb;;;;;;;;OAQG;IACH,OAAO,CAAC,CAAC,SAAS,MAAM,SAAS,GAAG,MAAM,EACxC,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,KAAK,EACrD,OAAO,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAC7B,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAEhC;;;OAGG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;IAElC;;;;OAIG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;IAEnC;;;;;OAKG;IACH,KAAK,IAAI,IAAI,CAAA;CACd;AAKD,OAAO,EACL,cAAc,EACd,KAAK,mBAAmB,GACzB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAAC,aAAa,EAAC,MAAM,wBAAwB,CAAA;AACpD,OAAO,EAAC,cAAc,EAAC,MAAM,yBAAyB,CAAA;AACtD,OAAO,EAAC,eAAe,EAAC,MAAM,0BAA0B,CAAA;AACxD,OAAO,EAAC,YAAY,EAAC,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAC,WAAW,EAAC,MAAM,sBAAsB,CAAA;AAChD,OAAO,EAAC,qBAAqB,EAAC,MAAM,gCAAgC,CAAA;AACpE,OAAO,EAAC,MAAM,EAAE,KAAK,WAAW,EAAC,MAAM,iBAAiB,CAAA;AACxD,OAAO,EAAC,aAAa,EAAC,MAAM,wBAAwB,CAAA;AACpD,YAAY,EAAC,kBAAkB,EAAE,mBAAmB,EAAE,UAAU,EAAE,sBAAsB,EAAC,MAAM,wBAAwB,CAAA;AAEvH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,WAAW,CAAC,SAAS,SAAS,MAAM,IAAI,cAAc,CAAC,SAAS,CAAC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAC,MAAM,eAAe,CAAA;AAC3E,YAAY,EAAC,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAE,iBAAiB,EAAC,MAAM,eAAe,CAAA;AACnG,OAAO,EAAC,cAAc,EAAE,qBAAqB,EAAC,MAAM,eAAe,CAAA;AAEnE,MAAM,WAAW,cAAc,CAAC,SAAS,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAChF;;;;OAIG;IACH,IAAI,CAAC,CAAC,SAAS,MAAM,SAAS,GAAG,MAAM,EACrC,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,KAAK,GAAG,CAAC,EACrD,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,GACpB,IAAI,CAAA;IAEP;;;OAGG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,SAAS,GAAG,MAAM,EACnC,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,KAAK,GAAG,CAAC,EACrD,EAAE,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,GAClC,MAAM,IAAI,CAAA;IAEb;;;;;;;;OAQG;IACH,OAAO,CAAC,CAAC,SAAS,MAAM,SAAS,GAAG,MAAM,EACxC,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,KAAK,EACrD,OAAO,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAC7B,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAEhC;;;OAGG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;IAElC;;;;OAIG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;IAEnC;;;;;OAKG;IACH,KAAK,IAAI,IAAI,CAAA;CACd;AAKD,OAAO,EACL,cAAc,EACd,KAAK,mBAAmB,GACzB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAAC,aAAa,EAAC,MAAM,wBAAwB,CAAA;AACpD,OAAO,EAAC,cAAc,EAAC,MAAM,yBAAyB,CAAA;AACtD,OAAO,EAAC,eAAe,EAAC,MAAM,0BAA0B,CAAA;AACxD,OAAO,EAAC,YAAY,EAAC,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAC,WAAW,EAAC,MAAM,sBAAsB,CAAA;AAChD,OAAO,EAAC,qBAAqB,EAAC,MAAM,gCAAgC,CAAA;AACpE,OAAO,EAAC,MAAM,EAAE,KAAK,WAAW,EAAC,MAAM,iBAAiB,CAAA;AACxD,OAAO,EAAC,eAAe,EAAE,KAAK,eAAe,EAAC,MAAM,0BAA0B,CAAA;AAC9E,OAAO,EAAC,aAAa,EAAC,MAAM,wBAAwB,CAAA;AACpD,YAAY,EAAC,kBAAkB,EAAE,mBAAmB,EAAE,UAAU,EAAE,sBAAsB,EAAC,MAAM,wBAAwB,CAAA;AAEvH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,WAAW,CAAC,SAAS,SAAS,MAAM,IAAI,cAAc,CAAC,SAAS,CAAC,CAAA"}

package/dist/ui/index.js

@@ -29,5 +29,6 @@ export { useConnected } from "../react/useConnected";
 export { useSafeArea } from "../react/useSafeArea";
 export { useCapsuleHeaderStyle } from "../react/useCapsuleHeaderStyle";
 export { useRpc } from "../react/useRpc";
+export { useHistoryState } from "../react/useHistoryState";
 export { StreamPreview } from "../react/StreamPreview";
 //# sourceMappingURL=index.js.map

package/dist/ui/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,EAAC,cAAc,EAAE,qBAAqB,EAAC,MAAM,eAAe,CAAA;AA2DnE,uEAAuE;AACvE,sEAAsE;AACtE,+DAA+D;AAC/D,OAAO,EACL,cAAc,GAEf,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAAC,aAAa,EAAC,MAAM,wBAAwB,CAAA;AACpD,OAAO,EAAC,cAAc,EAAC,MAAM,yBAAyB,CAAA;AACtD,OAAO,EAAC,eAAe,EAAC,MAAM,0BAA0B,CAAA;AACxD,OAAO,EAAC,YAAY,EAAC,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAC,WAAW,EAAC,MAAM,sBAAsB,CAAA;AAChD,OAAO,EAAC,qBAAqB,EAAC,MAAM,gCAAgC,CAAA;AACpE,OAAO,EAAC,MAAM,EAAmB,MAAM,iBAAiB,CAAA;AACxD,OAAO,EAAC,aAAa,EAAC,MAAM,wBAAwB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,EAAC,cAAc,EAAE,qBAAqB,EAAC,MAAM,eAAe,CAAA;AA2DnE,uEAAuE;AACvE,sEAAsE;AACtE,+DAA+D;AAC/D,OAAO,EACL,cAAc,GAEf,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAAC,aAAa,EAAC,MAAM,wBAAwB,CAAA;AACpD,OAAO,EAAC,cAAc,EAAC,MAAM,yBAAyB,CAAA;AACtD,OAAO,EAAC,eAAe,EAAC,MAAM,0BAA0B,CAAA;AACxD,OAAO,EAAC,YAAY,EAAC,MAAM,uBAAuB,CAAA;AAClD,OAAO,EAAC,WAAW,EAAC,MAAM,sBAAsB,CAAA;AAChD,OAAO,EAAC,qBAAqB,EAAC,MAAM,gCAAgC,CAAA;AACpE,OAAO,EAAC,MAAM,EAAmB,MAAM,iBAAiB,CAAA;AACxD,OAAO,EAAC,eAAe,EAAuB,MAAM,0BAA0B,CAAA;AAC9E,OAAO,EAAC,aAAa,EAAC,MAAM,wBAAwB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/miniapp",
-  "version": "3.2.1-beta.373",
+  "version": "3.2.1-beta.386",
   "description": "SDK for building MentraOS local miniapps (browser/WebView)",
   "author": "Mentra Labs",
   "license": "Apache-2.0",
@@ -57,7 +57,7 @@
     }
   },
   "dependencies": {
-    "@mentra/cloud-protocol": "3.2.1-beta.373",
+    "@mentra/cloud-protocol": "3.2.1-beta.386",
     "eventemitter3": "^5.0.1"
   },
   "devDependencies": {

package/src/react/index.ts

@@ -10,5 +10,6 @@ export type {MiniappHeaderProps} from "./MiniappHeader"
 export {MentraProvider} from "./MentraProvider"
 export type {MentraProviderProps} from "./MentraProvider"
 export {useRpc, type RpcCallable} from "./useRpc"
+export {useHistoryState, type SetHistoryState} from "./useHistoryState"
 export {StreamPreview} from "./StreamPreview"
 export type {StreamPreviewProps, StreamPreviewStatus, PreviewFit, PreviewConnectionState} from "./StreamPreview"

package/src/react/useHistoryState.ts

@@ -0,0 +1,135 @@
+/**
+ * @fileoverview useHistoryState — `useState` whose changes are browser history
+ * entries, so the phone's back gesture steps back through them.
+ *
+ * The host sends the back gesture (iOS edge swipe, Android back) to the
+ * miniapp's WebView history first, and minimizes the miniapp only once that
+ * history is empty. Screens, tabs and dialogs kept in plain React state never
+ * create history, so back skips past them and minimizes the whole miniapp.
+ * This hook keeps its value in `history.state` instead:
+ *
+ * - Setting a new value pushes a history entry. Back pops it, and the hook
+ *   re-renders with the previous value.
+ * - Setting the value back to what it was before its latest change(s) goes
+ *   back instead of pushing. Closing a dialog with its own button therefore
+ *   consumes the dialog's entry, and the next back gesture does not reopen it.
+ *
+ * Routers in hash or browser mode (react-router's `HashRouter`, wouter's
+ * `useHashLocation`) already create history for pages; use this hook for UI
+ * state that is not a route. Every hook on the page shares one history entry
+ * per step, and `key` names the value within it, so components passing the
+ * same key share the same value. Values are stored as structured clones.
+ */
+
+import {useCallback, useRef, useSyncExternalStore} from "react"
+
+const STATE_KEY = "__mentraHistoryState"
+
+interface Entry {
+  values: Record<string, unknown>
+  /** One record per entry this hook pushed, oldest first, with the value it replaced. */
+  trail: Array<{key: string; previous: unknown}>
+}
+
+const EMPTY: Entry = {values: {}, trail: []}
+
+let cachedState: unknown = null
+let cachedEntry: Entry = EMPTY
+
+/** This hook's slice of the current entry, cached so snapshots stay referentially stable. */
+function currentEntry(): Entry {
+  if (typeof window === "undefined") return EMPTY
+  const state: unknown = window.history.state
+  if (state !== cachedState) {
+    cachedState = state
+    cachedEntry = (state as Record<string, Entry | undefined> | null)?.[STATE_KEY] ?? EMPTY
+  }
+  return cachedEntry
+}
+
+const listeners = new Set<() => void>()
+let boundWindow: Window | null = null
+// history.go() lands later, on popstate. A change applied before then would
+// push on top of the entry being left, and the traversal would pop that push
+// instead, so changes wait in order until the traversal lands.
+let traversing = false
+const pending: Array<() => void> = []
+
+function notify() {
+  listeners.forEach((listener) => listener())
+}
+
+function flush() {
+  while (!traversing && pending.length > 0) pending.shift()!()
+}
+
+function onPopState() {
+  traversing = false
+  notify()
+  // Let every popstate listener, including the host's history bridge, see the
+  // landed entry before a waiting change pushes the next one.
+  setTimeout(flush, 0)
+}
+
+function subscribe(listener: () => void): () => void {
+  if (boundWindow !== window) {
+    boundWindow?.removeEventListener("popstate", onPopState)
+    window.addEventListener("popstate", onPopState)
+    boundWindow = window
+    traversing = false
+    pending.length = 0
+  }
+  listeners.add(listener)
+  return () => listeners.delete(listener)
+}
+
+function whenSettled(change: () => void) {
+  if (traversing || pending.length > 0) pending.push(change)
+  else change()
+}
+
+function apply(key: string, initialValue: unknown, update: unknown) {
+  const {values, trail} = currentEntry()
+  const current = key in values ? values[key] : initialValue
+  const next = typeof update === "function" ? (update as (previous: unknown) => unknown)(current) : update
+  if (Object.is(current, next)) return
+  for (let index = trail.length - 1; index >= 0 && trail[index].key === key; index--) {
+    if (Object.is(trail[index].previous, next)) {
+      traversing = true
+      window.history.go(index - trail.length)
+      return
+    }
+  }
+  // Keep other fields (a router's index, the host's depth marker) on the new entry.
+  const state: unknown = window.history.state
+  const base = state !== null && typeof state === "object" ? state : {}
+  const entry: Entry = {values: {...values, [key]: next}, trail: [...trail, {key, previous: current}]}
+  window.history.pushState({...base, [STATE_KEY]: entry}, "")
+  notify()
+}
+
+export type SetHistoryState<T> = (value: T | ((previous: T) => T)) => void
+
+/**
+ * Like `useState`, but each change is a history entry that the phone's back
+ * gesture undoes. `key` names the value in history state and must be unique
+ * per piece of state on the page.
+ *
+ * ```tsx
+ * const [tab, setTab] = useHistoryState<"home" | "settings">("tab", "home")
+ * const [pickerOpen, setPickerOpen] = useHistoryState("languagePicker", false)
+ * ```
+ */
+export function useHistoryState<T>(key: string, initialValue: T): [T, SetHistoryState<T>] {
+  const initialRef = useRef(initialValue)
+  const read = () => {
+    const {values} = currentEntry()
+    return (key in values ? values[key] : initialRef.current) as T
+  }
+  const value = useSyncExternalStore(subscribe, read, () => initialRef.current)
+  const setValue = useCallback<SetHistoryState<T>>(
+    (update) => whenSettled(() => apply(key, initialRef.current, update)),
+    [key],
+  )
+  return [value, setValue]
+}

package/src/ui/index.ts

@@ -93,6 +93,7 @@ export {useConnected} from "../react/useConnected"
 export {useSafeArea} from "../react/useSafeArea"
 export {useCapsuleHeaderStyle} from "../react/useCapsuleHeaderStyle"
 export {useRpc, type RpcCallable} from "../react/useRpc"
+export {useHistoryState, type SetHistoryState} from "../react/useHistoryState"
 export {StreamPreview} from "../react/StreamPreview"
 export type {StreamPreviewProps, StreamPreviewStatus, PreviewFit, PreviewConnectionState} from "../react/StreamPreview"