@bygghammar/cms-platform 0.90.0-m7.9 → 0.91.0

package/src/config/site-config.ts

@@ -14,6 +14,8 @@ export type { SiteFeatureFlags } from "./modules";
 export { DEFAULT_FEATURE_FLAGS } from "./modules";
 import type { SiteFeatureFlags } from "./modules";
 import { CMS_MODULE_KEYS, DEFAULT_FEATURE_FLAGS } from "./modules";
+import { DEFAULT_TIMEZONE, isValidTimezone } from "../cms/timezone";
+import { EMPTY_TYPOGRAPHY, parseSiteTypography, type SiteTypography } from "./typography";
 
 /** Official company / contact details. Locale-neutral by design. */
 export type SiteCompany = {
@@ -87,6 +89,13 @@ export type SiteConfigInput = {
   backofficePath?: string;
   /** UI language of the backoffice itself. */
   backofficeLocale?: string;
+  /**
+   * IANA timezone the site's editors think in, e.g. "Europe/Stockholm".
+   *
+   * Scheduled content is stored in UTC and displayed in this zone, so a
+   * publish time typed as "10 Sep 18:00" means 18:00 where the site is run.
+   */
+  timezone?: string;
   company?: Partial<SiteCompany>;
   /** Logo artwork defaults; the backoffice may override these. */
   branding?: Partial<SiteBranding>;
@@ -104,7 +113,11 @@ export type SiteConfig = {
   defaultLocale: string;
   backofficePath: string;
   backofficeLocale: string;
+  /** IANA timezone used to display and enter scheduled times. */
+  timezone: string;
   company: SiteCompany;
+  /** Menu and footer typography. Defaults keep the theme fonts. */
+  typography: SiteTypography;
   branding: SiteBranding;
   brand: SiteBrandTokens;
   features: SiteFeatureFlags;
@@ -130,6 +143,8 @@ export function defineSiteConfig(input: SiteConfigInput): SiteConfig {
   if (!backofficePath.startsWith("/") || backofficePath.endsWith("/")) {
     fail(`backofficePath "${backofficePath}" must start with "/" and not end with one`);
   }
+  const timezone = input.timezone?.trim() || DEFAULT_TIMEZONE;
+  if (!isValidTimezone(timezone)) fail(`timezone "${timezone}" is not a known IANA timezone`);
   return {
     key: input.key,
     name: input.name.trim(),
@@ -138,7 +153,9 @@ export function defineSiteConfig(input: SiteConfigInput): SiteConfig {
     defaultLocale: input.defaultLocale,
     backofficePath,
     backofficeLocale: input.backofficeLocale ?? "en",
+    timezone,
     company: { ...EMPTY_COMPANY, ...(input.company ?? {}) },
+    typography: EMPTY_TYPOGRAPHY,
     branding: { ...EMPTY_BRANDING, ...(input.branding ?? {}) },
     brand: { ...(input.brand ?? {}) },
     features: { ...DEFAULT_FEATURE_FLAGS, ...(input.features ?? {}) },
@@ -179,6 +196,7 @@ export const OVERRIDABLE_SETTING_KEYS = [
   "branding",
   "brand",
   "features",
+  "typography",
 ] as const satisfies readonly (keyof SiteConfig)[];
 
 export type OverridableSettingKey = (typeof OVERRIDABLE_SETTING_KEYS)[number];
@@ -190,6 +208,7 @@ export type SiteSettingOverrides = Partial<{
   branding: Partial<SiteBranding>;
   brand: SiteBrandTokens;
   features: Partial<SiteFeatureFlags>;
+  typography: SiteTypography;
 }>;
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -238,6 +257,7 @@ export function parseSiteSettingOverrides(raw: unknown): SiteSettingOverrides {
     }
     out.features = features;
   }
+  if (isRecord(raw["typography"])) out.typography = parseSiteTypography(raw["typography"]);
   return out;
 }
 
@@ -251,6 +271,7 @@ export function resolveSiteConfig(base: SiteConfig, overrides: unknown): SiteCon
     branding: { ...base.branding, ...(parsed.branding ?? {}) },
     brand: { ...base.brand, ...(parsed.brand ?? {}) },
     features: { ...base.features, ...(parsed.features ?? {}) },
+    typography: { ...base.typography, ...(parsed.typography ?? {}) },
   };
 }
 
@@ -273,6 +294,17 @@ export function registerSiteConfig(config: SiteConfig): SiteConfig {
   return config;
 }
 
+/**
+ * The site's timezone, or the platform default when no config is registered.
+ *
+ * Scheduling controls need a zone but must not be the thing that crashes a
+ * screen: an unregistered config is a startup bug, not a reason for a date
+ * field to throw while an editor is typing in it.
+ */
+export function siteTimezone(): string {
+  return active?.timezone || DEFAULT_TIMEZONE;
+}
+
 /** Read the registered site config. Throws when a site forgot to register. */
 export function siteConfig(): SiteConfig {
   if (!active) {

package/src/config/typography.ts

@@ -0,0 +1,143 @@
+/**
+ * Menu and footer typography.
+ *
+ * Two independent choices — the top menu and the footer — each either keep the
+ * site's theme font (the default, and what every existing site already renders)
+ * or name a Google font family.
+ *
+ * Backwards compatibility is the point of the `"theme"` source: a site with no
+ * stored typography, or with a half-filled row, resolves to *no* font-family
+ * declaration at all, so the menu and footer keep inheriting exactly the fonts
+ * they inherit today. Upgrading changes nothing until an editor chooses a font.
+ */
+
+/** Where a font comes from. `theme` means "leave the theme alone". */
+export type FontSource = "theme" | "google";
+
+/** Theme font tokens from `theme.css`, used as the fallback stack. */
+export type ThemeFontToken = "sans" | "serif";
+
+export type FontChoice = {
+  /** Defaults to `"theme"` — anything unrecognised is treated as `"theme"`. */
+  source?: FontSource;
+  /** Google font family, e.g. "DM Serif Display". Required when source is google. */
+  family?: string;
+  /** Weights to request. Defaults to 400 and 700. */
+  weights?: number[];
+  /** Theme token appended as the fallback stack behind a Google family. */
+  fallback?: ThemeFontToken;
+};
+
+export type TypographySlot = "menu" | "footer";
+
+/** Slots a site can restyle, and the theme token each one falls back to. */
+export const TYPOGRAPHY_SLOTS: Record<TypographySlot, { label: string; fallback: ThemeFontToken }> =
+  {
+    menu: { label: "Menu", fallback: "sans" },
+    footer: { label: "Footer", fallback: "serif" },
+  };
+
+export type SiteTypography = Partial<Record<TypographySlot, FontChoice>>;
+
+/** No overrides: every slot keeps the theme font. */
+export const EMPTY_TYPOGRAPHY: SiteTypography = {};
+
+/** The choice a slot starts from — explicitly "whatever the theme already does". */
+export const THEME_FONT_CHOICE: FontChoice = { source: "theme" };
+
+/** Weights requested when a font choice does not name any. */
+export const DEFAULT_FONT_WEIGHTS = [400, 700] as const;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * A Google family name safe to put in a stylesheet URL and a CSS declaration.
+ * Letters, digits, spaces and a few punctuation marks only — no quotes, no
+ * semicolons, nothing that could break out of the `font-family` value.
+ */
+export function sanitizeFontFamily(raw: unknown): string {
+  if (typeof raw !== "string") return "";
+  return raw
+    .replace(/[^A-Za-z0-9 +\-_]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 60);
+}
+
+function sanitizeWeights(raw: unknown): number[] | undefined {
+  if (!Array.isArray(raw)) return undefined;
+  const weights = Array.from(
+    new Set(
+      raw
+        .map((w) => (typeof w === "number" ? w : Number.parseInt(String(w), 10)))
+        .filter((w) => Number.isFinite(w) && w >= 100 && w <= 900 && w % 100 === 0),
+    ),
+  ).sort((a, b) => a - b);
+  return weights.length ? weights : undefined;
+}
+
+/** Narrow one untrusted font choice. Anything unusable becomes the theme font. */
+export function parseFontChoice(raw: unknown): FontChoice {
+  if (!isRecord(raw)) return { ...THEME_FONT_CHOICE };
+  const family = sanitizeFontFamily(raw["family"]);
+  const source: FontSource = raw["source"] === "google" && family ? "google" : "theme";
+  const out: FontChoice = { source };
+  if (family) out.family = family;
+  const weights = sanitizeWeights(raw["weights"]);
+  if (weights) out.weights = weights;
+  if (raw["fallback"] === "sans" || raw["fallback"] === "serif") {
+    out.fallback = raw["fallback"];
+  }
+  return out;
+}
+
+/** Narrow an untrusted typography payload from `site_settings`. */
+export function parseSiteTypography(raw: unknown): SiteTypography {
+  if (!isRecord(raw)) return {};
+  const out: SiteTypography = {};
+  for (const slot of Object.keys(TYPOGRAPHY_SLOTS) as TypographySlot[]) {
+    if (raw[slot] !== undefined) out[slot] = parseFontChoice(raw[slot]);
+  }
+  return out;
+}
+
+export type ResolvedFont = {
+  /**
+   * The `font-family` value to apply, or `undefined` when the theme font should
+   * be left exactly as it is. `undefined` is the backwards-compatible answer.
+   */
+  fontFamily?: string;
+  /** Google family to load, when one is configured. */
+  googleFamily?: string;
+  /** Weights to load with it. */
+  weights: number[];
+};
+
+/** Resolve one slot's choice into what the renderer and the loader need. */
+export function resolveFontChoice(
+  choice: FontChoice | null | undefined,
+  slot: TypographySlot,
+): ResolvedFont {
+  const weights = [...DEFAULT_FONT_WEIGHTS];
+  if (!choice || choice.source !== "google") return { weights };
+  const family = sanitizeFontFamily(choice.family);
+  if (!family) return { weights };
+  const fallback = choice.fallback ?? TYPOGRAPHY_SLOTS[slot].fallback;
+  return {
+    fontFamily: `"${family}", var(--font-${fallback})`,
+    googleFamily: family,
+    weights: choice.weights?.length ? [...choice.weights] : weights,
+  };
+}
+
+export type ResolvedTypography = Record<TypographySlot, ResolvedFont>;
+
+/** Resolve every slot at once. */
+export function resolveTypography(typography: SiteTypography | undefined): ResolvedTypography {
+  return {
+    menu: resolveFontChoice(typography?.menu, "menu"),
+    footer: resolveFontChoice(typography?.footer, "footer"),
+  };
+}

package/src/http/cache-policy.ts

@@ -62,6 +62,44 @@ export function isVersionedMediaUrl(search: string | URLSearchParams): boolean {
   return typeof token === "string" && token.length > 0;
 }
 
+/** Sitemaps and feeds: generated from data that changes on a schedule. */
+export function isFeedPath(pathname: string): boolean {
+  return /^\/sitemap.*\.xml$/.test(pathname) || pathname === "/rss.xml";
+}
+
+/** The longest a feed is cached when nothing at all is scheduled to change. */
+const FEED_MAX_AGE = 3600;
+
+/** Still cacheable, but every hit revalidates — an ETag turns that into a 304. */
+const FEED_REVALIDATE: CachePolicy = {
+  cacheControl: "public, max-age=0, must-revalidate",
+  expiresSeconds: 0,
+  kind: "feed",
+};
+
+/**
+ * Caching for one sitemap or feed response, capped by the next publication
+ * boundary.
+ *
+ * `revalidateAt` is the instant the body stops being true — the earliest
+ * `publish_at` still to come or `unpublish_at` still to pass across every page
+ * in it, which `listPublishedRoutesCore` hands back with the keys. A cache may
+ * shorten that but never outlive it: a scheduled page missing from the sitemap
+ * for an hour after it went live is the same defect as publishing it an hour
+ * late. Null means nothing is scheduled, so the ordinary hour applies; a
+ * boundary already reached means revalidate now.
+ */
+export function feedCachePolicy(
+  revalidateAt?: number | null,
+  now: number = Date.now(),
+): CachePolicy {
+  const budget =
+    revalidateAt == null ? FEED_MAX_AGE : Math.floor((revalidateAt - now) / 1000);
+  const maxAge = Math.max(0, Math.min(FEED_MAX_AGE, budget));
+  if (maxAge <= 0) return { ...FEED_REVALIDATE };
+  return { cacheControl: `public, max-age=${maxAge}`, expiresSeconds: maxAge, kind: "feed" };
+}
+
 /** Resolve the caching policy for one request path (+ query string). */
 export function cachePolicyFor(pathname: string, search = ""): CachePolicy {
   if (NO_STORE_PREFIXES.some((p) => pathname === p || pathname.startsWith(p))) {
@@ -95,8 +133,17 @@ export function cachePolicyFor(pathname: string, search = ""): CachePolicy {
     };
   }
 
-  if (/^\/sitemap.*\.xml$/.test(pathname) || pathname === "/rss.xml") {
-    return { cacheControl: "public, max-age=3600", expiresSeconds: 3600, kind: "feed" };
+  if (isFeedPath(pathname)) {
+    /*
+     * Deliberately not an hour. A sitemap is generated from publication
+     * windows, so its contents change on a schedule: an hour of caching can
+     * keep a page that went live at noon out of the sitemap until one, and keep
+     * a page that expired at noon in it just as long. The path alone cannot say
+     * when the next boundary is — only the handler that read the publications
+     * knows that, and it says so by calling `feedCachePolicy`. Everything else
+     * revalidates, which still costs one cheap 304 rather than a full body.
+     */
+    return { ...FEED_REVALIDATE };
   }
 
   // Dynamic, server-rendered HTML: always revalidate, never immutable.

package/src/media/folders.ts

@@ -0,0 +1,183 @@
+/**
+ * Media folders.
+ *
+ * Storage paths are plain `folder/name.ext` strings — no new table, no new
+ * storage API. Uploads default into a `YYYY-MM` folder so the bucket root does
+ * not grow without bound; a batch may instead be pinned to a named folder such
+ * as `2027-01-Cruice_1_Gallery`.
+ *
+ * Existing files keep their existing paths: nothing here moves or rewrites
+ * anything already uploaded, and `mediaUrl()` has always accepted a prefixed
+ * path, so old URLs keep resolving byte for byte.
+ */
+
+import { instantToZonedLocal } from "../cms/timezone";
+
+/** Folders are shallow on purpose — deep trees make the browser unusable. */
+export const MEDIA_FOLDER_MAX_SEGMENTS = 3;
+export const MEDIA_FOLDER_MAX_SEGMENT_LENGTH = 64;
+export const MEDIA_FOLDER_MAX_LENGTH = 160;
+
+/** How a batch decides where its files land. */
+export type MediaFolderMode = "auto" | "custom";
+
+/** Thrown for folder input that cannot be made safe. */
+export class MediaFolderError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "MediaFolderError";
+  }
+}
+
+/**
+ * The automatic folder for an upload: `YYYY-MM` in the site timezone, so a
+ * batch uploaded at 00:30 on the first of the month lands where the editor
+ * expects it rather than in the previous month's UTC folder.
+ */
+export function monthFolder(now: Date | number = Date.now(), timezone?: string | null): string {
+  const instant = typeof now === "number" ? now : now.getTime();
+  if (!Number.isFinite(instant)) return "unknown";
+  return instantToZonedLocal(instant, timezone).slice(0, 7);
+}
+
+/** True for a `YYYY-MM` folder — the ones the library groups by date. */
+export function isMonthFolder(folder: string): boolean {
+  return /^\d{4}-(?:0[1-9]|1[0-2])$/.test(folder);
+}
+
+/**
+ * One path segment, made safe for any object store.
+ *
+ * Case is preserved (`Cruice_1_Gallery` stays readable) but everything that
+ * could escape the bucket or confuse a storage backend is removed: separators,
+ * control characters, leading/trailing dots and whitespace, and the `.`/`..`
+ * segments that path traversal relies on. Returns `""` when nothing usable is
+ * left, which callers treat as invalid rather than as "the bucket root".
+ */
+export function sanitizeFolderSegment(input: string): string {
+  const cleaned = input
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    // Whitespace becomes a separator before the remaining control characters
+    // are dropped, so a pasted line break separates words instead of gluing
+    // them together.
+    .replace(/\s+/g, "-")
+    .replace(/[\u0000-\u001f\u007f]/g, "")
+    .replace(/[^A-Za-z0-9._-]/g, "-")
+    .replace(/-{2,}/g, "-")
+    .replace(/^[.\-]+/, "")
+    .replace(/[.\-]+$/, "")
+    .slice(0, MEDIA_FOLDER_MAX_SEGMENT_LENGTH);
+  if (cleaned === "." || cleaned === "..") return "";
+  return cleaned;
+}
+
+/**
+ * Sanitize a whole folder path. Returns `""` when the input is empty or has no
+ * usable segment left — callers decide whether that means "use the automatic
+ * folder" or "reject". Never returns a leading `/`, a `..` segment, a drive
+ * letter, a protocol, or more than {@link MEDIA_FOLDER_MAX_SEGMENTS} levels.
+ */
+export function sanitizeMediaFolder(input: string | null | undefined): string {
+  if (typeof input !== "string") return "";
+  const segments = input
+    .replace(/\\/g, "/")
+    .split("/")
+    .map(sanitizeFolderSegment)
+    .filter(Boolean)
+    .slice(0, MEDIA_FOLDER_MAX_SEGMENTS);
+  return segments.join("/").slice(0, MEDIA_FOLDER_MAX_LENGTH).replace(/\/+$/, "");
+}
+
+/**
+ * Sanitize a folder the editor typed, refusing input that cannot be honoured.
+ * Silently uploading somewhere other than the folder that was asked for is
+ * worse than an error message.
+ */
+export function assertMediaFolder(input: string | null | undefined): string {
+  const raw = typeof input === "string" ? input.trim() : "";
+  if (!raw) return "";
+  // A `..` is refused rather than rewritten. "../../gallery" sanitizes to the
+  // perfectly safe folder "gallery", but uploading there is not what was asked
+  // for, and a traversal attempt deserves an answer rather than a shrug.
+  if (/(?:^|\/)\.\.(?:\/|$)/.test(raw.replace(/\\/g, "/"))) {
+    throw new MediaFolderError(
+      `"${raw}" is not a usable folder name: a folder path cannot contain "..".`,
+    );
+  }
+  const safe = sanitizeMediaFolder(raw);
+  if (!safe) {
+    throw new MediaFolderError(
+      `"${raw}" is not a usable folder name. Use letters, numbers, dashes, dots or underscores.`,
+    );
+  }
+  return safe;
+}
+
+/** Everything before the last `/`, or `""` for a file at the bucket root. */
+export function mediaFolderOf(path: string): string {
+  const at = path.lastIndexOf("/");
+  return at === -1 ? "" : path.slice(0, at);
+}
+
+/** Everything after the last `/`. */
+export function mediaBaseName(path: string): string {
+  const at = path.lastIndexOf("/");
+  return at === -1 ? path : path.slice(at + 1);
+}
+
+/** Join an already sanitized folder and a file name into a storage path. */
+export function joinMediaPath(folder: string, name: string): string {
+  const dir = folder.replace(/^\/+|\/+$/g, "");
+  const file = name.replace(/^\/+/, "");
+  return dir ? `${dir}/${file}` : file;
+}
+
+/** Label for the folder pickers — the root has to be called something. */
+export const ROOT_FOLDER_LABEL = "Library root";
+
+export function folderLabel(folder: string): string {
+  return folder === "" ? ROOT_FOLDER_LABEL : folder;
+}
+
+export type MediaFolderSummary = {
+  /** `""` for the bucket root. */
+  folder: string;
+  label: string;
+  count: number;
+};
+
+/**
+ * Folder list for the browser: month folders newest first, then named folders
+ * alphabetically, then the root. Cheap enough to run on every render — one
+ * pass over paths the host already loaded.
+ */
+export function summarizeMediaFolders(paths: Iterable<string>): MediaFolderSummary[] {
+  const counts = new Map<string, number>();
+  for (const path of paths) {
+    const folder = mediaFolderOf(path);
+    counts.set(folder, (counts.get(folder) ?? 0) + 1);
+  }
+  return [...counts.entries()]
+    .map(([folder, count]) => ({ folder, label: folderLabel(folder), count }))
+    .sort((a, b) => {
+      if (a.folder === b.folder) return 0;
+      if (a.folder === "") return 1;
+      if (b.folder === "") return -1;
+      const aMonth = isMonthFolder(a.folder);
+      const bMonth = isMonthFolder(b.folder);
+      if (aMonth !== bMonth) return aMonth ? -1 : 1;
+      return aMonth ? b.folder.localeCompare(a.folder) : a.folder.localeCompare(b.folder);
+    });
+}
+
+/** True when `path` sits in `folder` itself, not in one of its subfolders. */
+export function isInFolder(path: string, folder: string): boolean {
+  return mediaFolderOf(path) === folder;
+}
+
+/** True when `path` sits in `folder` or anywhere below it. */
+export function isUnderFolder(path: string, folder: string): boolean {
+  if (folder === "") return true;
+  return path === folder || path.startsWith(`${folder}/`);
+}

package/src/media/use-media-upload.ts

@@ -4,6 +4,7 @@ import { useQueryClient } from "@tanstack/react-query";
 import { optimizeForUpload } from "./optimize";
 import { pickVideoPoster } from "./pick-video-poster";
 import { cleanFileName, splitExt, uniqueFileName } from "./filename";
+import { mediaBaseName } from "./folders";
 
 export type UploadProgress = { label: string; percent: number } | null;
 
@@ -14,9 +15,15 @@ export type UploadExistingItem = { name: string };
 export type UploadBundleFn = (input: {
   data: {
     files: Array<{ name: string; contentType: string; bytes: number[] }>;
+    /** Destination folder; omitted means the automatic `YYYY-MM` folder. */
+    folder?: string;
+    timezone?: string;
   };
 }) => Promise<{ urls: string[] }>;
 
+/** Where a batch should land. Omitted folder = the automatic month folder. */
+export type UploadOptions = { folder?: string; timezone?: string };
+
 /**
  * Shared browser-side media upload (optimize → storage → cache invalidate)
  * with a coarse percentage so callers can render a progress bar.
@@ -26,6 +33,7 @@ export type UploadBundleFn = (input: {
 export function useMediaUploadWith(
   uploadBundle: UploadBundleFn,
   existing: UploadExistingItem[] = [],
+  options: UploadOptions = {},
 ) {
   const queryClient = useQueryClient();
   const [progress, setProgress] = useState<UploadProgress>(null);
@@ -37,10 +45,13 @@ export function useMediaUploadWith(
       if (!arr.length) return [];
       setUploading(true);
       const urls: string[] = [];
+      // File names are compared without their folder: the same name in two
+      // folders is fine, and the server de-duplicates within the destination.
       const taken = new Set<string>(
         existing.flatMap((i) => {
-          const { base } = splitExt(i.name);
-          return [i.name, base, base.replace(/-(?:480|768|1200|1920)$/, "")];
+          const name = mediaBaseName(i.name);
+          const { base } = splitExt(name);
+          return [name, base, base.replace(/-(?:480|768|1200|1920)$/, "")];
         }),
       );
       try {
@@ -72,7 +83,13 @@ export function useMediaUploadWith(
               bytes: Array.from(new Uint8Array(await part.blob.arrayBuffer())),
             })),
           );
-          const { urls: uploaded } = await uploadBundle({ data: { files: payload } });
+          const { urls: uploaded } = await uploadBundle({
+            data: {
+              files: payload,
+              ...(options.folder ? { folder: options.folder } : {}),
+              ...(options.timezone ? { timezone: options.timezone } : {}),
+            },
+          });
           urls.push(uploaded[0]!);
           step(1, "Uploading");
         }
@@ -83,7 +100,7 @@ export function useMediaUploadWith(
         setProgress(null);
       }
     },
-    [existing, queryClient, uploadBundle],
+    [existing, options.folder, options.timezone, queryClient, uploadBundle],
   );
 
   return { upload, uploading, progress };

package/src/navigation/index.ts

@@ -1,6 +1,7 @@
 import type { ComponentType } from "react";
 
 import { hasText, resolvedHref } from "../blocks/optional-content";
+import { isVisibleAt, type VisibilitySchedule } from "../cms/visibility-schedule";
 import type { Locale } from "../i18n/locales";
 import type { LocalizedString } from "../i18n/types";
 
@@ -8,6 +9,11 @@ export type NavigationItem = {
   label: LocalizedString;
   href: string;
   children?: NavigationItem[];
+  /**
+   * Optional visibility window. Absent means "always visible", so every menu
+   * written before scheduling existed behaves exactly as it did.
+   */
+  schedule?: VisibilitySchedule;
 };
 
 export type BackofficeNavigationItem<TIconProps = { className?: string }> = {
@@ -52,19 +58,45 @@ export function navigationPanelId(href: string): string {
  * only in Swedish still shows in English through the usual fallback, while one
  * deliberately blanked for English is absent there.
  *
+ * An entry may also carry a visibility window (`schedule`). Outside that window
+ * it is dropped here, which is the only place menu visibility is decided — so a
+ * hidden entry is absent from the desktop bar, the mobile panel and any other
+ * consumer at the same instant. `now` is a parameter rather than a call to
+ * `Date.now()` inside, so callers control the clock and every boundary is
+ * testable; a caller that renders over time re-renders on the next boundary
+ * (see `useScheduleClock`) rather than trusting a cached list.
+ *
  * Order is preserved exactly, so what the editor arranged is what renders.
  */
 export function renderableNavigation(
   items: readonly NavigationItem[] | undefined,
   locale: Locale,
+  now: number | Date = Date.now(),
 ): NavigationItem[] {
   return (items ?? [])
-    .filter((item) => hasText(item.label, locale) && resolvedHref(item.href) !== "")
+    .filter(
+      (item) =>
+        hasText(item.label, locale) &&
+        resolvedHref(item.href) !== "" &&
+        isVisibleAt(item.schedule, now),
+    )
     .map((item) => {
       const href = resolvedHref(item.href);
-      const children = renderableNavigation(item.children, locale);
+      const children = renderableNavigation(item.children, locale, now);
       return children.length > 0
         ? { ...item, href, children }
         : { ...item, href, children: undefined };
     });
 }
+
+/** Every schedule in a navigation tree, for cache and re-render planning. */
+export function navigationSchedules(
+  items: readonly NavigationItem[] | undefined,
+): VisibilitySchedule[] {
+  const out: VisibilitySchedule[] = [];
+  for (const item of items ?? []) {
+    if (item.schedule) out.push(item.schedule);
+    out.push(...navigationSchedules(item.children));
+  }
+  return out;
+}