npm - @tokenoftrust/storefront-runner - Versions diffs - 0.1.0 - Mend

@tokenoftrust/storefront-runner 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (337) hide show

package/apps/storefront/src/lib/storyblok/provider.ts ADDED Viewed

@@ -0,0 +1,524 @@
+/**
+ * ContentProvider — the Storyblok seam (brief §7 CMS).
+ *
+ * Two implementations behind one interface:
+ *   - StoryblokContentProvider — calls the Storyblok delivery API for a tenant's
+ *     child space, maps stories -> our content model.
+ *   - LocalContentProvider     — reads src/content/pilot/*.json, so the site
+ *     renders fully OFFLINE with no Storyblok token.
+ *
+ * Selection: if the tenant has a usable delivery token AND the Storyblok client
+ * is configured, use Storyblok; otherwise fall back to local. Phase 1 ships with
+ * a placeholder token, so the LOCAL provider is what actually renders. The
+ * mapping layer is the documented swap point — Storyblok story JSON shares the
+ * same `component` discriminators as our blocks, so the parent-space schemas map
+ * 1:1. See DECISIONS.md.
+ */
+import type {
+  EditorialPage,
+  HomeContent,
+  SiteChrome,
+} from "./content-model.js";
+import type { CustomizationEnv, KvGet, TenantConfig } from "@tot/public-runtime";
+import { contentArtifactPath, readPublishedArtifact } from "@tot/public-runtime";
+export interface ContentProvider {
+  getHome(): Promise<HomeContent>;
+  /**
+   * A marketing tenant's self-authored home document (raw HTML), or null. When
+   * present the homepage route serves it VERBATIM (bypassing the block Layout) —
+   * the "vendor injects their own HTML" path. Full `<!doctype html>` document;
+   * the route nonces its inline <style>/<script> so it still satisfies CSP.
+   */
+  getHomeHtml(): Promise<string | null>;
+  /**
+   * A marketing tenant's self-authored SUBPAGE document (raw HTML) for `slug`,
+   * or null. Same verbatim-serve path as getHomeHtml — the catch-all route
+   * (`[...slug].astro`) serves it bypassing the block Layout and nonces its
+   * inline tags. Files live at `content/<tenant>/pages-html/<slug>.html`.
+   */
+  getPageHtml(slug: string): Promise<string | null>;
+  /** Slugs of this tenant's raw subpages (for the sitemap). */
+  listPageHtmlSlugs(): Promise<string[]>;
+  /**
+   * The tenant's shared-chrome WRAPPER document (raw HTML), or null. A full
+   * document containing the CHROME_BODY_MARKER where a body-only page fragment is
+   * spliced in (see lib/rawMarketingHtml.ts). Lets raw pages stop duplicating
+   * chrome: chrome lives once here, pages become fragments. File:
+   * `content/<tenant>/chrome.html`. Tenant-owned (no cross-tenant fallback).
+   */
+  getChromeHtml(): Promise<string | null>;
+  getChrome(): Promise<SiteChrome>;
+  getPage(slug: string): Promise<EditorialPage | null>;
+  listPages(): Promise<EditorialPage[]>;
+}
+// ---------------------------------------------------------------------------
+// LocalContentProvider — static JSON bundled at build time.
+// ---------------------------------------------------------------------------
+// Per-tenant local content lives under the colocated repo-root layout
+// tenants/<tenant_id>/content/. Vite globs bundle every tenant's JSON at build
+// time; a file missing for a tenant falls back to the default scope, so a
+// partially-adopted tenant still renders. Depth: from src/lib/storyblok/ the
+// repo root is five levels up (storyblok→lib→src→storefront→apps→root).
+const homeGlobs = import.meta.glob<HomeContent>("../../../../../tenants/*/content/home.json", {
+  import: "default",
+});
+const chromeGlobs = import.meta.glob<SiteChrome>("../../../../../tenants/*/content/chrome.json", {
+  import: "default",
+});
+const pageGlobs = import.meta.glob<EditorialPage>("../../../../../tenants/*/content/pages/*.json", {
+  import: "default",
+});
+// Raw self-authored home documents (marketing tenants). `?raw` bundles the file
+// as a string; a tenant with no home.html simply has no entry here.
+const homeHtmlGlobs = import.meta.glob<string>("../../../../../tenants/*/content/home.html", {
+  query: "?raw",
+  import: "default",
+});
+// Raw self-authored SUBPAGE documents: tenants/<tenant>/content/pages-html/<slug>.html
+// (e.g. pages-html/pricing.html -> /pricing/). `**` supports nested slugs.
+const pageHtmlGlobs = import.meta.glob<string>("../../../../../tenants/*/content/pages-html/**/*.html", {
+  query: "?raw",
+  import: "default",
+});
+// Shared-chrome wrapper document (marketing tenants that author body-only page
+// fragments). One per tenant; a tenant without it keeps serving full documents.
+const chromeHtmlGlobs = import.meta.glob<string>("../../../../../tenants/*/content/chrome.html", {
+  query: "?raw",
+  import: "default",
+});
+const DEFAULT_SCOPE = "home";
+function pickContent<T>(
+  globs: Record<string, () => Promise<T>>,
+  scope: string,
+): (() => Promise<T>) | null {
+  const seg = `/tenants/${scope}/content/`;
+  const key = Object.keys(globs).find((k) => k.includes(seg));
+  return (key ? globs[key] : null) ?? null;
+}
+function pickPages(scope: string): Array<() => Promise<EditorialPage>> {
+  const seg = `/tenants/${scope}/content/pages/`;
+  return Object.keys(pageGlobs)
+    .filter((k) => k.includes(seg))
+    .map((k) => pageGlobs[k]!);
+}
+/** Normalize a route slug to the file stem: strip surrounding slashes + .html. */
+function normalizeRawPageSlug(slug: string): string {
+  return slug.replace(/^\/+|\/+$/g, "").replace(/\.html$/i, "");
+}
+/** The subpage slug a glob key encodes for `scope`, or null if it's not one. */
+function rawPageSlugForKey(scope: string, key: string): string | null {
+  const seg = `/tenants/${scope}/content/pages-html/`;
+  const start = key.indexOf(seg);
+  if (start < 0 || !key.endsWith(".html")) return null;
+  return key.slice(start + seg.length, -".html".length);
+}
+function pickPageHtml(scope: string, slug: string): (() => Promise<string>) | null {
+  const wanted = normalizeRawPageSlug(slug);
+  if (!wanted) return null;
+  const key = Object.keys(pageHtmlGlobs).find(
+    (k) => rawPageSlugForKey(scope, k) === wanted,
+  );
+  return key ? pageHtmlGlobs[key]! : null;
+}
+/**
+ * DEV hot-reload for raw tenant HTML. The `?raw` import.meta.glob above bundles
+ * each file's contents at server boot, so an edit to tenants/<id>/content/*.html
+ * would NOT preview until a full rebuild — the "magic on save" gap. In dev we read
+ * the file from disk at REQUEST time instead, so an edit shows on the next request.
+ *
+ * Prod: import.meta.env.DEV is statically false, so this whole branch tree-shakes
+ * out and the bundled glob is used — node:fs never enters the Worker. If fs is
+ * unavailable (e.g. the workerd dev runtime) or the file is missing, we return null
+ * and the caller falls back to the glob, so behavior is never worse than before.
+ */
+async function readRawDevFile(scope: string, relative: string): Promise<string | null> {
+  if (!import.meta.env.DEV) return null;
+  try {
+    const [{ readFile }, { fileURLToPath }, { resolve, dirname }] = await Promise.all([
+      import("node:fs/promises"),
+      import("node:url"),
+      import("node:path"),
+    ]);
+    // provider.ts lives at apps/storefront/src/lib/storyblok/ — the repo root is five
+    // levels up, mirroring the import.meta.glob prefix ("../../../../../tenants/...").
+    const here = dirname(fileURLToPath(import.meta.url));
+    const abs = resolve(here, "../../../../..", "tenants", scope, "content", relative);
+    return await readFile(abs, "utf8");
+  } catch {
+    return null;
+  }
+}
+export class LocalContentProvider implements ContentProvider {
+  constructor(private readonly scope: string = DEFAULT_SCOPE) {}
+  async getHome(): Promise<HomeContent> {
+    const loader = pickContent(homeGlobs, this.scope) ?? pickContent(homeGlobs, DEFAULT_SCOPE);
+    if (!loader) throw new Error("no home content");
+    return loader();
+  }
+  async getHomeHtml(): Promise<string | null> {
+    // DEV: serve fresh from disk so an edit previews on save (see readRawDevFile).
+    const dev = await readRawDevFile(this.scope, "home.html");
+    if (dev !== null) return dev;
+    // Tenant-owned only (no cross-tenant fallback): a raw home document is a
+    // whole-page identity, never inherited from the default scope.
+    const loader = pickContent(homeHtmlGlobs, this.scope);
+    return loader ? loader() : null;
+  }
+  async getPageHtml(slug: string): Promise<string | null> {
+    // DEV: serve fresh from disk so a subpage edit previews on save.
+    const dev = await readRawDevFile(this.scope, `pages-html/${normalizeRawPageSlug(slug)}.html`);
+    if (dev !== null) return dev;
+    // Tenant-owned only, like getHomeHtml — raw subpages are whole-page identity.
+    const loader = pickPageHtml(this.scope, slug);
+    return loader ? loader() : null;
+  }
+  async listPageHtmlSlugs(): Promise<string[]> {
+    return Object.keys(pageHtmlGlobs)
+      .map((k) => rawPageSlugForKey(this.scope, k))
+      .filter((slug): slug is string => !!slug)
+      .sort((a, b) => a.localeCompare(b));
+  }
+  async getChromeHtml(): Promise<string | null> {
+    // DEV: serve fresh from disk so a chrome edit previews on save.
+    const dev = await readRawDevFile(this.scope, "chrome.html");
+    if (dev !== null) return dev;
+    // Tenant-owned only (no cross-tenant fallback) — chrome is whole-page identity.
+    const loader = pickContent(chromeHtmlGlobs, this.scope);
+    return loader ? loader() : null;
+  }
+  async getChrome(): Promise<SiteChrome> {
+    const defL = pickContent(chromeGlobs, DEFAULT_SCOPE);
+    const def: SiteChrome = defL
+      ? await defL()
+      : { nav: [], footer: { columns: [], social: [] } };
+    const ownL = pickContent(chromeGlobs, this.scope);
+    if (!ownL) return def;
+    const c = await ownL();
+    if (this.scope === DEFAULT_SCOPE) return c;
+    // Per-field fallback fills only STRUCTURAL scaffolding (nav/footer) so a
+    // partially-adopted tenant still renders. Promotional/identity/legal fields
+    // (announcement, headerCtas, disclaimers) are tenant-OWNED and never inherit
+    // from the default scope — otherwise e.g. a marketing tenant would show the
+    // default store's shipping banner or nicotine disclaimers.
+    return {
+      nav: c.nav?.length ? c.nav : def.nav,
+      footer:
+        c.footer && (c.footer.columns?.length || c.footer.social?.length)
+          ? c.footer
+          : def.footer,
+      headerCtas: c.headerCtas,
+      announcement: c.announcement,
+      disclaimer: c.disclaimer,
+      disclaimers: c.disclaimers,
+    };
+  }
+  async getPage(slug: string): Promise<EditorialPage | null> {
+    return (await this.listPages()).find((p) => p.slug === slug) ?? null;
+  }
+  async listPages(): Promise<EditorialPage[]> {
+    // Editorial pages are NOT cross-tenant: a distinct tenant with no pages of
+    // its own returns none rather than inheriting the default scope's pages.
+    // (Serving e.g. pilot's privacy/legal copy under another brand would be a
+    // content/compliance leak; marketing tenants keep legal pages external.)
+    const loaders = pickPages(this.scope);
+    return Promise.all(loaders.map((l) => l()));
+  }
+}
+// ---------------------------------------------------------------------------
+// StoryblokContentProvider — live delivery API, mapping stories -> our model.
+//
+// Every method tries the Storyblok delivery API and falls back to
+// LocalContentProvider on ANY failure (no token, network error, non-2xx, or a
+// story whose shape doesn't map) — so the site never breaks. The map* fns assume
+// the Storyblok components mirror content-model.ts (same `component`
+// discriminators / shared parent-space schema, per DECISIONS.md). If your space
+// uses different field names, adjust the map* fns — that's the single seam.
+//
+// Config via env: STORYBLOK_REGION (eu|us|ap|ca, default eu),
+// STORYBLOK_VERSION (published|draft, default published).
+// ---------------------------------------------------------------------------
+const STORYBLOK_REGION_BASES: Record<string, string> = {
+  eu: "https://api.storyblok.com",
+  us: "https://api-us.storyblok.com",
+  ap: "https://api-ap.storyblok.com",
+  ca: "https://api-ca.storyblok.com",
+};
+function storyblokBase(): string {
+  const region = (import.meta.env.STORYBLOK_REGION ?? "eu").toLowerCase();
+  return STORYBLOK_REGION_BASES[region] ?? STORYBLOK_REGION_BASES.eu!;
+}
+function storyblokVersion(): "published" | "draft" {
+  return import.meta.env.STORYBLOK_VERSION === "draft" ? "draft" : "published";
+}
+interface StoryblokStory {
+  slug: string;
+  full_slug: string;
+  name: string;
+  content: Record<string, any>;
+}
+// Cap Storyblok latency so a slow/unreachable CMS can't hang the Worker — on
+// timeout (or any error) the caller falls back to LocalContentProvider. The
+// storefront must always render. (Epic S4 / S3.)
+const STORYBLOK_TIMEOUT_MS = 1500;
+async function fetchStoryblokJson<T>(url: string): Promise<T | null> {
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(STORYBLOK_TIMEOUT_MS) });
+    if (!res.ok) return null;
+    return (await res.json()) as T;
+  } catch {
+    // Network error, non-2xx already handled, or AbortSignal timeout.
+    return null;
+  }
+}
+async function fetchStory(token: string, slug: string): Promise<StoryblokStory | null> {
+  const url =
+    `${storyblokBase()}/v2/cdn/stories/${slug}` +
+    `?token=${encodeURIComponent(token)}&version=${storyblokVersion()}`;
+  const json = await fetchStoryblokJson<{ story?: StoryblokStory }>(url);
+  return json?.story ?? null;
+}
+async function fetchStories(token: string, startsWith: string): Promise<StoryblokStory[]> {
+  const url =
+    `${storyblokBase()}/v2/cdn/stories` +
+    `?starts_with=${encodeURIComponent(startsWith)}` +
+    `&token=${encodeURIComponent(token)}&version=${storyblokVersion()}&per_page=100`;
+  const json = await fetchStoryblokJson<{ stories?: StoryblokStory[] }>(url);
+  return json?.stories ?? [];
+}
+function mapHome(content: Record<string, any>): HomeContent {
+  // Storyblok nests the block list under `body` (array of bloks, each with its
+  // own `component`); our HomeBlock union uses the same discriminator.
+  const blocks = Array.isArray(content.body)
+    ? content.body
+    : Array.isArray(content.blocks)
+      ? content.blocks
+      : [];
+  if (blocks.length === 0) throw new Error("storyblok home: no blocks");
+  return {
+    seoTitle: content.seoTitle ?? content.seo_title,
+    seoDescription: content.seoDescription ?? content.seo_description,
+    blocks: blocks as HomeContent["blocks"],
+  };
+}
+function mapPage(content: Record<string, any>, slug: string): EditorialPage {
+  // Expect a rendered-HTML field (text/markdown component). A raw richtext object
+  // would need a resolver — we throw so the local fallback serves it instead.
+  const body_html = content.body_html ?? content.body;
+  if (typeof body_html !== "string") throw new Error(`storyblok page ${slug}: body not HTML`);
+  return {
+    slug: slug.replace(/^pages\//, ""),
+    title: content.title ?? slug,
+    seoTitle: content.seoTitle ?? content.seo_title,
+    seoDescription: content.seoDescription ?? content.seo_description,
+    body_html,
+    eyebrow: content.eyebrow,
+    intro: content.intro,
+    isPolicy: !!content.isPolicy,
+  };
+}
+export class StoryblokContentProvider implements ContentProvider {
+  constructor(
+    private readonly token: string,
+    private readonly fallback: ContentProvider = new LocalContentProvider(),
+  ) {}
+  async getHome(): Promise<HomeContent> {
+    try {
+      const story = await fetchStory(this.token, "home");
+      if (story) return mapHome(story.content);
+    } catch {
+      /* fall back */
+    }
+    return this.fallback.getHome();
+  }
+  getHomeHtml(): Promise<string | null> {
+    // Raw home documents live in tenant content files, not Storyblok — delegate.
+    return this.fallback.getHomeHtml();
+  }
+  getPageHtml(slug: string): Promise<string | null> {
+    return this.fallback.getPageHtml(slug);
+  }
+  listPageHtmlSlugs(): Promise<string[]> {
+    return this.fallback.listPageHtmlSlugs();
+  }
+  getChromeHtml(): Promise<string | null> {
+    // The chrome wrapper lives in tenant content files, not Storyblok — delegate.
+    return this.fallback.getChromeHtml();
+  }
+  async getChrome(): Promise<SiteChrome> {
+    // Editorial chrome (nav/footer/tagline) is authored in Storyblok; the
+    // announcement + legal disclaimers are MIGRATION-sourced (written to local
+    // chrome.json), so overlay those from the fallback regardless.
+    const local = await this.fallback.getChrome();
+    try {
+      const story = await fetchStory(this.token, "chrome");
+      const c = story?.content;
+      if (c && Array.isArray(c.nav)) {
+        return {
+          nav: c.nav,
+          footer: c.footer ?? local.footer,
+          announcement: local.announcement ?? c.announcement,
+          disclaimer: local.disclaimer,
+          disclaimers: local.disclaimers,
+        };
+      }
+    } catch {
+      /* fall back */
+    }
+    return local;
+  }
+  async getPage(slug: string): Promise<EditorialPage | null> {
+    try {
+      const story = await fetchStory(this.token, `pages/${slug}`);
+      if (story) return mapPage(story.content, story.full_slug ?? slug);
+    } catch {
+      /* fall back */
+    }
+    return this.fallback.getPage(slug);
+  }
+  async listPages(): Promise<EditorialPage[]> {
+    try {
+      const stories = await fetchStories(this.token, "pages/");
+      const pages = stories
+        .map((s) => {
+          try {
+            return mapPage(s.content, s.full_slug ?? s.slug);
+          } catch {
+            return null;
+          }
+        })
+        .filter((p): p is EditorialPage => p !== null);
+      if (pages.length > 0) return pages;
+    } catch {
+      /* fall back */
+    }
+    return this.fallback.listPages();
+  }
+}
+// ---------------------------------------------------------------------------
+// PublishedContentProvider — overlays published customization content for the
+// resolved environment (store->app wiring). For each content artifact it checks
+// the customization store ({live,test} pointer -> versioned JSON); if present it
+// serves that, otherwise it delegates to the base provider (Storyblok/local).
+// listPages() stays from the base (per-page overrides flow through getPage).
+// ---------------------------------------------------------------------------
+export interface ContentCustomization {
+  get: KvGet;
+  env: CustomizationEnv;
+}
+export class PublishedContentProvider implements ContentProvider {
+  constructor(
+    private readonly base: ContentProvider,
+    private readonly tenantId: string,
+    private readonly cust: ContentCustomization,
+  ) {}
+  /** Raw published-artifact string for a tenant file, or null to fall back to base. */
+  private publishedRaw(relative: string): Promise<string | null> {
+    return readPublishedArtifact(
+      this.cust.get,
+      this.tenantId,
+      this.cust.env,
+      contentArtifactPath(this.tenantId, relative),
+    );
+  }
+  private async published<T>(relative: string): Promise<T | null> {
+    const raw = await this.publishedRaw(relative);
+    if (!raw) return null;
+    try {
+      return JSON.parse(raw) as T;
+    } catch {
+      return null;
+    }
+  }
+  async getHome(): Promise<HomeContent> {
+    return (await this.published<HomeContent>("home.json")) ?? this.base.getHome();
+  }
+  // Raw whole-page documents (T0 marketing tenants) publish via KV too, so a
+  // vendor edit previews / goes live with NO Worker rebuild. Artifact path mirrors
+  // the source file: content/<tenant>/home.html and .../pages-html/<slug>.html.
+  async getHomeHtml(): Promise<string | null> {
+    return (await this.publishedRaw("home.html")) ?? this.base.getHomeHtml();
+  }
+  async getPageHtml(slug: string): Promise<string | null> {
+    const rel = `pages-html/${normalizeRawPageSlug(slug)}.html`;
+    return (await this.publishedRaw(rel)) ?? this.base.getPageHtml(slug);
+  }
+  listPageHtmlSlugs(): Promise<string[]> {
+    return this.base.listPageHtmlSlugs();
+  }
+  getChromeHtml(): Promise<string | null> {
+    // Raw chrome wrapper is bundled tenant content (like home/page HTML) — delegate.
+    return this.base.getChromeHtml();
+  }
+  async getChrome(): Promise<SiteChrome> {
+    return (await this.published<SiteChrome>("chrome.json")) ?? this.base.getChrome();
+  }
+  async getPage(slug: string): Promise<EditorialPage | null> {
+    return (await this.published<EditorialPage>(`pages/${slug}.json`)) ?? this.base.getPage(slug);
+  }
+  listPages(): Promise<EditorialPage[]> {
+    return this.base.listPages();
+  }
+}
+const PLACEHOLDER_TOKEN_RE = /PLACEHOLDER|^$/i;
+export function createContentProvider(
+  tenant: TenantConfig,
+  customization?: ContentCustomization,
+): ContentProvider {
+  // Content dirs are keyed by tenant_id (the adopter writes content/<tenant>/).
+  const local = new LocalContentProvider(tenant.tenant_id);
+  const token = tenant.storyblok_space_token;
+  const usable = token && !PLACEHOLDER_TOKEN_RE.test(token);
+  const base: ContentProvider = usable
+    ? new StoryblokContentProvider(token, local)
+    : local;
+  return customization
+    ? new PublishedContentProvider(base, tenant.tenant_id, customization)
+    : base;
+}

package/apps/storefront/src/lib/tenantRouting.ts ADDED Viewed

@@ -0,0 +1,91 @@
+/**
+ * Tenant routing resolution: Host first, then a `/<domain>/*` path-prefix
+ * fallback for hosts that don't resolve to a tenant on their own.
+ *
+ * Precedence (host-first — matches the prod contract where a custom hostname
+ * authoritatively owns a tenant; the path form is a DNS-free escape hatch for
+ * localhost/preview):
+ *
+ *   1. Host strictly claims a tenant         -> use it, no base path.
+ *   2. Host is unknown AND the first path
+ *      segment looks like a hostname that
+ *      strictly claims a tenant              -> use it; the segment becomes the
+ *                                               base path and is stripped from
+ *                                               the rendered route.
+ *   3. Otherwise                             -> registry default (resolveByHost).
+ *
+ * Example: on localhost (which claims no tenant), GET
+ *   /store2.tokenoftrust.com/products/foo
+ * resolves tenant "store2", basePath "/store2.tokenoftrust.com", and renders
+ * the route "/products/foo". A bare localhost/products falls through to the
+ * default tenant because "products" isn't a hostname.
+ */
+import type { TenantConfig, TenantResolver } from "@tot/public-runtime";
+export interface TenantRouting {
+  tenant: TenantConfig | null;
+  /** "" when host-resolved; "/<domain>" when path-resolved. */
+  basePath: string;
+  /** Route to render with the tenant prefix stripped (leading slash, no query). */
+  renderPath: string;
+}
+/**
+ * A path segment is treated as a tenant-domain candidate only if it looks like
+ * a hostname (has a dot, no "@" or other path-ish junk). Real first segments
+ * — products, collections, saved, search — never contain a dot, so there is no
+ * collision with genuine routes.
+ */
+export function looksLikeHost(segment: string): boolean {
+  return (
+    segment.length > 0 &&
+    segment.includes(".") &&
+    !segment.startsWith(".") &&
+    !segment.endsWith(".") &&
+    !segment.includes("@") &&
+    !segment.includes(" ")
+  );
+}
+/** Normalize a path: always leading slash, never a trailing slash (except "/"). */
+function normalizePath(path: string): string {
+  const withSlash = path.startsWith("/") ? path : `/${path}`;
+  const trimmed = withSlash.replace(/\/+$/, "");
+  return trimmed === "" ? "/" : trimmed;
+}
+export async function resolveTenantRouting(
+  host: string,
+  pathname: string,
+  resolver: TenantResolver,
+): Promise<TenantRouting> {
+  // 1. Host wins when it explicitly owns a tenant.
+  const byHost = await resolver.resolveStrict(host);
+  if (byHost) {
+    return { tenant: byHost, basePath: "", renderPath: normalizePath(pathname) };
+  }
+  // 2. Unknown host -> try a /<domain>/* path prefix.
+  const segments = pathname.replace(/^\/+/, "").split("/");
+  const firstRaw = segments[0] ?? "";
+  let first = firstRaw;
+  try {
+    first = decodeURIComponent(firstRaw);
+  } catch {
+    /* leave as-is if it isn't valid percent-encoding */
+  }
+  if (looksLikeHost(first)) {
+    const byPath = await resolver.resolveStrict(first);
+    if (byPath) {
+      return {
+        tenant: byPath,
+        basePath: `/${first}`,
+        renderPath: normalizePath(segments.slice(1).join("/")),
+      };
+    }
+  }
+  // 3. Fall back to the registry default for this (unknown) host.
+  const fallback = await resolver.resolveByHost(host);
+  return { tenant: fallback, basePath: "", renderPath: normalizePath(pathname) };
+}