@vectoriox/iox-ui 4.34.0 → 4.36.0

package/index.d.ts

@@ -308,6 +308,12 @@ declare class BuilderIconComponent {
     /** Full Phosphor icon CSS class string, e.g. "ph-thin ph-star" */
     iconClass: string;
     nodeId: string;
+    /**
+     * Repaired at render time: a Phosphor class saved without its weight (`ph-house`) matches no CSS
+     * rule and renders as an invisible box. The picker used to emit exactly that, so this keeps
+     * every already-saved icon working. Shared with the SSR engine — see `normalizeIconClass`.
+     */
+    get normalizedIconClass(): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<BuilderIconComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<BuilderIconComponent, "i[iox-icon]", never, { "iconClass": { "alias": "iconClass"; "required": false; }; "nodeId": { "alias": "nodeId"; "required": false; }; }, {}, never, never, false, never>;
 }
@@ -1928,6 +1934,26 @@ declare function declaredInputNames(type: Type<unknown>): Set<string>;
  */
 declare function safeSetInput(ref: ComponentRef<unknown>, name: string, value: unknown): boolean;
 
+/**
+ * Phosphor's CSS needs TWO classes — a weight and a name (`.ph-thin.ph-house:before`). A class
+ * string carrying only the name matches nothing at all: no `font-family`, no glyph, so the element
+ * renders as an invisible, zero-glyph box.
+ *
+ * The icon picker used to emit exactly that (`ph-house`), so every icon chosen through it was blank
+ * on the canvas, in the picker grid and on the live site. Fixing the picker alone would leave every
+ * icon already saved broken, so the repair happens at RENDER time, here, and is shared by the
+ * builder's Icon component and the SSR engine's renderer.
+ *
+ * Everything that is not a weightless Phosphor class passes through untouched — Iconoir
+ * (`iconoir-home`), custom icon-set fonts, Font Awesome, and Phosphor strings that already carry a
+ * weight.
+ *
+ * See iox-ai-guidance `architecture/cms/custom-icon-fonts.md`.
+ */
+/** The weight assumed when a Phosphor class has none — the weight this platform uses everywhere. */
+declare const DEFAULT_PHOSPHOR_WEIGHT = "ph-thin";
+declare function normalizeIconClass(iconClass: string | null | undefined): string;
+
 /**
  * THE binding path resolver — one implementation, shared by every renderer.
  *
@@ -1941,6 +1967,115 @@ declare function safeSetInput(ref: ComponentRef<unknown>, name: string, value: u
  */
 declare function resolvePath(obj: any, path: string): any;
 
