@ohhwells/bridge 0.1.150 → 0.1.151-next.406

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
-import { Ref, ReactNode, DragEvent, PointerEvent } from 'react';
+import { Ref, CSSProperties, ReactNode, DragEvent, PointerEvent } from 'react';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
 import { Toggle as Toggle$1, DropdownMenu as DropdownMenu$1, Tooltip as Tooltip$1 } from 'radix-ui';
@@ -686,6 +686,19 @@ declare function SchedulingWidget({ notifyOnConnect, initialScheduleId, insertAf
     insertAfter?: string;
 }): react_jsx_runtime.JSX.Element;
 
+declare const OHW_LOADER_STYLE: CSSProperties;
+declare function OhwLoaderSpinner(): react_jsx_runtime.JSX.Element;
+declare const OHW_LOADER_PREHYDRATE_SCRIPT = "(function(){try{var fromGlobal=typeof window!==\"undefined\"&&window.__OHW_SUBDOMAIN__?String(window.__OHW_SUBDOMAIN__):\"\";var p=location.hostname.split(\".\");var fromHost=location.hostname.endsWith(\".ohhwells.site\")&&p[0]&&p[0]!==\"www\"?p[0]:\"\";var fromQuery=new URLSearchParams(location.search).get(\"subdomain\")||\"\";var fromCookie=(document.cookie.match(/(?:^|; )ohw-subdomain=([^;]*)/)||[])[1];fromCookie=fromCookie?decodeURIComponent(fromCookie):\"\";if(!fromGlobal&&!fromHost&&!fromQuery&&!fromCookie)return;var e=document.getElementById(\"ohw-loader\");if(e)e.style.display=\"flex\"}catch(e){}})();";
+/**
+ * The loader div plus the script that reveals it before hydration.
+ *
+ * Render it from a template's root layout, outside <Suspense> and before {children}. It starts
+ * hidden, so a non-customer page (a raw template preview URL) never shows it: the script above
+ * only reveals it once it has found a site identity. The bridge hides it again from a
+ * useLayoutEffect once the site's content is applied.
+ */
+declare function OhwLoaderSurface(): react_jsx_runtime.JSX.Element;
+
 declare const DragHandle: React.ForwardRefExoticComponent<React.ButtonHTMLAttributes<HTMLButtonElement> & React.RefAttributes<HTMLButtonElement>>;
 
 /**
@@ -853,6 +866,89 @@ declare function EmptySection({ title, homeHref, eyebrowKey, titleKey, subtitleK
 
 declare function isEditSessionActive(): boolean;
 
+declare const BRAND_TITLE_KEY = "__ohw_site_title";
+declare const SITE_OG_IMAGE_KEY = "__ohw_og_image";
+/**
+ * Apply the reserved brand-chrome keys from a hydrated content payload. Safe to call on every
+ * hydrate: each write guards on its current value. Missing keys are simply skipped, so a site
+ * without the business-name path / Site Settings overrides is untouched. Description applies
+ * only when non-empty. Og:image applies when the key is present — empty string clears it
+ * (Site Settings Remove).
+ */
+declare function applyBrandChrome(content: Record<string, string>): void;
+
+/**
+ * Telling a page's content mounting apart from incidental DOM churn, so the hydration pass can run
+ * before the browser paints in the first case and stay debounced in the second.
+ *
+ * Measured on a client-side nav from `/` to `/about`: the page's DOM commits at +376ms showing the
+ * template's own default copy, and the stored content only replaces it at +523ms when the debounced
+ * observer pass runs — ~150ms of visibly wrong text on every page-to-page click. The content was
+ * already in the cache the whole time (blocking the per-path fetch changed nothing), so that window
+ * was pure timer latency. A hard refresh never showed it because the loader covers the first paint,
+ * and the loader does not come back for client-side navigation.
+ *
+ * The fix rests on when a MutationObserver callback runs: it is queued as a microtask and drains at
+ * the end of the task that mutated the DOM, which is before the browser's next rendering
+ * opportunity. Applying synchronously from the callback therefore makes the new page's *first*
+ * paint correct, where a `setTimeout` — at any delay, including 0 — necessarily lands a frame later.
+ *
+ * The debounce still earns its keep for everything else, so this is a discriminator rather than a
+ * removal: only a batch that actually mounted content the bridge writes into skips the timer.
+ */
+/**
+ * Did this batch of mutations add content the bridge is responsible for hydrating?
+ *
+ * Deliberately cheap: it stops at the first match, and the observer watches `childList` only, so
+ * attribute-driven churn (carousel fades, hover states, the style store) never reaches it at all.
+ */
+declare function hasMountedContentNodes(records: MutationRecord[]): boolean;
+
+/**
+ * Deciding when a client-side page switch actually needs to ask the backend for content.
+ *
+ * A site's content is stored as one site-wide blob, so the payload the content endpoint returns is
+ * identical for every ordinary page. The exception is a duplicated page: it shares its source
+ * page's `data-ohw-key` strings but stores different values against them, which the backend merges
+ * in per path. The bridge used to be unable to tell the two apart, so it fetched once per distinct
+ * path visited — meaning every page switch on a normal site re-downloaded a byte-identical blob.
+ *
+ * The content response now carries `overriddenPaths`, the paths that genuinely diverge, which
+ * reduces that to: fetch on the first load, then only when entering a page that is actually a
+ * duplicate. An older backend omits the field, and since there is no other way to recognise a
+ * duplicate from the client, that case keeps the previous fetch-per-path behaviour rather than
+ * risking a duplicated page silently showing its source page's content.
+ */
+/** Record what a content response said, including that it said nothing. */
+declare function recordOverriddenPaths(subdomain: string, raw: unknown): void;
+/** Should navigating to `path` trigger a content fetch? */
+declare function shouldFetchContentForPath(subdomain: string, path: string): boolean;
+/** Test seam: the cache is module state that would otherwise leak between cases. */
+declare function resetOverriddenPathsCache(): void;
+
+declare function isStickySearchParam(name: string): boolean;
+/**
+ * Copy the sticky params of `currentSearch` onto `target`, and report whether anything changed.
+ *
+ * A param already present on `target` wins — an author who wrote `/pricing?ref=footer` meant that
+ * `ref`, so it is not overwritten by the one the visitor arrived with.
+ */
+declare function applyStickySearchParams(target: URL, currentSearch: string): boolean;
+/**
+ * Whether a click should be turned into an in-page navigation at all.
+ *
+ * The modifier checks are the reason this exists as a named helper: a handler that calls
+ * preventDefault() on every click silently breaks cmd/ctrl-click (open in new tab), shift-click
+ * (new window) and middle-click, which is a far worse regression than the dropped param it was
+ * trying to fix.
+ */
+declare function isPlainLeftClick(e: MouseEvent): boolean;
+/**
+ * Given a clicked anchor, the page's current search string and the origin, work out the URL the
+ * bridge should navigate to instead — or null to let the browser handle the click untouched.
+ */
+declare function resolveStickyNavigation(anchor: HTMLAnchorElement, currentSearch: string, origin: string): string | null;
+
 type CarouselSlide = {
     src: string;
     alt: string;
@@ -874,4 +970,4 @@ declare function useOhwCarousel(key: string, initial: CarouselSlide[]): {
     bind: Record<string, string>;
 };
 
-export { AI_DEFAULT_BRAND, AI_FOOTER_KEY, AI_TREE_SCHEMA_VERSIONS, AI_TREE_TOKENS, type AiBlockNode, type AiBrandKit, type AiFooterBottomBar, type AiFooterColumn, type AiFooterLayoutTree, AiFooterRenderer, type AiFooterRendererProps, type AiLayoutTree, AiTreeRenderer, type AiTreeRendererProps, type CarouselSlide, CustomToolbar, CustomToolbarButton, CustomToolbarDivider, DragHandle, DropIndicator, type DropIndicatorProps, DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger, EmptySection, type EmptySectionProps, FOOTER_COLUMN_BLOCKS, FOOTER_COLUMN_SPANS, FOOTER_SOCIAL_PLATFORMS, ItemActionToolbar, type ItemActionToolbarProps, ItemInteractionLayer, type ItemInteractionLayerProps, type ItemInteractionState, LinkEditorPanel, type LinkModalMode, type LinkModalProps, type LinkPage, LinkPopover, type LinkSection, OhhwellsBridge, SchedulingWidget, type SectionScaffold, type SiteLegalLinks, Toggle, ToggleGroup, ToggleGroupItem, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, addFooterLinkColumn, appendFooterSocial, buildDefaultFooterTree, buildTarget, dropIndicatorVariants, ensureFooterTree, filterAvailablePages, foldAlignIntoTrees, getEditModeInitialState, insertFooterHours, isEditSessionActive, isRenderableFooterTree, isRenderableTree, isValidUrl, nextViableSlide, parseAiFooterState, parseAiSectionsState, parseTarget, removeFooterBlock, resolveFooterCopyright, serializeAiFooterState, stepViableSlide, stripTextAlignCss, toggleVariants, useOhwCarousel, validateUrlInput, viableSlides };
+export { AI_DEFAULT_BRAND, AI_FOOTER_KEY, AI_TREE_SCHEMA_VERSIONS, AI_TREE_TOKENS, type AiBlockNode, type AiBrandKit, type AiFooterBottomBar, type AiFooterColumn, type AiFooterLayoutTree, AiFooterRenderer, type AiFooterRendererProps, type AiLayoutTree, AiTreeRenderer, type AiTreeRendererProps, BRAND_TITLE_KEY, type CarouselSlide, CustomToolbar, CustomToolbarButton, CustomToolbarDivider, DragHandle, DropIndicator, type DropIndicatorProps, DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger, EmptySection, type EmptySectionProps, FOOTER_COLUMN_BLOCKS, FOOTER_COLUMN_SPANS, FOOTER_SOCIAL_PLATFORMS, ItemActionToolbar, type ItemActionToolbarProps, ItemInteractionLayer, type ItemInteractionLayerProps, type ItemInteractionState, LinkEditorPanel, type LinkModalMode, type LinkModalProps, type LinkPage, LinkPopover, type LinkSection, OHW_LOADER_PREHYDRATE_SCRIPT, OHW_LOADER_STYLE, OhhwellsBridge, OhwLoaderSpinner, OhwLoaderSurface, SITE_OG_IMAGE_KEY, SchedulingWidget, type SectionScaffold, type SiteLegalLinks, Toggle, ToggleGroup, ToggleGroupItem, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, addFooterLinkColumn, appendFooterSocial, applyBrandChrome, applyStickySearchParams, buildDefaultFooterTree, buildTarget, dropIndicatorVariants, ensureFooterTree, filterAvailablePages, foldAlignIntoTrees, getEditModeInitialState, hasMountedContentNodes, insertFooterHours, isEditSessionActive, isPlainLeftClick, isRenderableFooterTree, isRenderableTree, isStickySearchParam, isValidUrl, nextViableSlide, parseAiFooterState, parseAiSectionsState, parseTarget, recordOverriddenPaths, removeFooterBlock, resetOverriddenPathsCache, resolveFooterCopyright, resolveStickyNavigation, serializeAiFooterState, shouldFetchContentForPath, stepViableSlide, stripTextAlignCss, toggleVariants, useOhwCarousel, validateUrlInput, viableSlides };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
-import { Ref, ReactNode, DragEvent, PointerEvent } from 'react';
+import { Ref, CSSProperties, ReactNode, DragEvent, PointerEvent } from 'react';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
 import { Toggle as Toggle$1, DropdownMenu as DropdownMenu$1, Tooltip as Tooltip$1 } from 'radix-ui';
@@ -686,6 +686,19 @@ declare function SchedulingWidget({ notifyOnConnect, initialScheduleId, insertAf
     insertAfter?: string;
 }): react_jsx_runtime.JSX.Element;
 
+declare const OHW_LOADER_STYLE: CSSProperties;
+declare function OhwLoaderSpinner(): react_jsx_runtime.JSX.Element;
+declare const OHW_LOADER_PREHYDRATE_SCRIPT = "(function(){try{var fromGlobal=typeof window!==\"undefined\"&&window.__OHW_SUBDOMAIN__?String(window.__OHW_SUBDOMAIN__):\"\";var p=location.hostname.split(\".\");var fromHost=location.hostname.endsWith(\".ohhwells.site\")&&p[0]&&p[0]!==\"www\"?p[0]:\"\";var fromQuery=new URLSearchParams(location.search).get(\"subdomain\")||\"\";var fromCookie=(document.cookie.match(/(?:^|; )ohw-subdomain=([^;]*)/)||[])[1];fromCookie=fromCookie?decodeURIComponent(fromCookie):\"\";if(!fromGlobal&&!fromHost&&!fromQuery&&!fromCookie)return;var e=document.getElementById(\"ohw-loader\");if(e)e.style.display=\"flex\"}catch(e){}})();";
+/**
+ * The loader div plus the script that reveals it before hydration.
+ *
+ * Render it from a template's root layout, outside <Suspense> and before {children}. It starts
+ * hidden, so a non-customer page (a raw template preview URL) never shows it: the script above
+ * only reveals it once it has found a site identity. The bridge hides it again from a
+ * useLayoutEffect once the site's content is applied.
+ */
+declare function OhwLoaderSurface(): react_jsx_runtime.JSX.Element;
+
 declare const DragHandle: React.ForwardRefExoticComponent<React.ButtonHTMLAttributes<HTMLButtonElement> & React.RefAttributes<HTMLButtonElement>>;
 
 /**
@@ -853,6 +866,89 @@ declare function EmptySection({ title, homeHref, eyebrowKey, titleKey, subtitleK
 
 declare function isEditSessionActive(): boolean;
 
+declare const BRAND_TITLE_KEY = "__ohw_site_title";
+declare const SITE_OG_IMAGE_KEY = "__ohw_og_image";
+/**
+ * Apply the reserved brand-chrome keys from a hydrated content payload. Safe to call on every
+ * hydrate: each write guards on its current value. Missing keys are simply skipped, so a site
+ * without the business-name path / Site Settings overrides is untouched. Description applies
+ * only when non-empty. Og:image applies when the key is present — empty string clears it
+ * (Site Settings Remove).
+ */
+declare function applyBrandChrome(content: Record<string, string>): void;
+
+/**
+ * Telling a page's content mounting apart from incidental DOM churn, so the hydration pass can run
+ * before the browser paints in the first case and stay debounced in the second.
+ *
+ * Measured on a client-side nav from `/` to `/about`: the page's DOM commits at +376ms showing the
+ * template's own default copy, and the stored content only replaces it at +523ms when the debounced
+ * observer pass runs — ~150ms of visibly wrong text on every page-to-page click. The content was
+ * already in the cache the whole time (blocking the per-path fetch changed nothing), so that window
+ * was pure timer latency. A hard refresh never showed it because the loader covers the first paint,
+ * and the loader does not come back for client-side navigation.
+ *
+ * The fix rests on when a MutationObserver callback runs: it is queued as a microtask and drains at
+ * the end of the task that mutated the DOM, which is before the browser's next rendering
+ * opportunity. Applying synchronously from the callback therefore makes the new page's *first*
+ * paint correct, where a `setTimeout` — at any delay, including 0 — necessarily lands a frame later.
+ *
+ * The debounce still earns its keep for everything else, so this is a discriminator rather than a
+ * removal: only a batch that actually mounted content the bridge writes into skips the timer.
+ */
+/**
+ * Did this batch of mutations add content the bridge is responsible for hydrating?
+ *
+ * Deliberately cheap: it stops at the first match, and the observer watches `childList` only, so
+ * attribute-driven churn (carousel fades, hover states, the style store) never reaches it at all.
+ */
+declare function hasMountedContentNodes(records: MutationRecord[]): boolean;
+
+/**
+ * Deciding when a client-side page switch actually needs to ask the backend for content.
+ *
+ * A site's content is stored as one site-wide blob, so the payload the content endpoint returns is
+ * identical for every ordinary page. The exception is a duplicated page: it shares its source
+ * page's `data-ohw-key` strings but stores different values against them, which the backend merges
+ * in per path. The bridge used to be unable to tell the two apart, so it fetched once per distinct
+ * path visited — meaning every page switch on a normal site re-downloaded a byte-identical blob.
+ *
+ * The content response now carries `overriddenPaths`, the paths that genuinely diverge, which
+ * reduces that to: fetch on the first load, then only when entering a page that is actually a
+ * duplicate. An older backend omits the field, and since there is no other way to recognise a
+ * duplicate from the client, that case keeps the previous fetch-per-path behaviour rather than
+ * risking a duplicated page silently showing its source page's content.
+ */
+/** Record what a content response said, including that it said nothing. */
+declare function recordOverriddenPaths(subdomain: string, raw: unknown): void;
+/** Should navigating to `path` trigger a content fetch? */
+declare function shouldFetchContentForPath(subdomain: string, path: string): boolean;
+/** Test seam: the cache is module state that would otherwise leak between cases. */
+declare function resetOverriddenPathsCache(): void;
+
+declare function isStickySearchParam(name: string): boolean;
+/**
+ * Copy the sticky params of `currentSearch` onto `target`, and report whether anything changed.
+ *
+ * A param already present on `target` wins — an author who wrote `/pricing?ref=footer` meant that
+ * `ref`, so it is not overwritten by the one the visitor arrived with.
+ */
+declare function applyStickySearchParams(target: URL, currentSearch: string): boolean;
+/**
+ * Whether a click should be turned into an in-page navigation at all.
+ *
+ * The modifier checks are the reason this exists as a named helper: a handler that calls
+ * preventDefault() on every click silently breaks cmd/ctrl-click (open in new tab), shift-click
+ * (new window) and middle-click, which is a far worse regression than the dropped param it was
+ * trying to fix.
+ */
+declare function isPlainLeftClick(e: MouseEvent): boolean;
+/**
+ * Given a clicked anchor, the page's current search string and the origin, work out the URL the
+ * bridge should navigate to instead — or null to let the browser handle the click untouched.
+ */
+declare function resolveStickyNavigation(anchor: HTMLAnchorElement, currentSearch: string, origin: string): string | null;
+
 type CarouselSlide = {
     src: string;
     alt: string;
@@ -874,4 +970,4 @@ declare function useOhwCarousel(key: string, initial: CarouselSlide[]): {
     bind: Record<string, string>;
 };
 
-export { AI_DEFAULT_BRAND, AI_FOOTER_KEY, AI_TREE_SCHEMA_VERSIONS, AI_TREE_TOKENS, type AiBlockNode, type AiBrandKit, type AiFooterBottomBar, type AiFooterColumn, type AiFooterLayoutTree, AiFooterRenderer, type AiFooterRendererProps, type AiLayoutTree, AiTreeRenderer, type AiTreeRendererProps, type CarouselSlide, CustomToolbar, CustomToolbarButton, CustomToolbarDivider, DragHandle, DropIndicator, type DropIndicatorProps, DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger, EmptySection, type EmptySectionProps, FOOTER_COLUMN_BLOCKS, FOOTER_COLUMN_SPANS, FOOTER_SOCIAL_PLATFORMS, ItemActionToolbar, type ItemActionToolbarProps, ItemInteractionLayer, type ItemInteractionLayerProps, type ItemInteractionState, LinkEditorPanel, type LinkModalMode, type LinkModalProps, type LinkPage, LinkPopover, type LinkSection, OhhwellsBridge, SchedulingWidget, type SectionScaffold, type SiteLegalLinks, Toggle, ToggleGroup, ToggleGroupItem, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, addFooterLinkColumn, appendFooterSocial, buildDefaultFooterTree, buildTarget, dropIndicatorVariants, ensureFooterTree, filterAvailablePages, foldAlignIntoTrees, getEditModeInitialState, insertFooterHours, isEditSessionActive, isRenderableFooterTree, isRenderableTree, isValidUrl, nextViableSlide, parseAiFooterState, parseAiSectionsState, parseTarget, removeFooterBlock, resolveFooterCopyright, serializeAiFooterState, stepViableSlide, stripTextAlignCss, toggleVariants, useOhwCarousel, validateUrlInput, viableSlides };
+export { AI_DEFAULT_BRAND, AI_FOOTER_KEY, AI_TREE_SCHEMA_VERSIONS, AI_TREE_TOKENS, type AiBlockNode, type AiBrandKit, type AiFooterBottomBar, type AiFooterColumn, type AiFooterLayoutTree, AiFooterRenderer, type AiFooterRendererProps, type AiLayoutTree, AiTreeRenderer, type AiTreeRendererProps, BRAND_TITLE_KEY, type CarouselSlide, CustomToolbar, CustomToolbarButton, CustomToolbarDivider, DragHandle, DropIndicator, type DropIndicatorProps, DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger, EmptySection, type EmptySectionProps, FOOTER_COLUMN_BLOCKS, FOOTER_COLUMN_SPANS, FOOTER_SOCIAL_PLATFORMS, ItemActionToolbar, type ItemActionToolbarProps, ItemInteractionLayer, type ItemInteractionLayerProps, type ItemInteractionState, LinkEditorPanel, type LinkModalMode, type LinkModalProps, type LinkPage, LinkPopover, type LinkSection, OHW_LOADER_PREHYDRATE_SCRIPT, OHW_LOADER_STYLE, OhhwellsBridge, OhwLoaderSpinner, OhwLoaderSurface, SITE_OG_IMAGE_KEY, SchedulingWidget, type SectionScaffold, type SiteLegalLinks, Toggle, ToggleGroup, ToggleGroupItem, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, addFooterLinkColumn, appendFooterSocial, applyBrandChrome, applyStickySearchParams, buildDefaultFooterTree, buildTarget, dropIndicatorVariants, ensureFooterTree, filterAvailablePages, foldAlignIntoTrees, getEditModeInitialState, hasMountedContentNodes, insertFooterHours, isEditSessionActive, isPlainLeftClick, isRenderableFooterTree, isRenderableTree, isStickySearchParam, isValidUrl, nextViableSlide, parseAiFooterState, parseAiSectionsState, parseTarget, recordOverriddenPaths, removeFooterBlock, resetOverriddenPathsCache, resolveFooterCopyright, resolveStickyNavigation, serializeAiFooterState, shouldFetchContentForPath, stepViableSlide, stripTextAlignCss, toggleVariants, useOhwCarousel, validateUrlInput, viableSlides };