@wix/himalaya-cli 0.1411.0 → 0.1413.0

package/templates/retail-store-owner/himalaya.content.json

@@ -31,6 +31,12 @@
     "himi_owner_lite_home": {
       "displayName": "Business Dashboard"
     },
+    "himi_owner_lite_inbox": {
+      "displayName": "Inbox"
+    },
+    "himi_owner_lite_inbox_thread": {
+      "displayName": "Conversation"
+    },
     "himi_owner_lite_manage": {
       "displayName": "Shop"
     },

package/templates/retail-store-owner/tier5-src/_shared/chat-live.ts

@@ -0,0 +1,242 @@
+// How an open chat thread stays live — one helper for owner-lite's Inbox thread and
+// branded-lite's member chat.
+//
+// Two paths, and the worker never has to choose between them by platform:
+//
+//  1. REALTIME. With a Wix Chat channel configured, `load` returns a `_stream` directive
+//     whose url is `wix-realtime://<appDefId>/<channel>?slug=<slug>&resourceId=<chatroom>`.
+//     The iOS and Android hosts open a Wix Duplexer channel for it and
+//     dispatch `onEvent` for each matching message.
+//  2. FALLBACK. With no channel, or once the stream fails (`onError` — which is also what
+//     the web host answers, since it refuses `wix-realtime://`), a `_poll` directive asks
+//     the host to re-read the thread every 4 s.
+//
+// The fallback is a HOST timer, not a worker one: the worker sandbox has no
+// `setInterval`. That is also what keeps it to the
+// foreground — every host suspends a poll when the app is backgrounded or the screen is
+// pooled off-view, and cancels it when the screen is torn down — so a hidden thread never
+// polls. A poll has no stop verb; a thread that has its stream simply never asks for one.
+//
+// An event is only ever "the thread changed". Its payload is not read: its shape is
+// unverified, and the host deliberately does not interpret it either. The worker re-reads
+// the messages instead — one cheap call that cannot desync — and `createReloadGate`
+// folds a burst of events into one read.
+//
+// This file is copied verbatim into every generated starter app, so it explains itself
+// without pointing at anything only this repo has.
+
+import type { PollDirective, StreamDirective } from "@himalaya/state";
+
+/** A Wix Chat Duplexer channel: the `ns` (an app def id), the bare channel name, and the
+ *  event slug a new message arrives under. */
+export interface ChatRealtimeConfig {
+  appDefId: string;
+  channel: string;
+  slug: string;
+}
+
+/** The stream's id. One per screen: a new directive under the same id replaces the old
+ *  channel instead of opening a second one. */
+export const CHAT_LIVE_STREAM_ID = "chat-live";
+/** The fallback poll's id. Re-arming it replaces the timer, never stacks a second one. */
+export const CHAT_LIVE_POLL_ID = "chat-live-poll";
+/** "A message from the other side appears within 5 s." */
+export const CHAT_LIVE_POLL_MS = 4000;
+
+/** Which path is keeping the thread live: `off` before a conversation is open, `stream`
+ *  when a realtime channel was asked for, `poll` on the fallback. Diagnostic. */
+export type ChatLiveMode = "off" | "stream" | "poll";
+
+const GUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** A complete, well-formed channel, or null. A half-filled one would subscribe to
+ *  nothing and never fire, which looks exactly like a quiet conversation. */
+export function chatRealtimeConfig(value: unknown): ChatRealtimeConfig | null {
+  let v = value;
+  if (typeof v === "string") {
+    if (!v.trim()) return null;
+    try { v = JSON.parse(v); } catch { return null; }
+  }
+  if (!v || typeof v !== "object") return null;
+  const { appDefId, channel, slug } = v as Record<string, unknown>;
+  if (typeof appDefId !== "string" || !GUID.test(appDefId)) return null;
+  if (typeof channel !== "string" || !channel.trim()) return null;
+  if (typeof slug !== "string" || !slug.trim()) return null;
+  return { appDefId, channel, slug };
+}
+
+/** The `wix-realtime://` url for one conversation. */
+export function chatRealtimeUrl(cfg: ChatRealtimeConfig, chatroomId: string): string {
+  return `wix-realtime://${cfg.appDefId}/${encodeURIComponent(cfg.channel)}?slug=${encodeURIComponent(cfg.slug)}&resourceId=${encodeURIComponent(chatroomId)}`;
+}
+
+/** The stream directive that keeps `chatroomId` live, or null when there is no channel
+ *  (or no conversation) to open. `onEvent` / `onError` are action names of the calling
+ *  service. */
+export function liveThreadDirective(
+  cfg: ChatRealtimeConfig | null,
+  chatroomId: string,
+  actions: { onEvent: string; onError: string },
+): StreamDirective | null {
+  if (!cfg || !chatroomId) return null;
+  return {
+    id: CHAT_LIVE_STREAM_ID,
+    request: { method: "GET", url: chatRealtimeUrl(cfg, chatroomId) },
+    onEvent: actions.onEvent,
+    onError: actions.onError,
+  };
+}
+
+/** The 4 s foreground re-read. `action` is fully qualified (`"<service>.<action>"`). */
+export function livePollDirective(action: string, intervalMs = CHAT_LIVE_POLL_MS): PollDirective {
+  return { id: CHAT_LIVE_POLL_ID, intervalMs, action, immediate: false };
+}
+
+/** What `load` returns beside its state to keep the conversation live: the stream when a
+ *  channel is configured, else the poll. Nothing when there is no conversation. The
+ *  service's actions must be named `onStreamEvent`, `onStreamError` and `refresh`. */
+export function liveDirectives(
+  cfg: ChatRealtimeConfig | null,
+  chatroomId: string,
+  service: string,
+): { live: ChatLiveMode; _stream?: StreamDirective; _poll?: PollDirective } {
+  if (!chatroomId) return { live: "off" };
+  const stream = liveThreadDirective(cfg, chatroomId, { onEvent: "onStreamEvent", onError: "onStreamError" });
+  if (stream) return { live: "stream", _stream: stream };
+  return { live: "poll", _poll: livePollDirective(`${service}.refresh`) };
+}
+
+/** What `onStreamError` returns beside its state: the stream is gone, so poll. */
+export function liveFallback(service: string): { live: ChatLiveMode; _poll: PollDirective } {
+  return { live: "poll", _poll: livePollDirective(`${service}.refresh`) };
+}
+
+/**
+ * Fold re-read requests so a burst costs one read.
+ *
+ * Requests made in the same tick share one read. A request made while a read is in
+ * flight gets ONE trailing read after it — never more than one, however many arrive —
+ * because the in-flight read may have left the server before the change that prompted
+ * the request, and returning its answer would drop that message.
+ */
+export function createReloadGate<T>(read: () => Promise<T>): { request(): Promise<T> } {
+  let queued: Promise<T> | null = null;
+  let running: Promise<void> | null = null;
+  return {
+    request() {
+      if (queued) return queued;
+      const prior = running ?? Promise.resolve();
+      const next = prior.then(() => {
+        queued = null;
+        return read();
+      });
+      queued = next;
+      const settled = next.then(() => undefined, () => undefined);
+      running = settled;
+      void settled.then(() => {
+        if (running === settled) running = null;
+      });
+      return next;
+    },
+  };
+}
+
+/**
+ * One chat token per thread VISIT.
+ *
+ * Every chat-web call needs a token, and minting one is a request of its own — so a thread
+ * that re-reads every 4 s would otherwise mint every 4 s. `get()` mints on first use and
+ * shares that token with every read and send; `reset()` starts a new visit; `drop(p)`
+ * forgets a token after a call that used it failed (an expired token costs one failed call,
+ * and the next one mints again). `drop` only forgets THAT token: a late failure from an
+ * earlier visit must not throw away the token the current visit just minted.
+ */
+export function createVisitToken(mint: () => Promise<string>): {
+  get(): Promise<string>;
+  drop(token: Promise<string> | null): void;
+  reset(): void;
+} {
+  let current: Promise<string> | null = null;
+  const drop = (token: Promise<string> | null): void => {
+    if (token && current === token) current = null;
+  };
+  return {
+    get() {
+      if (!current) {
+        const minted = mint();
+        current = minted;
+        minted.catch(() => drop(minted));
+      }
+      return current;
+    },
+    drop,
+    reset() {
+      current = null;
+    },
+  };
+}
+
+/** Did a chat-web call fail because its token was refused? The status chat-web uses for an
+ *  expired chatToken is NOT verified against a live session: 401 and 403 are both treated as
+ *  "refused", and either way a retry with the same message id is the same send intent, so a
+ *  wrong guess costs one extra request, never a second message. Any other failure may have
+ *  posted the message, so it is not retried. */
+export function isTokenRejected(e: unknown): boolean {
+  return /HTTP 40[13]\b/.test(String((e as Error)?.message ?? e ?? ""));
+}
+
+/** UUID v4 for a send's idempotency id (the worker realm has no crypto.randomUUID). */
+export function uuidV4(): string {
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.floor(Math.random() * 16);
+    return (c === "x" ? r : (r & 0x3) | 0x8).toString(16);
+  });
+}
+
+/**
+ * Send ids that belong to the INTENT, not the tap.
+ *
+ * The same id on a retry is the same send to chat-web, so the server keeps one message. A
+ * send that failed ambiguously (a gateway timeout after the backend stored it) and is tapped
+ * again must reuse its id, or the business receives the message twice. An intent is the
+ * conversation plus the exact text; it is settled once the send succeeds, and any other text
+ * is a new intent.
+ */
+export function createSendIntents(): { idFor(chatroomId: string, text: string): string; settle(chatroomId: string, text: string): void } {
+  const ids = new Map<string, string>();
+  const keyOf = (chatroomId: string, text: string) => `${chatroomId}\u0000${text}`;
+  return {
+    idFor(chatroomId, text) {
+      const key = keyOf(chatroomId, text);
+      let id = ids.get(key);
+      if (!id) { id = uuidV4(); ids.set(key, id); }
+      return id;
+    },
+    settle(chatroomId, text) {
+      ids.delete(keyOf(chatroomId, text));
+    },
+  };
+}
+
+/** Post with the visit's token, re-minting once if chat-web refused the token. Whichever
+ *  token a failed attempt used is dropped, so a rejected token is never reused. */
+export async function postWithVisitToken(
+  token: ReturnType<typeof createVisitToken>,
+  send: (chatToken: string) => Promise<void>,
+): Promise<void> {
+  const first = token.get();
+  try {
+    await send(await first);
+    return;
+  } catch (e) {
+    token.drop(first);
+    if (!isTokenRejected(e)) throw e;
+  }
+  const retry = token.get();
+  try {
+    await send(await retry);
+  } catch (e) {
+    token.drop(retry);
+    throw e;
+  }
+}

