shabbat-gate 0.1.1 → 0.2.0

package/README.md

@@ -1,91 +1,194 @@
-# shabbat-gate
-
-[קריאה בעברית](README.he.md)
-
-Cloudflare Pages / Workers middleware that automatically closes a site to human visitors
-during Shabbat and major Jewish holidays (Israel-observance rules) - while always letting
-search engines and AI crawlers through, so SEO stays unaffected.
-
-## Why
-
-- **Israel single-day Yom Tov, not diaspora 2-day.** The holiday calendar is fetched from
-  Hebcal's free public API with `i=on`, which is critical - without it you'd get the diaspora
-  reckoning (an extra blocked day) instead of the correct single-day Yom Tov used in Israel.
-- **Bots always get through.** A broad, case-insensitive user-agent allowlist (Googlebot,
-  Bingbot, GPTBot, ClaudeBot, and many others) is checked first, before any other logic runs.
-  The gate only ever affects human visitors - crawlers and indexers see the real site 24/7, so
-  ranking and AI-search visibility are never impacted by the site being "closed."
-- **Fails open.** Any error (network failure, bad API response, whatever) falls through to the
-  real site rather than showing an error page. An accidental block on a regular Tuesday would be
-  a real, visible bug; an occasional missed block during a rare error is a minor, invisible one.
-
-## Install
-
-```sh
-npm install shabbat-gate
-```
-
-## Usage
-
-In a Cloudflare Pages project, add `functions/_middleware.ts`:
-
-```ts
-import { createShabbatGate } from 'shabbat-gate';
-
-const gate = createShabbatGate({ siteName: 'My Site' });
-
-export const onRequest: PagesFunction = (context) => gate(context);
-```
-
-## Config
-
-```ts
-export interface ShabbatGateConfig {
-  siteName: string;
-
-  /** Decimal lat/long for zmanim. Both default to Jerusalem (31.7683, 35.2137) if
-   *  omitted - a fine single reference point for all of Israel at this granularity. */
-  latitude?: number;
-  longitude?: number;
-
-  /** Query param name + required value that bypasses the gate entirely, so the site
-   *  owner can preview/test on any day. Keep the value non-guessable - this is a
-   *  testing convenience, not real auth. */
-  bypassParam?: string;
-  bypassValue?: string;
-
-  /** Optional custom holding-page renderer. Defaults to a Hebrew, mobile-responsive
-   *  page showing siteName and when the site reopens. */
-  renderHoldingPage?: (ctx: { siteName: string; reasonLabel: string; untilLabel: string }) => string;
-}
-```
-
-Full example:
-
-```ts
-import { createShabbatGate } from 'shabbat-gate';
-
-const gate = createShabbatGate({
-  siteName: 'tehila·games',
-  latitude: 31.7683,
-  longitude: 35.2137,
-  bypassParam: 'preview',
-  bypassValue: 'letmein-9f3a7c',
-});
-
-export const onRequest: PagesFunction = (context) => gate(context);
-```
-
-## How it works
-
-1. Bot check (allowlist regex on the `user-agent` header) - matches pass straight through.
-2. Bypass check - if the bypass query param + value match, pass straight through.
-3. Fetch (with ~24h caching via the Workers Cache API) the merged list of Shabbat and major
-   holiday windows from Hebcal, ~45 days into the future.
-4. If the current time falls inside a window, serve the holding page (HTTP 200). Otherwise let
-   the real site through.
-5. Any error along the way falls through to the real site.
-
-## License
-
-MIT
+# shabbat-gate
+
+[קריאה בעברית](README.he.md)
+
+Cloudflare Pages / Workers middleware that automatically closes a site to human visitors
+during Shabbat and major Jewish holidays (Israel-observance rules) - while always letting
+search engines and AI crawlers through, so SEO stays unaffected.
+
+## Why
+
+- **Israel single-day Yom Tov, not diaspora 2-day.** The holiday calendar is fetched from
+  Hebcal's free public API with `i=on`, which is critical - without it you'd get the diaspora
+  reckoning (an extra blocked day) instead of the correct single-day Yom Tov used in Israel.
+- **Bots always get through.** A broad, case-insensitive user-agent allowlist (Googlebot,
+  Bingbot, GPTBot, ClaudeBot, and many others) is checked first, before any other logic runs.
+  The gate only ever affects human visitors - crawlers and indexers see the real site 24/7, so
+  ranking and AI-search visibility are never impacted by the site being "closed."
+- **Fails open.** Any error (network failure, bad API response, whatever) falls through to the
+  real site rather than showing an error page. An accidental block on a regular Tuesday would be
+  a real, visible bug; an occasional missed block during a rare error is a minor, invisible one.
+
+## Install
+
+```sh
+npm install shabbat-gate
+```
+
+## Usage
+
+In a Cloudflare Pages project, add `functions/_middleware.ts`:
+
+```ts
+import { createShabbatGate } from 'shabbat-gate';
+
+const gate = createShabbatGate({ siteName: 'My Site' });
+
+export const onRequest: PagesFunction = (context) => gate(context);
+```
+
+### Using with a plain Worker + Assets binding (not Pages)
+
+`createShabbatGate` returns a Pages-Functions-shaped handler (`(context) => Response`), which
+doesn't fit a plain Worker's `fetch(request, env)` signature (there's no `next()`). Use
+`createShabbatGateForWorker` instead - it returns `null` for "let the real site through" and a
+`Response` for "serve the holding page":
+
+```ts
+import { createShabbatGateForWorker } from 'shabbat-gate';
+
+const gate = createShabbatGateForWorker({ siteName: 'My Site' });
+
+export default {
+  async fetch(request: Request, env: { ASSETS: Fetcher }) {
+    const blocked = await gate(request);
+    return blocked ?? env.ASSETS.fetch(request);
+  },
+};
+```
+
+**Gotcha that silently defeats the whole gate:** a Cloudflare Worker with an `assets` binding
+serves any request matching a file in the assets directory *directly*, without invoking the
+Worker's `fetch` handler at all - unless `run_worker_first: true` is set. Without it, the gate
+code runs and looks correctly wired up, tests pass, but real page requests (which almost always
+match a static asset) never reach it, so the site never actually closes. In `wrangler.jsonc`:
+
+```jsonc
+{
+  "assets": {
+    "directory": "./dist",
+    "binding": "ASSETS",
+    "run_worker_first": true
+  }
+}
+```
+
+## Config
+
+```ts
+export interface ShabbatGateConfig {
+  siteName: string;
+
+  /** Decimal lat/long for zmanim. Both default to Jerusalem (31.7683, 35.2137) if
+   *  omitted - a fine single reference point for all of Israel at this granularity. */
+  latitude?: number;
+  longitude?: number;
+
+  /** Query param name + required value that bypasses the gate entirely, so the site
+   *  owner can preview/test on any day. Keep the value non-guessable - this is a
+   *  testing convenience, not real auth. */
+  bypassParam?: string;
+  bypassValue?: string;
+
+  /** Optional custom holding-page renderer. Defaults to a Hebrew, mobile-responsive
+   *  page showing siteName and when the site reopens. `reasonLabel` and `closingLabel`
+   *  differ grammatically for plain Shabbat ("שבת קודש" opening vs. "השבת" closing) -
+   *  use `closingLabel` for "back after ___", not `reasonLabel` again. */
+  renderHoldingPage?: (ctx: {
+    siteName: string;
+    reasonLabel: string;
+    closingLabel: string;
+    untilLabel: string;
+    /** Optional localized message shown below the Hebrew one (with a blank-line
+     *  gap), for a visitor outside Israel, in their own browser language. Absent
+     *  for visitors in Israel, Hebrew-speaking visitors, or unknown location. */
+    secondary?: { dir: 'ltr' | 'rtl'; lines: string[] };
+  }) => string;
+
+  /** Minutes to close the site *before* candle-lighting and reopen *after*
+   *  havdalah, on top of the raw Hebcal window. Defaults to 0. Useful padding
+   *  against clock drift / last-minute browsing right at the boundary. */
+  bufferMinutes?: number;
+
+  /** When `true`, also block a visitor during Shabbat/Yom Tov in *their own*
+   *  location (from Cloudflare's `request.cf` geolocation), not only Israel's.
+   *  Closed to them if it's Shabbat in Israel *or* where they are - so an
+   *  overseas visitor stays blocked from Israel's candle-lighting through their
+   *  own local havdalah. Holidays for a visitor outside Israel use diaspora
+   *  two-day Yom Tov reckoning. Defaults to `false` (Israel-only). Falls back to
+   *  the Israel-only decision when a request has no geolocation (local dev,
+   *  unplaceable IP). */
+  enforceVisitorLocation?: boolean;
+}
+```
+
+### Blocking by the visitor's timezone too (`enforceVisitorLocation`)
+
+By default the gate uses **Israel's** calendar for every visitor worldwide: the moment
+Shabbat ends in Israel, the site reopens for everyone - including a US visitor for whom it's
+still Shabbat. Set `enforceVisitorLocation: true` to make it the **union of two Shabbatot**:
+the site is closed to a visitor if it's Shabbat/Yom Tov in Israel **or** where they are. A New
+York visitor is then blocked from Israel's candle-lighting (even if it's still Friday afternoon
+for them) continuously through their own local havdalah. Holidays are reckoned diaspora-style
+(two-day Yom Tov) for visitors abroad. Chanukah, Purim, Yom HaAtzma'ut and Chol HaMoed never
+block, in Israel or abroad.
+
+### Localized message for visitors abroad
+
+When a visitor is outside Israel, the default holding page shows the Hebrew message first,
+then (below a two-line gap) a message in their browser language (from `Accept-Language`).
+Built-in languages: English (default/fallback), French, Russian, Spanish, German, and Arabic
+(rendered right-to-left). Hebrew speakers and visitors in Israel get no second message; the
+reopen time is shown in the visitor's own timezone. This works even without `enforceVisitorLocation` (whenever the site is
+closed and the visitor is known to be abroad).
+
+Full example:
+
+```ts
+import { createShabbatGate } from 'shabbat-gate';
+
+const gate = createShabbatGate({
+  siteName: 'tehila·games',
+  latitude: 31.7683,
+  longitude: 35.2137,
+  bypassParam: 'preview',
+  bypassValue: 'letmein-9f3a7c',
+  bufferMinutes: 10,
+});
+
+export const onRequest: PagesFunction = (context) => gate(context);
+```
+
+## How it works
+
+1. Bot check (allowlist regex on the `user-agent` header) - matches pass straight through.
+2. Bypass check - if the bypass query param + value match, pass straight through.
+3. Fetch (with ~24h caching via the Workers Cache API) the merged list of Shabbat and major
+   holiday windows from Hebcal, ~45 days into the future - one call to Hebcal's `/hebcal`
+   endpoint (`ss=on` for weekly Shabbat + `maj=on` for major holidays), passing `latitude`/
+   `longitude` directly so every window is correctly localized, not just the nearest one.
+4. `bufferMinutes` (if set) is applied on top of the fetched windows before the time check.
+5. If `enforceVisitorLocation` is set, a second window list is fetched for the visitor's own
+   location (from `request.cf`, diaspora reckoning when abroad) and unioned with Israel's -
+   blocking if the time falls inside either. Overlapping windows are coalesced into one
+   continuous window so the shown reopen time is accurate.
+6. If the current time falls inside a window, serve the holding page (HTTP 200). Otherwise let
+   the real site through.
+7. Any error along the way falls through to the real site.
+
+## Internal cache key
+
+The merged window list is cached under a fixed internal key
+(`https://internal.cache/shabbat-gate-windows-v1`, exported as `INTERNAL_CACHE_KEY_URL`) for
+~24h via the Workers Cache API. If your own code also caches derived data (e.g. windows with
+your own buffer applied) via `caches.default`, use a different key - reusing this one will
+silently serve stale, unprocessed data for up to 24h.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for what changed in each release, including root-cause
+explanations for fixed bugs.
+
+## License
+
+MIT