+/** The part of an `IoxBinding` that turns source data into a value. */
+interface BoundValueSpec {
+    /** Dot/bracket path into the source data. Empty or absent means the source value itself. */
+    path?: string;
+    /** Render-time transforms (UI label "Filters"), applied after the path lookup. */
+    pipes?: IoxPipe[];
+}
+/**
+ * Resolve one binding's value out of its already-selected source data: path lookup, then pipes.
+ *
+ * Trivial on its own, which is exactly why it had been retyped at three call sites — the engine's
+ * string renderer, the engine's component renderer and the builder canvas — plus a fourth needed by
+ * page SEO. `resolvePath` itself was forked five times before it was shared, and the copy that
+ * drifted caused a repeater to render in the SSR HTML and then blank on hydration.
+ *
+ * What is NOT here: picking the source (`resolvedData[binding.source]`) and deciding what an empty
+ * context slot means. Those are per-renderer policy — the string renderer clears the prop, the
+ * builder skips it — so they stay with the caller.
+ */
+declare function resolveBoundValue(sourceData: unknown, binding: BoundValueSpec, ctx?: PipeContext): unknown;
+
+/**
+ * The canonical shape of a page's SEO metadata, plus the flat tag list both renderers emit.
+ *
+ * ⚠️ This file is the ONLY declaration of that shape. Before it existed, `iox-cms` stored
+ * `seo.og.title` while the SSR engine read a flat `seo.ogTitle`, so no Open Graph tag had ever been
+ * emitted, and `iox-cms-client` carried a third, hand-copied variant of the same schema. See
+ * iox-ai-guidance `architecture/cms/seo-plan.md`.
+ */
+/** Open Graph subset we author and emit. */
+interface SeoOg {
+    title?: string;
+    description?: string;
+    image?: string;
+}
+/** Twitter-card subset. Emitted only when `card` is set — see `seoToTags`. */
+interface SeoTwitter {
+    card?: string;
+    title?: string;
+    description?: string;
+    image?: string;
+}
+/** Sitemap participation for this page. Consumed by the sitemap route (plan phase 3). */
+interface SeoSitemap {
+    include?: boolean;
+    priority?: number;
+    changeFreq?: string;
+}
+/**
+ * A page's stored SEO metadata, normalized.
+ *
+ * `keywords` has no authoring field — search engines have ignored the tag for over a decade — but
+ * it is read and emitted when a document already carries one, because the engine used to read it.
+ */
+interface SeoDoc {
+    title?: string;
+    description?: string;
+    keywords?: string;
+    canonicalUrl?: string;
+    robots?: string;
+    og?: SeoOg;
+    twitter?: SeoTwitter;
+    structuredData?: unknown;
+    sitemap?: SeoSitemap;
+}
+
+/**
+ * Turn a page's STORED SEO document into the resolved one a crawler should see.
+ *
+ * Runs the ladder, per field: `override` → `binding` → auto. It lives in the main entry point rather
+ * than `seo-core` because the binding rung needs `resolvePath` + `applyBindingPipes` from here, and
+ * `iox-cms` (which imports `seo-core` under plain Node) never resolves anything — it only stores and
+ * declares. `seoToTags` then turns this output into head tags.
+ *
+ * The reason this exists: `applyPageSeo(page.seo)` used to hand the stored strings straight to the
+ * head, never consulting the resolved route item, so all 24 pages rendered from one template shipped
+ * the same `<title>`. See iox-ai-guidance `architecture/cms/seo-plan.md`.
+ */
+/** What the ladder's lower two rungs need. All optional — a static page supplies almost none of it. */
+interface SeoResolveContext {
+    /** The page's resolved data sources, keyed by alias (`$current` on a template page). */
+    resolvedData?: Record<string, unknown> | null;
+    /** The page's layout tree, for the "derive from the content" rung. */
+    tree?: readonly unknown[] | null;
+    /** Title of last resort, when the page has no heading at all. */
+    pageName?: string;
+    /** Absolute URL of the page being rendered — the automatic canonical. */
+    pageUrl?: string;
+}
+/** What the layout tree yields for the bottom rung. */
+interface SeoDerivedContent {
+    title?: string;
+    description?: string;
+    image?: string;
+}
+declare function resolveSeo(seo: unknown, ctx?: SeoResolveContext): SeoDoc;
+/**
+ * Derive a title, description and image from the page's own content, in document order.
+ *
+ * ⚠️ Node bindings are resolved here too. On a template page the `<h1>` is normally bound to
+ * `$current.title`, so reading `props.content` alone would return the design-time placeholder — the
+ * same trap that made context slots fall through to component defaults. An unresolved binding yields
+ * nothing rather than the placeholder.
+ *
+ * Node shapes are the renderers' own: `Heading` has `level` + `content`, `Text` has `content` (rich
+ * HTML from the editor) + `tag`, `Image` has `src`.
+ */
+declare function deriveSeoFromContent(tree: readonly unknown[] | null | undefined, resolvedData?: Record<string, unknown> | null): SeoDerivedContent;
+
 /**
  * Element context state — shared types.
  *
@@ -2441,5 +2576,5 @@ declare class GalleryLoop {
     private emit;
 }
 
-export { AOSService, AnalyticsService, BREAKPOINTS, Breakpoint, BreakpointQueryKind, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, CMSClientInfraModule, CONTEXT_ACTION_TYPES, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ConsentService, ContainerComponent, ContentService, ContextStore, DEFAULT_GALLERY_SCHEDULER, DEFAULT_PAGE_TRANSITION, DEFAULT_PAGE_TRANSITION_DURATION, DEFAULT_PAGE_TRANSITION_EASING, DEFAULT_PAGE_TRANSITION_PERSPECTIVE, DEFAULT_WIDTH_BY_TYPE, DeclarationContext, ENVIRONMENT, FormRenderState, FormRuntimeService, GALLERY_EFFECTS, GALLERY_EFFECT_DESCRIPTORS, GalleryLoop, IOX_BUILDER_EVENTS, IOX_FORM_MESSAGES, IOX_FORM_NAVIGATOR, IOX_FORM_TRANSPORT, IS_PREVIEW, IoxAnimateContainer, IoxAosDirective, IoxAosModule, IoxBuilderComponentsModule, IoxComponentRegistryService, IoxFieldComponent, IoxFormComponent, IoxFormErrorComponent, IoxFormSuccessComponent, IoxPageComponent, IoxPageModule, IoxSubmitButtonComponent, IoxUiModule, LinkedContainerComponent, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, PrivacyModalComponent, PrivacyModalService, PrivacyModelEvent, RESERVED_ALIAS_PREFIX, SUPPRESSED_STYLE_PROPS_BY_TYPE, SWIPER_RESPONSIVE_TRAITS, SectionComponent, TRANSITION_FEELS, TextBlockComponent, VIRTUAL_TRAIT_GROUPS, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, WebSettingsService, activeActions, applyBindingPipes, applyFeel, breakpointDef, breakpointForWidth, breakpointQueryFor, buildDataSourceFilter, buildRelatedFilter, buildSwiperBreakpoints, buildTargetedStateSelector, buildTransitionTimeline, cascadeChain, clearInputOverride, clearOverride, collectContextSlotKeys, collectReferencedAliases, compileDeclarations, composeVirtualTraits, computeRelative, contextActionEffect, contextSlotKeys, countOverrides, dataSourcePlanToRequest, declaredInputNames, defaultMessageResolver, effectiveTransitionId, excludeSelf, feelFor, getByPath, initialSlotValues, isActionEnabled, isContextAction, isInputOverriddenAt, isOverriddenAt, isReservedAlias, isValidSlotKey, legacyEnterToTransition, matchRouteParams, mediaQueryFor, mergeSwiperBreakpoints, nearestCommonAncestorId, nodeCssId, nodeUsesContext, normalizeCollectionResult, normalizeGalleryImage, parentBreakpoint, parseUrlList, planDataSource, planResponsiveRules, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resolveContextValue, resolveDerivedInto, resolveGalleryEffect, resolveGalleryUrls, resolveInputChain, resolveInputs, resolvePageTransition, resolvePath, resolveRelativeInto, resolveRepeaterItems, resolveSiblings, resolveSingleItemId, resolveStateStyles, resolveStyleProps, resolveValueChain, rewriteViewportUnits, safeSetInput, setInputOverride, setOverride, stateNamesIn, stripSuppressedProps, styleKeyToKebab, variableAliases, variableItemsFrom, withContextSlots, wrapInBreakpointQuery, wrapInMediaQuery };
-export type { BreakpointDef, BuildRelatedFilterOptions, ContextActionEffect, ContextActionLike, ContextItemRef, ContextSlotDefault, ContextValueSpec, ContextWriteScope, DataSourceDomain, DataSourceEndpoints, DataSourceMode, DataSourcePlan, DataSourceQueryFilter, DataSourceRequest, DataSourceRequestSpec, DataSourceRouteFilter, DataSourceSpec, FormMessageResolver, GalleryBoundSource, GalleryDurations, GalleryEffect, GalleryEffectDescriptor, GalleryImage, GalleryLoopOptions, GalleryLoopScheduler, GalleryLoopState, GallerySlideState, IBuilderEventEmitter, InputMap, IoxContextSlot, IoxPipe, OverrideBreakpoint, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionOptions, PageTransitionPreset, PipeArgSpec, PipeContext, PipeDescriptor, RelativeInputs, RelativeSourceKind, RelativeSourceSpec, ResolveSiblingsOptions, ResolvedPageTransition, ResponsiveLayer, ResponsiveOverrides, ResponsiveRuleSet, RouteContext, SetContextParams, SiblingsResult, StateStyleMap, StyleMap, StyleTreeNode, SwiperBreakpointMap, ToggleableAction, TransitionFeel, TransitionPhase, TransitionTimelineInput, ValueSource, VirtualTraitGroup };
+export { AOSService, AnalyticsService, BREAKPOINTS, Breakpoint, BreakpointQueryKind, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, CMSClientInfraModule, CONTEXT_ACTION_TYPES, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ConsentService, ContainerComponent, ContentService, ContextStore, DEFAULT_GALLERY_SCHEDULER, DEFAULT_PAGE_TRANSITION, DEFAULT_PAGE_TRANSITION_DURATION, DEFAULT_PAGE_TRANSITION_EASING, DEFAULT_PAGE_TRANSITION_PERSPECTIVE, DEFAULT_PHOSPHOR_WEIGHT, DEFAULT_WIDTH_BY_TYPE, DeclarationContext, ENVIRONMENT, FormRenderState, FormRuntimeService, GALLERY_EFFECTS, GALLERY_EFFECT_DESCRIPTORS, GalleryLoop, IOX_BUILDER_EVENTS, IOX_FORM_MESSAGES, IOX_FORM_NAVIGATOR, IOX_FORM_TRANSPORT, IS_PREVIEW, IoxAnimateContainer, IoxAosDirective, IoxAosModule, IoxBuilderComponentsModule, IoxComponentRegistryService, IoxFieldComponent, IoxFormComponent, IoxFormErrorComponent, IoxFormSuccessComponent, IoxPageComponent, IoxPageModule, IoxSubmitButtonComponent, IoxUiModule, LinkedContainerComponent, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, PrivacyModalComponent, PrivacyModalService, PrivacyModelEvent, RESERVED_ALIAS_PREFIX, SUPPRESSED_STYLE_PROPS_BY_TYPE, SWIPER_RESPONSIVE_TRAITS, SectionComponent, TRANSITION_FEELS, TextBlockComponent, VIRTUAL_TRAIT_GROUPS, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, WebSettingsService, activeActions, applyBindingPipes, applyFeel, breakpointDef, breakpointForWidth, breakpointQueryFor, buildDataSourceFilter, buildRelatedFilter, buildSwiperBreakpoints, buildTargetedStateSelector, buildTransitionTimeline, cascadeChain, clearInputOverride, clearOverride, collectContextSlotKeys, collectReferencedAliases, compileDeclarations, composeVirtualTraits, computeRelative, contextActionEffect, contextSlotKeys, countOverrides, dataSourcePlanToRequest, declaredInputNames, defaultMessageResolver, deriveSeoFromContent, effectiveTransitionId, excludeSelf, feelFor, getByPath, initialSlotValues, isActionEnabled, isContextAction, isInputOverriddenAt, isOverriddenAt, isReservedAlias, isValidSlotKey, legacyEnterToTransition, matchRouteParams, mediaQueryFor, mergeSwiperBreakpoints, nearestCommonAncestorId, nodeCssId, nodeUsesContext, normalizeCollectionResult, normalizeGalleryImage, normalizeIconClass, parentBreakpoint, parseUrlList, planDataSource, planResponsiveRules, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resolveBoundValue, resolveContextValue, resolveDerivedInto, resolveGalleryEffect, resolveGalleryUrls, resolveInputChain, resolveInputs, resolvePageTransition, resolvePath, resolveRelativeInto, resolveRepeaterItems, resolveSeo, resolveSiblings, resolveSingleItemId, resolveStateStyles, resolveStyleProps, resolveValueChain, rewriteViewportUnits, safeSetInput, setInputOverride, setOverride, stateNamesIn, stripSuppressedProps, styleKeyToKebab, variableAliases, variableItemsFrom, withContextSlots, wrapInBreakpointQuery, wrapInMediaQuery };
+export type { BoundValueSpec, BreakpointDef, BuildRelatedFilterOptions, ContextActionEffect, ContextActionLike, ContextItemRef, ContextSlotDefault, ContextValueSpec, ContextWriteScope, DataSourceDomain, DataSourceEndpoints, DataSourceMode, DataSourcePlan, DataSourceQueryFilter, DataSourceRequest, DataSourceRequestSpec, DataSourceRouteFilter, DataSourceSpec, FormMessageResolver, GalleryBoundSource, GalleryDurations, GalleryEffect, GalleryEffectDescriptor, GalleryImage, GalleryLoopOptions, GalleryLoopScheduler, GalleryLoopState, GallerySlideState, IBuilderEventEmitter, InputMap, IoxContextSlot, IoxPipe, OverrideBreakpoint, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionOptions, PageTransitionPreset, PipeArgSpec, PipeContext, PipeDescriptor, RelativeInputs, RelativeSourceKind, RelativeSourceSpec, ResolveSiblingsOptions, ResolvedPageTransition, ResponsiveLayer, ResponsiveOverrides, ResponsiveRuleSet, RouteContext, SeoDerivedContent, SeoResolveContext, SetContextParams, SiblingsResult, StateStyleMap, StyleMap, StyleTreeNode, SwiperBreakpointMap, ToggleableAction, TransitionFeel, TransitionPhase, TransitionTimelineInput, ValueSource, VirtualTraitGroup };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "4.34.0",
+  "version": "4.36.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

package/seo-core/index.d.ts

@@ -42,6 +42,52 @@ interface SeoDoc {
     structuredData?: unknown;
     sitemap?: SeoSitemap;
 }
+/**
+ * A binding on an SEO field. Structurally the resolvable part of an `IoxBinding` — `source` picks an
+ * entry in the page's resolved data (`$current` on a template page), `path` walks into it, `pipes`
+ * are the render-time transforms. Typed loosely because the pipe catalog lives in the main
+ * `@vectoriox/iox-ui` entry point, which this framework-free one must not import.
+ */
+interface SeoBinding {
+    source: string;
+    path?: string;
+    pipes?: readonly unknown[];
+}
+/**
+ * One SEO field as stored once it carries more than a typed string.
+ *
+ * The ladder is `override` → `binding` → auto; `auto: false` opts that field out of the automatic
+ * value, leaving it genuinely empty. A bare `string` in a stored document means `{ override }`, so
+ * nothing has to be migrated.
+ */
+interface SeoFieldValue {
+    override?: string;
+    binding?: SeoBinding;
+    auto?: false;
+}
+/** A stored SEO document, before resolution: any text field may be a plain string or a value object. */
+type SeoRawDoc = Record<string, unknown>;
+/**
+ * The text fields that can carry a binding, as dotted paths into the document.
+ *
+ * One list, used by the resolver and (phase 2) by the panel that draws the bind affordance — so a
+ * field can never be bindable in the UI and ignored at render time. `robots`, `sitemap.*` and
+ * `structuredData` are deliberately absent: they are pick-lists and blobs, not prose.
+ */
+declare const SEO_BINDABLE_FIELDS: readonly string[];
+/** Where an automatic value comes from when a field has neither an override nor a binding. */
+type SeoAutoSource = 'contentTitle' | 'contentDescription' | 'contentImage' | 'pageUrl';
+/**
+ * The bottom rung of the ladder, as a table rather than a chain of ifs.
+ *
+ * Deliberately short. `og:title` and `twitter:*` are NOT here — `seoToTags` already falls back to
+ * the page title for them, and materialising a copy of a value we did not author would only make
+ * later drift harder to see.
+ */
+declare const SEO_AUTO_SOURCES: ReadonlyArray<{
+    field: string;
+    source: SeoAutoSource;
+}>;
 /** `<title>`. */
 interface SeoTitleTag {
     kind: 'title';
@@ -101,6 +147,14 @@ declare const SEO_CHANGE_FREQ_OPTIONS: ReadonlyArray<{
  * Empty branches are dropped rather than left as `{}`, so `if (seo.og)` is a meaningful test.
  */
 declare function normalizeSeoDoc(raw: unknown): SeoDoc;
+/**
+ * A field's value as a trimmed string, or `undefined`. Exported because the resolver needs the exact
+ * same coercion for a value it has just pulled out of a data source.
+ *
+ * Unwraps the value object: a bound or auto field has no `override`, so it correctly resolves to
+ * `undefined` here and `resolveSeo` fills it in from the lower rungs.
+ */
+declare function seoString(value: unknown): string | undefined;
 
 /**
  * Turn a page's SEO document into the flat list of head tags to emit.
@@ -131,5 +185,5 @@ declare function seoToTags(seo: SeoDoc | unknown, ctx?: SeoTagContext): SeoTag[]
  */
 declare function buildSeoSchemaProperties(): Record<string, unknown>;
 
-export { SEO_CHANGE_FREQ_OPTIONS, SEO_DESCRIPTION_MAX, SEO_ROBOTS_OPTIONS, SEO_TITLE_MAX, SEO_TWITTER_CARD_OPTIONS, buildSeoSchemaProperties, normalizeSeoDoc, seoToTags };
-export type { SeoDoc, SeoLinkTag, SeoMetaTag, SeoOg, SeoSitemap, SeoTag, SeoTagContext, SeoTitleTag, SeoTwitter };
+export { SEO_AUTO_SOURCES, SEO_BINDABLE_FIELDS, SEO_CHANGE_FREQ_OPTIONS, SEO_DESCRIPTION_MAX, SEO_ROBOTS_OPTIONS, SEO_TITLE_MAX, SEO_TWITTER_CARD_OPTIONS, buildSeoSchemaProperties, normalizeSeoDoc, seoString, seoToTags };
+export type { SeoAutoSource, SeoBinding, SeoDoc, SeoFieldValue, SeoLinkTag, SeoMetaTag, SeoOg, SeoRawDoc, SeoSitemap, SeoTag, SeoTagContext, SeoTitleTag, SeoTwitter };

package/src/seo-core/normalize.ts

@@ -18,32 +18,32 @@ export function normalizeSeoDoc(raw: unknown): SeoDoc {
     if (!src) return {};
 
     const og = compact<SeoOg>({
-        title: str(pick(src, 'og', 'title') ?? src['ogTitle']),
-        description: str(pick(src, 'og', 'description') ?? src['ogDescription']),
-        image: str(pick(src, 'og', 'image') ?? src['ogImage']),
+        title: seoString(pick(src, 'og', 'title') ?? src['ogTitle']),
+        description: seoString(pick(src, 'og', 'description') ?? src['ogDescription']),
+        image: seoString(pick(src, 'og', 'image') ?? src['ogImage']),
     });
 
     const twitter = compact<SeoTwitter>({
-        card: str(pick(src, 'twitter', 'card')),
-        title: str(pick(src, 'twitter', 'title')),
-        description: str(pick(src, 'twitter', 'description')),
-        image: str(pick(src, 'twitter', 'image')),
+        card: seoString(pick(src, 'twitter', 'card')),
+        title: seoString(pick(src, 'twitter', 'title')),
+        description: seoString(pick(src, 'twitter', 'description')),
+        image: seoString(pick(src, 'twitter', 'image')),
     });
 
     const sitemap = compact<SeoSitemap>({
         include: bool(pick(src, 'sitemap', 'include')),
         priority: num(pick(src, 'sitemap', 'priority')),
-        changeFreq: str(pick(src, 'sitemap', 'changeFreq')),
+        changeFreq: seoString(pick(src, 'sitemap', 'changeFreq')),
     });
 
     const structuredData = structured(src['structuredData']);
 
     const doc = compact<SeoDoc>({
-        title: str(src['title']),
-        description: str(src['description']),
-        keywords: str(src['keywords']),
-        canonicalUrl: str(src['canonicalUrl']),
-        robots: str(src['robots']),
+        title: seoString(src['title']),
+        description: seoString(src['description']),
+        keywords: seoString(src['keywords']),
+        canonicalUrl: seoString(src['canonicalUrl']),
+        robots: seoString(src['robots']),
         og,
         twitter,
         sitemap,
@@ -60,12 +60,13 @@ function pick(src: Record<string, unknown>, branch: string, leaf: string): unkno
 }
 
 /**
- * A field's value as a trimmed string, or `undefined`.
+ * A field's value as a trimmed string, or `undefined`. Exported because the resolver needs the exact
+ * same coercion for a value it has just pulled out of a data source.
  *
- * Unwraps the phase-2 value object: a bound or auto field has no `override`, so it correctly
- * resolves to `undefined` here and the binding layer fills it in later.
+ * Unwraps the value object: a bound or auto field has no `override`, so it correctly resolves to
+ * `undefined` here and `resolveSeo` fills it in from the lower rungs.
  */
-function str(value: unknown): string | undefined {
+export function seoString(value: unknown): string | undefined {
     const wrapper = asRecord(value);
     const raw = wrapper ? wrapper['override'] : value;
     if (typeof raw === 'number') return String(raw);

package/src/seo-core/seo.model.ts

@@ -47,6 +47,70 @@ export interface SeoDoc {
     sitemap?: SeoSitemap;
 }
 
+/**
+ * A binding on an SEO field. Structurally the resolvable part of an `IoxBinding` — `source` picks an
+ * entry in the page's resolved data (`$current` on a template page), `path` walks into it, `pipes`
+ * are the render-time transforms. Typed loosely because the pipe catalog lives in the main
+ * `@vectoriox/iox-ui` entry point, which this framework-free one must not import.
+ */
+export interface SeoBinding {
+    source: string;
+    path?: string;
+    pipes?: readonly unknown[];
+}
+
+/**
+ * One SEO field as stored once it carries more than a typed string.
+ *
+ * The ladder is `override` → `binding` → auto; `auto: false` opts that field out of the automatic
+ * value, leaving it genuinely empty. A bare `string` in a stored document means `{ override }`, so
+ * nothing has to be migrated.
+ */
+export interface SeoFieldValue {
+    override?: string;
+    binding?: SeoBinding;
+    auto?: false;
+}
+
+/** A stored SEO document, before resolution: any text field may be a plain string or a value object. */
+export type SeoRawDoc = Record<string, unknown>;
+
+/**
+ * The text fields that can carry a binding, as dotted paths into the document.
+ *
+ * One list, used by the resolver and (phase 2) by the panel that draws the bind affordance — so a
+ * field can never be bindable in the UI and ignored at render time. `robots`, `sitemap.*` and
+ * `structuredData` are deliberately absent: they are pick-lists and blobs, not prose.
+ */
+export const SEO_BINDABLE_FIELDS: readonly string[] = [
+    'title',
+    'description',
+    'canonicalUrl',
+    'og.title',
+    'og.description',
+    'og.image',
+    'twitter.title',
+    'twitter.description',
+    'twitter.image',
+];
+
+/** Where an automatic value comes from when a field has neither an override nor a binding. */
+export type SeoAutoSource = 'contentTitle' | 'contentDescription' | 'contentImage' | 'pageUrl';
+
+/**
+ * The bottom rung of the ladder, as a table rather than a chain of ifs.
+ *
+ * Deliberately short. `og:title` and `twitter:*` are NOT here — `seoToTags` already falls back to
+ * the page title for them, and materialising a copy of a value we did not author would only make
+ * later drift harder to see.
+ */
+export const SEO_AUTO_SOURCES: ReadonlyArray<{ field: string; source: SeoAutoSource }> = [
+    { field: 'title', source: 'contentTitle' },
+    { field: 'description', source: 'contentDescription' },
+    { field: 'og.image', source: 'contentImage' },
+    { field: 'canonicalUrl', source: 'pageUrl' },
+];
+
 /** `<title>`. */
 export interface SeoTitleTag {
     kind: 'title';