package/templates/retail-store-owner/tier5-src/_shared/detail-presence.ts

@@ -0,0 +1,51 @@
+// Whether a detail screen's entity is there — the worker half of the shared not-found
+// state (the `detailNotFound` descriptor builder).
+//
+// A detail screen's descriptor asks two questions, both as `hiddenWhen` flags:
+//   • `noEntity`     → hide the entity's content AND its actions (Like, Follow, Send…)
+//   • `hideNotFound` → hide the not-found state
+// Four answers exist, and only one of them shows the not-found state:
+//   loading  — a loading line (`hideLoading` false); no content, no actions, no verdict
+//   found    — content + actions shown
+//   missing  — not-found shown, content + actions hidden
+//   failed   — a load-error line (`hideLoadError` false); no content, no actions
+// A load that FAILS for any reason other than "not found" is `failed`, never `missing`:
+// an offline device must not tell the user their invoice was deleted.
+
+export type Presence = "loading" | "found" | "missing" | "failed";
+
+export interface PresenceFlags {
+  found: boolean;
+  notFound: boolean;
+  noEntity: boolean;
+  hideNotFound: boolean;
+  hideLoading: boolean;
+  hideLoadError: boolean;
+}
+
+export function presence(p: Presence): PresenceFlags {
+  return {
+    found: p === "found", notFound: p === "missing", noEntity: p !== "found", hideNotFound: p !== "missing",
+    hideLoading: p !== "loading", hideLoadError: p !== "failed",
+  };
+}
+
+/** The entity id the host baked into this detail screen (`himi.open` params). */
+export function detailInputId(): string {
+  const v = (globalThis as { himalaya?: { input?: { id?: unknown } } }).himalaya?.input?.id;
+  return typeof v === "string" ? v.trim() : "";
+}
+
+/** True when a Wix read failed because the record does not exist: the SDK rejects
+ *  with "HTTP <code>: <body>", so an HTTP 404, or Wix's `NOT_FOUND` error code. A bare
+ *  "not found" in a message is NOT enough — "capability wix_api not found" or "Method
+ *  not found" is a broken integration, and must not tell the user the record is gone. */
+export function isNotFoundError(error: unknown): boolean {
+  const msg = String((error as { message?: unknown } | null)?.message ?? error ?? "");
+  return /\bHTTP\s*404\b/.test(msg) || /\bNOT_FOUND\b/.test(msg);
+}
+
+/** `missing` for a not-found failure, `failed` (claim nothing) otherwise. */
+export function presenceAfterError(error: unknown): PresenceFlags {
+  return presence(isNotFoundError(error) ? "missing" : "failed");
+}