package/dist/hebcal.d.ts

@@ -1,27 +1,102 @@
 export interface Window {
     start: number;
     end: number;
+    /** Hebrew label for "the site is closed for ___". */
     label: string;
+    /** Hebrew label for "back after ___ [ends]" - grammatically distinct from
+     *  `label` for Shabbat ("שבת קודש" opening vs. "השבת" closing). */
+    closingLabel: string;
 }
 interface HebcalItem {
     title: string;
     hebrew?: string;
     date: string;
     category: string;
+    /** Present on `candles`/`havdalah` items: the title of the holiday/parasha
+     *  it belongs to (e.g. "Erev Rosh Hashana", or "Parashat Devarim" for a
+     *  plain Shabbat week). Used to cross-reference against `holiday` items'
+     *  own `title` to find the right Hebrew label for *this specific* window,
+     *  instead of trusting whichever `holiday` item happened to appear most
+     *  recently in the feed (which leaks into unrelated windows - see below). */
+    memo?: string;
 }
+/** Hebcal's own "candles"/"havdalah" items always carry the generic literal
+ *  "הדלקת נרות"/"הבדלה" in their `hebrew` field, never the occasion name - so
+ *  it's unusable as a display label on its own. For a plain Shabbat week
+ *  (no accompanying `holiday` item), fall back to this fixed pair instead. */
+export declare const SHABBAT_LABEL = "\u05E9\u05D1\u05EA \u05E7\u05D5\u05D3\u05E9";
+export declare const SHABBAT_CLOSING_LABEL = "\u05D4\u05E9\u05D1\u05EA";
 /**
  * Pairs candles/havdalah events into continuous windows. Multi-day holidays
  * (e.g. Rosh Hashana) emit two "candles" events but only one "havdalah" at the
  * very end, so candles cannot simply be paired 1:1 with the next havdalah.
  * Instead: open a window on the first candles seen while none is open, ignore
  * further candles while one is open, and close on the next havdalah.
+ *
+ * `defaults` overrides the label for windows that have no matching `holiday`
+ * item (i.e. plain Shabbat weeks) - pass it when calling this with a merged
+ * feed that mixes weekly Shabbat and holiday items together.
+ *
+ * Holiday windows pick up the matching `holiday` item's own Hebrew name (e.g.
+ * "ערב ראש השנה") by matching the opening `candles` item's `memo` field
+ * against a `holiday` item's `title` - not just "the most recent holiday item
+ * seen so far". Some `holiday`-category items (e.g. fast days like תשעה באב,
+ * which are `maj=on` but have no candle-lighting of their own) never get
+ * consumed by a window; naively tracking "last holiday label seen" would leak
+ * their label into the next, unrelated Shabbat window instead of falling back
+ * to `defaults`.
  */
-export declare function pairWindows(items: HebcalItem[]): Window[];
+export declare function pairWindows(items: HebcalItem[], defaults?: {
+    label: string;
+    closingLabel: string;
+}): Window[];
+export interface FetchWindowsOptions {
+    /** `true` (default) = Israel single-day Yom Tov reckoning (`i=on`). `false` =
+     *  diaspora two-day Yom Tov reckoning (`i=off`), correct for a visitor
+     *  physically outside Israel. Only affects how many days a *Torah* Yom Tov
+     *  spans - the `maj=on&min=off&mod=off` filter is independent of `i`, so
+     *  Chanukah/Purim/Yom HaAtzma'ut/Chol HaMoed stay excluded either way. */
+    israelMode?: boolean;
+    /** IANA timezone the candle-lighting/havdalah times are computed against
+     *  (defaults to `'Asia/Jerusalem'`). Pass the visitor's own timezone when
+     *  computing their local windows so day boundaries line up with their sunset,
+     *  not Jerusalem's. */
+    tzid?: string;
+}
+/**
+ * Fetches and merges Shabbat + major-holiday windows for the next ~45 days from
+ * Hebcal's free public JSON API. Defaults to Israel single-day Yom Tov mode at
+ * Jerusalem's timezone; pass `options` to compute windows for a visitor's own
+ * location/reckoning instead (see {@link FetchWindowsOptions}).
+ *
+ * Uses a *single* call to the `/hebcal` endpoint (not the separate `/shabbat`
+ * endpoint) with `ss=on` added, passing `latitude`/`longitude` directly
+ * instead of a `geonameid`. Two real bugs motivated this over the previous
+ * two-call approach: (1) `/shabbat?start=...&end=...` silently ignores the
+ * requested range and only ever returns the single nearest Shabbat,
+ * regardless of how far out `end` is; (2) `geonameid` always resolves to a
+ * fixed city (Jerusalem), so every week after the nearest one was computed
+ * for the wrong location instead of the coordinates passed in. Querying
+ * `/hebcal` with `ss=on` + lat/long returns every Shabbat and holiday in the
+ * range, correctly localized, in one chronologically-ordered, already-merged
+ * list - which also means there's nothing left to de-duplicate.
+ */
+export declare function fetchWindows(latitude: number, longitude: number, options?: FetchWindowsOptions): Promise<Window[]>;
 /**
- * Fetches and merges Shabbat + major-holiday (Israel single-day Yom Tov mode)
- * windows for the next ~45 days from Hebcal's free public JSON API.
+ * Coalesces overlapping/touching windows into continuous ones. Needed when two
+ * independently-computed window lists are unioned (e.g. Israel's Shabbat and a
+ * foreign visitor's local Shabbat, which partially overlap): naively searching
+ * the concatenated list with {@link findActiveWindow} would return whichever
+ * matching window comes first and report *its* `end`, so a visitor sitting
+ * inside both windows could be told the site reopens at Israel's (earlier)
+ * havdalah while they're still blocked by their own later one. Merging first
+ * makes the reported reopen time the true end of the combined block.
+ *
+ * When two windows overlap, the merged window keeps the label of whichever one
+ * ends *later* - that's the occasion actually keeping the visitor blocked, and
+ * the one whose end time is shown.
  */