package/templates/retail-store-owner/tier5-src/himi-owner-lite-inbox/index.ts

@@ -0,0 +1,308 @@
+// Tier-5 bundle: __HIMI_APP_NAME__ — Inbox (the site's customer conversations).
+//
+// Transport is chat-web, the one the real Owner inbox uses: the public inbox/v2 REST has
+// no list endpoint. `listChatrooms` mints an owner (unified-list) chatToken and reads the
+// v2 list, site-scoped by the owner bridge's per-site instance.
+//
+// The list logic (rows, All/Unread, search, archive, mark unread) is lifted from the
+// wix-owner-clone app's `wix-owner-inbox` worker; that app keeps its own copy. What is
+// different here is honesty: a failed read is the shared owner error state with Retry —
+// never an empty "No messages yet", and never sample rows. An owner
+// who sees "no messages" must be able to trust that there are none.
+//
+// FRESHNESS. The thread is where a conversation is read, and chat-web marks it read
+// there; this list re-loads every time it appears, so the unread badge reflects the read
+// state the server applied while the owner was in the thread. While the list is visible
+// it also re-reads on a slow foreground `_poll`, so a conversation that arrives while the
+// owner is looking at the list shows up without a tap. The host suspends that poll in the
+// background and when the screen is pooled off-view — but NOT while another tab of a
+// keep-alive tab bar is showing, which is why the cadence is slow.
+//
+// A push does not refresh this list: `push.observerAction` lands in the app-level nav worker
+// only.
+
+import { defineService, type PollDirective } from "@himalaya/state";
+import { listChatrooms, archiveChatroom, markChatroomUnread, type Chatroom } from "@himalaya/wix-chat-web";
+import { formatMonthDay } from "../_shared/engine-intl.js";
+import { ownerLoadError, ownerWriteError } from "../_shared/owner-load-error.js";
+import { stashCopy, copyParam } from "../_shared/himi-copy.js";
+
+const SERVICE = "ownerLiteInbox";
+/** How many conversations one read asks for. */
+const PAGE_SIZE = 50;
+/** The list's own re-read. Slow: a new conversation is worth seeing soon, not within the
+ *  second, and a keep-alive tab keeps polling while the owner is on another tab. */
+const LIST_POLL_MS = 30000;
+
+export interface InboxRow {
+  id: string;
+  /** chat-web chatroom id — the thread screen uses it as-is. */
+  kind: "chatroom";
+  display: string;
+  /** Last-message preview. The time is its own field. */
+  subtitle: string;
+  initial: string;
+  image: string;
+  hasImage: boolean;
+  noImage: boolean;
+  unread: number;
+  /** "3", "99+", or "" when read. */
+  unreadText: string;
+  unreadHidden: boolean;
+  /** "now" / "5m" / "2h" / "3d" / "Jun 5". */
+  timeText: string;
+  /** The row's whole spoken name: who, how many unread, the preview. */
+  spokenLabel: string;
+}
+
+export interface InboxState {
+  status: "loading" | "ready" | "error";
+  /** FragmentSlot case: "loading" until the first answer, then "ready" — for good. A
+   *  re-load keeps the rows on screen instead of flashing the skeleton. */
+  phase: "loading" | "ready";
+  all: InboxRow[];
+  items: InboxRow[];
+  filter: "all" | "unread";
+  query: string;
+  error: string;
+  /** Why the last archive / mark-unread did not happen, or "". */
+  actionError: string;
+  unreadCount: number;
+  summary: string;
+  notErrored: boolean;
+  hideList: boolean;
+  /** One empty state each — "No messages yet", "You're all caught up", "No matches".
+   *  At most one is ever shown, and none while the read failed. */
+  hideEmptyAll: boolean;
+  hideEmptyUnread: boolean;
+  hideEmptyNoMatch: boolean;
+  _poll?: PollDirective;
+}
+
+function relTime(ms?: number): string {
+  if (!ms) return "";
+  const d = new Date(ms);
+  if (isNaN(d.getTime())) return "";
+  const min = Math.floor((Date.now() - ms) / 60000);
+  if (min < 1) return copyParam("ownerInbox.now", "now");
+  if (min < 60) return `${min}m`;
+  const hr = Math.floor(min / 60);
+  if (hr < 24) return `${hr}h`;
+  const day = Math.floor(hr / 24);
+  if (day < 7) return `${day}d`;
+  return formatMonthDay(d);
+}
+
+export function rowOf(c: Chatroom): InboxRow {
+  const fallback = copyParam("ownerInbox.untitled", "Conversation");
+  const display = (c.displayData?.name || c.lastMessage?.senderDisplayData?.name || "").trim() || fallback;
+  const image = c.displayData?.image?.url || c.lastMessage?.senderDisplayData?.image?.url || "";
+  const unread = Math.max(0, c.unreadCount ?? 0);
+  const unreadText = unread > 0 ? (unread > 99 ? "99+" : String(unread)) : "";
+  const subtitle = (c.lastMessage?.summary || "").trim().slice(0, 120);
+  const unreadLabel = unread === 0 ? "" : unread === 1
+    ? copyParam("ownerInbox.oneUnread", "1 unread message")
+    : `${unreadText} ${copyParam("ownerInbox.manyUnread", "unread messages")}`;
+  return {
+    id: c.id,
+    kind: "chatroom",
+    display,
+    subtitle,
+    initial: (display[0] || "#").toUpperCase(),
+    image,
+    hasImage: !!image,
+    noImage: !image,
+    unread,
+    unreadText,
+    unreadHidden: unread === 0,
+    timeText: relTime(c.lastMessage?.createdAt),
+    spokenLabel: [display, unreadLabel, subtitle].filter(Boolean).join(", "),
+  };
+}
+
+function narrow(all: InboxRow[], filter: InboxState["filter"], query: string): InboxRow[] {
+  const rows = filter === "unread" ? all.filter((r) => r.unread > 0) : all;
+  const q = query.trim().toLowerCase();
+  return q ? rows.filter((r) => r.display.toLowerCase().includes(q) || r.subtitle.toLowerCase().includes(q)) : rows;
+}
+
+/** Every derived field, from the real inputs only — never inherited from a spread. */
+export function shape(input: {
+  status: InboxState["status"];
+  all?: InboxRow[];
+  filter?: InboxState["filter"];
+  query?: string;
+  error?: string;
+  actionError?: string;
+  phase?: InboxState["phase"];
+}): InboxState {
+  const { status } = input;
+  const all = input.all ?? [];
+  const filter = input.filter ?? "all";
+  const query = input.query ?? "";
+  const items = narrow(all, filter, query);
+  const ready = status === "ready";
+  const empty = ready && items.length === 0;
+  const searching = query.trim() !== "";
+  const unreadCount = all.filter((r) => r.unread > 0).length;
+  return {
+    status,
+    phase: input.phase ?? (status === "loading" ? "loading" : "ready"),
+    all,
+    items,
+    filter,
+    query,
+    error: input.error ?? "",
+    actionError: input.actionError ?? "",
+    unreadCount,
+    summary: !ready || all.length === 0 ? "" : unreadCount === 0
+      ? copyParam("ownerInbox.allRead", "All read")
+      : unreadCount === 1
+        ? copyParam("ownerInbox.oneUnreadConversation", "1 unread conversation")
+        : `${unreadCount} ${copyParam("ownerInbox.manyUnreadConversations", "unread conversations")}`,
+    notErrored: status !== "error",
+    hideList: !ready || items.length === 0,
+    hideEmptyNoMatch: !(empty && searching),
+    hideEmptyUnread: !(empty && !searching && filter === "unread"),
+    hideEmptyAll: !(empty && !searching && filter === "all"),
+  };
+}
+
+const INITIAL = shape({ status: "loading" });
+
+function idOf(arg: unknown): string {
+  if (typeof arg === "string") return arg;
+  const id = (arg as { id?: unknown } | null | undefined)?.id;
+  return typeof id === "string" ? id : "";
+}
+
+function textOf(arg: unknown): string {
+  if (typeof arg === "string") return arg;
+  const v = (arg as { value?: unknown; text?: unknown } | null | undefined);
+  return typeof v?.value === "string" ? v.value : typeof v?.text === "string" ? v.text : "";
+}
+
+/** The filter a SegmentedControl picked: every renderer injects `selectedId`
+ *  (the SDUI action-payload contract); a bare value is accepted too. */
+function filterOf(arg: unknown): InboxState["filter"] {
+  const picked = (arg as { selectedId?: unknown } | null | undefined)?.selectedId;
+  const v = (typeof picked === "string" ? picked : textOf(arg)).toLowerCase();
+  return v.includes("unread") ? "unread" : "all";
+}
+
+/** The live service state — what an action that awaited must build on (see `read`). A
+ *  typed function rather than `svc.getState()` inline, so `svc`'s own initializer does not
+ *  reference it. */
+function liveState(): InboxState {
+  return svc.getState();
+}
+
+/** Archives Wix has confirmed, with the read generation each was confirmed at. A read
+ *  that LEFT before the archive landed may still list the room; only a read that started
+ *  after it can be trusted to say whether the room is gone. */
+const archivedAt = new Map<string, number>();
+/** Mark-unreads Wix has confirmed, fenced the same way: a read that left before the write
+ *  landed may still report the room read, and must not clear the badge the owner just set.
+ *  A read that started after the write may still lag it, so the fence also holds for a
+ *  short grace after confirmation — time-bound, not read-counted, so a conversation the
+ *  owner then opens and reads loses its badge on the next read after the grace. */
+const unreadAt = new Map<string, { at: number; until: number }>();
+const UNREAD_GRACE_MS = 3000;
+let readGeneration = 0;
+/** The newest read whose answer reached the screen. Reads are not ordered — a `load` on
+ *  return can start a read while a poll tick's is still in flight — so an OLDER read that
+ *  finishes after a newer one is dropped instead of painting the past over it. */
+let appliedGeneration = 0;
+
+/**
+ * Read the list and put it onto the LIVE state. The runtime replaces the whole service
+ * state with what an action returns, so a read that resolves after the owner searched,
+ * filtered or archived must take the filter, query and archives from now — not from the
+ * state it started with — or it would quietly undo them.
+ */
+async function read(): Promise<InboxState> {
+  const generation = ++readGeneration;
+  try {
+    const rooms = await listChatrooms(PAGE_SIZE);
+    // Stale first: a read older than one already painted changes nothing — not the screen,
+    // and not the fences either.
+    if (generation < appliedGeneration) return liveState();
+    appliedGeneration = generation;
+    for (const [id, at] of archivedAt) if (at < generation && !rooms.some((c) => c?.id === id)) archivedAt.delete(id);
+    const clock = Date.now();
+    for (const [id, fence] of unreadAt) if (fence.at < generation && clock >= fence.until) unreadAt.delete(id);
+    const all = rooms
+      .filter((c) => c?.id && !c.isArchived && !archivedAt.has(c.id))
+      .map((c) => rowOf(unreadAt.has(c.id) ? { ...c, unreadCount: Math.max(1, c.unreadCount ?? 0) } : c));
+    const now = liveState();
+    return shape({ status: "ready", all, filter: now.filter, query: now.query });
+  } catch (e) {
+    // A failed mint or list is not an empty Inbox. Rows already on screen are dropped
+    // too: they would claim a state the owner can no longer confirm. An older read failing
+    // after a newer one succeeded says nothing about now, so it is dropped.
+    if (generation < appliedGeneration) return liveState();
+    appliedGeneration = generation;
+    const now = liveState();
+    return shape({ status: "error", filter: now.filter, query: now.query, error: ownerLoadError(e), phase: "ready" });
+  }
+}
+
+const poll: PollDirective = { id: "inbox-list", intervalMs: LIST_POLL_MS, action: `${SERVICE}.refresh`, immediate: false };
+
+const svc = defineService<InboxState, {
+  load: (s: InboxState, arg?: unknown) => Promise<InboxState>;
+  refresh: (s: InboxState) => Promise<InboxState>;
+  filter: (s: InboxState, arg?: unknown) => InboxState;
+  search: (s: InboxState, arg?: unknown) => InboxState;
+  archive: (s: InboxState, arg?: unknown) => Promise<InboxState>;
+  markUnread: (s: InboxState, arg?: unknown) => Promise<InboxState>;
+}>(SERVICE, {
+  state: INITIAL,
+  actions: {
+    // onAppear — every appearance, so returning from a thread re-reads the unread state.
+    load: async (_s, arg) => {
+      stashCopy(arg);
+      return { ...(await read()), _poll: poll };
+    },
+    // The poll tick, and Retry's re-read. A transient failure during a tick still shows
+    // the error: a list that silently stops updating is the worse lie.
+    refresh: async () => read(),
+    filter: (s, arg) => shape({ status: s.status, all: s.all, filter: filterOf(arg), query: s.query, error: s.error, phase: s.phase }),
+    search: (s, arg) => shape({ status: s.status, all: s.all, filter: s.filter, query: textOf(arg), error: s.error, phase: s.phase }),
+    // Swipe → Archive (reversible). The row leaves only once Wix confirms it.
+    archive: async (s, arg) => {
+      const id = idOf(arg);
+      if (!id) return s;
+      try {
+        await archiveChatroom(id, true);
+      } catch (e) {
+        return { ...liveState(), actionError: ownerWriteError(e) };
+      }
+      archivedAt.set(id, readGeneration);
+      const now = liveState();
+      return shape({ status: now.status, all: now.all.filter((r) => r.id !== id), filter: now.filter, query: now.query, error: now.error, phase: now.phase });
+    },
+    // Swipe → Mark as unread. The badge shows at least 1 once Wix confirms it.
+    markUnread: async (s, arg) => {
+      const id = idOf(arg);
+      if (!id) return s;
+      try {
+        await markChatroomUnread(id);
+      } catch (e) {
+        return { ...liveState(), actionError: ownerWriteError(e) };
+      }
+      unreadAt.set(id, { at: readGeneration, until: Date.now() + UNREAD_GRACE_MS });
+      s = liveState();
+      const all = s.all.map((r) => (r.id === id ? rowOf({
+        id: r.id,
+        unreadCount: Math.max(1, r.unread),
+        displayData: { name: r.display, image: { url: r.image } },
+        lastMessage: { summary: r.subtitle },
+      }) : r)).map((r, i) => (r.id === id ? { ...r, timeText: s.all[i].timeText } : r));
+      return shape({ status: s.status, all, filter: s.filter, query: s.query, error: s.error, phase: s.phase });
+    },
+  },
+});
+
+svc.load();
+export { svc };