-export declare function fetchWindows(latitude: number, longitude: number): Promise<Window[]>;
+export declare function mergeWindows(windows: Window[]): Window[];
 /** Pure function: is `now` inside any of the given windows? */
 export declare function isBlocked(windows: Window[], now: number): boolean;
 /** Pure function: the window covering `now`, if any. */

package/dist/hebcal.js

@@ -1,26 +1,58 @@
-const HEBCAL_JERUSALEM_GEONAME_ID = 281184;
+/** Hebcal's own "candles"/"havdalah" items always carry the generic literal
+ *  "הדלקת נרות"/"הבדלה" in their `hebrew` field, never the occasion name - so
+ *  it's unusable as a display label on its own. For a plain Shabbat week
+ *  (no accompanying `holiday` item), fall back to this fixed pair instead. */
+export const SHABBAT_LABEL = 'שבת קודש';
+export const SHABBAT_CLOSING_LABEL = 'השבת';
 /**
  * Pairs candles/havdalah events into continuous windows. Multi-day holidays
  * (e.g. Rosh Hashana) emit two "candles" events but only one "havdalah" at the
  * very end, so candles cannot simply be paired 1:1 with the next havdalah.
  * Instead: open a window on the first candles seen while none is open, ignore
  * further candles while one is open, and close on the next havdalah.
+ *
+ * `defaults` overrides the label for windows that have no matching `holiday`
+ * item (i.e. plain Shabbat weeks) - pass it when calling this with a merged
+ * feed that mixes weekly Shabbat and holiday items together.
+ *
+ * Holiday windows pick up the matching `holiday` item's own Hebrew name (e.g.
+ * "ערב ראש השנה") by matching the opening `candles` item's `memo` field
+ * against a `holiday` item's `title` - not just "the most recent holiday item
+ * seen so far". Some `holiday`-category items (e.g. fast days like תשעה באב,
+ * which are `maj=on` but have no candle-lighting of their own) never get
+ * consumed by a window; naively tracking "last holiday label seen" would leak
+ * their label into the next, unrelated Shabbat window instead of falling back
+ * to `defaults`.
  */
-export function pairWindows(items) {
+export function pairWindows(items, defaults) {
     const windows = [];
+    const holidayTitles = new Map();
     let openStart = null;
     let openLabel = '';
+    let openClosingLabel = '';
     for (const item of items) {
+        if (item.category === 'holiday') {
+            holidayTitles.set(item.title, item.hebrew ?? item.title);
+        }
         if (item.category === 'candles') {
             if (openStart === null) {
                 openStart = new Date(item.date).getTime();
-                openLabel = item.hebrew ?? item.title;
+                const matchedHoliday = item.memo ? holidayTitles.get(item.memo) : undefined;
+                const label = matchedHoliday ?? defaults?.label ?? item.hebrew ?? item.title;
+                openLabel = label;
+                openClosingLabel = matchedHoliday ? label : (defaults?.closingLabel ?? label);
             }
         }
         else if (item.category === 'havdalah' && openStart !== null) {
-            windows.push({ start: openStart, end: new Date(item.date).getTime(), label: openLabel });
+            windows.push({
+                start: openStart,
+                end: new Date(item.date).getTime(),
+                label: openLabel,
+                closingLabel: openClosingLabel,
+            });
             openStart = null;
             openLabel = '';
+            openClosingLabel = '';
         }
     }
     return windows;
@@ -29,35 +61,78 @@ function toISODate(date) {
     return date.toISOString().slice(0, 10);
 }
 /**
- * Fetches and merges Shabbat + major-holiday (Israel single-day Yom Tov mode)
- * windows for the next ~45 days from Hebcal's free public JSON API.
+ * Fetches and merges Shabbat + major-holiday windows for the next ~45 days from
+ * Hebcal's free public JSON API. Defaults to Israel single-day Yom Tov mode at
+ * Jerusalem's timezone; pass `options` to compute windows for a visitor's own
+ * location/reckoning instead (see {@link FetchWindowsOptions}).
+ *
+ * Uses a *single* call to the `/hebcal` endpoint (not the separate `/shabbat`
+ * endpoint) with `ss=on` added, passing `latitude`/`longitude` directly
+ * instead of a `geonameid`. Two real bugs motivated this over the previous
+ * two-call approach: (1) `/shabbat?start=...&end=...` silently ignores the
+ * requested range and only ever returns the single nearest Shabbat,
+ * regardless of how far out `end` is; (2) `geonameid` always resolves to a
+ * fixed city (Jerusalem), so every week after the nearest one was computed
+ * for the wrong location instead of the coordinates passed in. Querying
+ * `/hebcal` with `ss=on` + lat/long returns every Shabbat and holiday in the
+ * range, correctly localized, in one chronologically-ordered, already-merged
+ * list - which also means there's nothing left to de-duplicate.
  */
-export async function fetchWindows(latitude, longitude) {
+export async function fetchWindows(latitude, longitude, options = {}) {
+    const israelMode = options.israelMode ?? true;
+    const tzid = options.tzid ?? 'Asia/Jerusalem';
     const start = new Date();
     const end = new Date(start.getTime() + 45 * 24 * 60 * 60 * 1000);
     const startParam = toISODate(start);
     const endParam = toISODate(end);
-    const shabbatUrl = `https://www.hebcal.com/shabbat?cfg=json&latitude=${latitude}&longitude=${longitude}` +
-        `&tzid=Asia/Jerusalem&M=on&start=${startParam}&end=${endParam}`;
-    // i=on = Israel single-day Yom Tov reckoning (not diaspora 2-day).
+    // i=on = Israel single-day Yom Tov reckoning; i=off = diaspora 2-day.
     // c=on = attach candles/havdalah entries to holidays, not just bare dates.
+    // ss=on = weekly Shabbat candle-lighting/havdalah, localized to lat/long.
     // maj=on + everything else off = only real work-restricted Yom Tov days.
-    const holidayUrl = `https://www.hebcal.com/hebcal?cfg=json&v=1&maj=on&min=off&mod=off&nx=off&mf=off&ss=off` +
-        `&c=on&i=on&geonameid=${HEBCAL_JERUSALEM_GEONAME_ID}&start=${startParam}&end=${endParam}`;
-    const [shabbatRes, holidayRes] = await Promise.all([fetch(shabbatUrl), fetch(holidayUrl)]);
-    if (!shabbatRes.ok || !holidayRes.ok) {
-        throw new Error(`hebcal fetch failed: shabbat=${shabbatRes.status} holiday=${holidayRes.status}`);
+    const iParam = israelMode ? 'on' : 'off';
+    const url = `https://www.hebcal.com/hebcal?cfg=json&v=1&maj=on&min=off&mod=off&nx=off&mf=off&ss=on` +
+        `&c=on&i=${iParam}&latitude=${latitude}&longitude=${longitude}&tzid=${encodeURIComponent(tzid)}` +
+        `&start=${startParam}&end=${endParam}`;
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`hebcal fetch failed: ${res.status}`);
     }
-    const [shabbatData, holidayData] = (await Promise.all([
-        shabbatRes.json(),
-        holidayRes.json(),
-    ]));
-    const windows = [
-        ...pairWindows(shabbatData.items ?? []),
-        ...pairWindows(holidayData.items ?? []),
-    ];
+    const data = (await res.json());
+    const windows = pairWindows(data.items ?? [], { label: SHABBAT_LABEL, closingLabel: SHABBAT_CLOSING_LABEL });
     return windows.sort((a, b) => a.start - b.start);
 }
+/**
+ * Coalesces overlapping/touching windows into continuous ones. Needed when two
+ * independently-computed window lists are unioned (e.g. Israel's Shabbat and a
+ * foreign visitor's local Shabbat, which partially overlap): naively searching
+ * the concatenated list with {@link findActiveWindow} would return whichever
+ * matching window comes first and report *its* `end`, so a visitor sitting
+ * inside both windows could be told the site reopens at Israel's (earlier)
+ * havdalah while they're still blocked by their own later one. Merging first
+ * makes the reported reopen time the true end of the combined block.
+ *
+ * When two windows overlap, the merged window keeps the label of whichever one
+ * ends *later* - that's the occasion actually keeping the visitor blocked, and
+ * the one whose end time is shown.
+ */
+export function mergeWindows(windows) {
+    const sorted = [...windows].sort((a, b) => a.start - b.start);
+    const merged = [];
+    for (const w of sorted) {
+        const last = merged[merged.length - 1];
+        if (last && w.start <= last.end) {
+            if (w.end > last.end) {
+                last.end = w.end;
+                last.label = w.label;
+                last.closingLabel = w.closingLabel;
+            }
+        }
+        else {
+            merged.push({ ...w });
+        }
+    }
+    return merged;
+}
 /** Pure function: is `now` inside any of the given windows? */
 export function isBlocked(windows, now) {
     return findActiveWindow(windows, now) !== undefined;

package/dist/holdingPage.d.ts

@@ -1,7 +1,15 @@
+import type { SecondaryMessage } from './translations.js';
+export type { SecondaryMessage } from './translations.js';
 export interface HoldingPageContext {
     siteName: string;
     reasonLabel: string;
+    closingLabel: string;
     untilLabel: string;
+    /** Optional localized message shown below the Hebrew one (with a blank-line
+     *  gap), for a visitor outside Israel, in their own browser language. Absent
+     *  for visitors in Israel, Hebrew-speaking visitors, or when the visitor's
+     *  location is unknown. */
+    secondary?: SecondaryMessage;
 }
 /** Simple, centered, mobile-responsive holding page. Inline CSS only, no external assets. */
 export declare function defaultRenderHoldingPage(ctx: HoldingPageContext): string;