@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/page-header-actions-context.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type ReactNode } from 'react';
+/**
+ * Lets any surface publish controls into the PAGE header — the bar carrying
+ * the surface icon, title and breadcrumb — from inside the page body.
+ *
+ * WHY A CONTEXT AND NOT A PROP. A route that owns its own `DashboardLayout`
+ * passes `headerRight` directly, which is how Screens, Layouts, Components
+ * and Templates put their readout and create button up there. A plugin
+ * surface has no such route: the console shell's generic host page owns the
+ * layout and renders the surface as a CHILD, and a child cannot set its
+ * parent's prop. The console app provides `setHeaderActions` from the layout
+ * that owns the header; a surface publishes through {@link PageHeaderActions}
+ * and stays free of console-app imports.
+ *
+ * WHICH HEADER A CONTROL BELONGS IN is a separate question this context
+ * deliberately does not answer. A surface with NO section navigation —
+ * Screens, Layouts, Components, Templates, Forms — puts its quota readout and
+ * create button in the page header. A surface that renders a vertical section
+ * rail keeps them in the CARD header, beside the section content the rail
+ * switches between, where they read as the section's rather than the whole
+ * surface's; in the plugin registry the deciding fact is whether the nav item
+ * declares `sections`. Refusing a publish from a section-bearing surface
+ * would enforce that rule one case too far — a hub can have an action that is
+ * genuinely about the whole surface, and this module cannot tell which it is
+ * looking at.
+ */
+export interface PageHeaderActionsContextValue {
+    /**
+     * Renders `actions` in the page header; `null` empties the slot.
+     *
+     * Absent when no provider is mounted, so a surface rendered outside one —
+     * a test harness, a storybook mount — publishes nothing rather than
+     * throwing.
+     */
+    setHeaderActions?: (actions: ReactNode) => void;
+}
+export declare const PageHeaderActionsContext: import("react").Context<PageHeaderActionsContextValue>;
+/** Hook form of {@link PageHeaderActionsContext}. */
+export declare function usePageHeaderActions(): PageHeaderActionsContextValue;
+export interface PageHeaderActionsProps {
+    /** The controls to render in the page header. */
+    children?: ReactNode;
+}
+/**
+ * Publishes its children into the page header, and renders nothing where it
+ * sits.
+ *
+ * Written inside the component that OWNS the controls — the card holding the
+ * listener a quota readout counts from, the state a create button toggles —
+ * so the header and the body read one source. A page that computed the same
+ * numbers a second time to fill its header would be paying for a second
+ * listener over the collection the card is already watching.
+ *
+ * THE SLOT IS EMPTIED ON UNMOUNT, which is what keeps a create button off a
+ * detail route. A list card and a detail card are different components, so
+ * navigating between them unmounts this publisher, and the cleanup runs in
+ * the same commit the incoming surface mounts in — the header never carries
+ * the outgoing surface's actions over the new one.
+ *
+ * One slot, so the last surface to publish holds it. Nothing renders two
+ * surfaces of one page at once, and a slot that concatenated would stack a
+ * hidden surface's buttons beside the visible one's.
+ */
+export declare function PageHeaderActions(props: PageHeaderActionsProps): null;
+export declare namespace PageHeaderActions {
+    var displayName: string;
+}

package/src/lib/app-utils/page-header-actions-context.js

@@ -0,0 +1,58 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ // Same placement rationale as media-picker-context.ts: lives in
+// @aglyn/aglyn without a 'use client' banner so both the console app and
+// relocated feature plugins share one context module.
+import { createContext, useContext, useEffect } from "react";
+export const PageHeaderActionsContext = createContext({});
+PageHeaderActionsContext.displayName = 'PageHeaderActionsContext';
+/** Hook form of {@link PageHeaderActionsContext}. */ export function usePageHeaderActions() {
+    return useContext(PageHeaderActionsContext);
+}
+/**
+ * Publishes its children into the page header, and renders nothing where it
+ * sits.
+ *
+ * Written inside the component that OWNS the controls — the card holding the
+ * listener a quota readout counts from, the state a create button toggles —
+ * so the header and the body read one source. A page that computed the same
+ * numbers a second time to fill its header would be paying for a second
+ * listener over the collection the card is already watching.
+ *
+ * THE SLOT IS EMPTIED ON UNMOUNT, which is what keeps a create button off a
+ * detail route. A list card and a detail card are different components, so
+ * navigating between them unmounts this publisher, and the cleanup runs in
+ * the same commit the incoming surface mounts in — the header never carries
+ * the outgoing surface's actions over the new one.
+ *
+ * One slot, so the last surface to publish holds it. Nothing renders two
+ * surfaces of one page at once, and a slot that concatenated would stack a
+ * hidden surface's buttons beside the visible one's.
+ */ export function PageHeaderActions(props) {
+    const { children } = props;
+    const { setHeaderActions } = usePageHeaderActions();
+    useEffect(()=>{
+        setHeaderActions == null ? void 0 : setHeaderActions(children != null ? children : null);
+        return ()=>setHeaderActions == null ? void 0 : setHeaderActions(null);
+    }, [
+        setHeaderActions,
+        children
+    ]);
+    return null;
+}
+PageHeaderActions.displayName = 'PageHeaderActions';
+
+//# sourceMappingURL=page-header-actions-context.js.map

package/src/lib/app-utils/page-header-actions-context.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/page-header-actions-context.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n// Same placement rationale as media-picker-context.ts: lives in\n// @aglyn/aglyn without a 'use client' banner so both the console app and\n// relocated feature plugins share one context module.\nimport { createContext, useContext, useEffect, type ReactNode } from 'react'\n\n/**\n * Lets any surface publish controls into the PAGE header — the bar carrying\n * the surface icon, title and breadcrumb — from inside the page body.\n *\n * WHY A CONTEXT AND NOT A PROP. A route that owns its own `DashboardLayout`\n * passes `headerRight` directly, which is how Screens, Layouts, Components\n * and Templates put their readout and create button up there. A plugin\n * surface has no such route: the console shell's generic host page owns the\n * layout and renders the surface as a CHILD, and a child cannot set its\n * parent's prop. The console app provides `setHeaderActions` from the layout\n * that owns the header; a surface publishes through {@link PageHeaderActions}\n * and stays free of console-app imports.\n *\n * WHICH HEADER A CONTROL BELONGS IN is a separate question this context\n * deliberately does not answer. A surface with NO section navigation —\n * Screens, Layouts, Components, Templates, Forms — puts its quota readout and\n * create button in the page header. A surface that renders a vertical section\n * rail keeps them in the CARD header, beside the section content the rail\n * switches between, where they read as the section's rather than the whole\n * surface's; in the plugin registry the deciding fact is whether the nav item\n * declares `sections`. Refusing a publish from a section-bearing surface\n * would enforce that rule one case too far — a hub can have an action that is\n * genuinely about the whole surface, and this module cannot tell which it is\n * looking at.\n */\nexport interface PageHeaderActionsContextValue {\n  /**\n   * Renders `actions` in the page header; `null` empties the slot.\n   *\n   * Absent when no provider is mounted, so a surface rendered outside one —\n   * a test harness, a storybook mount — publishes nothing rather than\n   * throwing.\n   */\n  setHeaderActions?: (actions: ReactNode) => void\n}\n\nexport const PageHeaderActionsContext =\n  createContext<PageHeaderActionsContextValue>({})\nPageHeaderActionsContext.displayName = 'PageHeaderActionsContext'\n\n/** Hook form of {@link PageHeaderActionsContext}. */\nexport function usePageHeaderActions(): PageHeaderActionsContextValue {\n  return useContext(PageHeaderActionsContext)\n}\n\nexport interface PageHeaderActionsProps {\n  /** The controls to render in the page header. */\n  children?: ReactNode\n}\n\n/**\n * Publishes its children into the page header, and renders nothing where it\n * sits.\n *\n * Written inside the component that OWNS the controls — the card holding the\n * listener a quota readout counts from, the state a create button toggles —\n * so the header and the body read one source. A page that computed the same\n * numbers a second time to fill its header would be paying for a second\n * listener over the collection the card is already watching.\n *\n * THE SLOT IS EMPTIED ON UNMOUNT, which is what keeps a create button off a\n * detail route. A list card and a detail card are different components, so\n * navigating between them unmounts this publisher, and the cleanup runs in\n * the same commit the incoming surface mounts in — the header never carries\n * the outgoing surface's actions over the new one.\n *\n * One slot, so the last surface to publish holds it. Nothing renders two\n * surfaces of one page at once, and a slot that concatenated would stack a\n * hidden surface's buttons beside the visible one's.\n */\nexport function PageHeaderActions(props: PageHeaderActionsProps): null {\n  const { children } = props\n  const { setHeaderActions } = usePageHeaderActions()\n  useEffect(() => {\n    setHeaderActions?.(children ?? null)\n    return () => setHeaderActions?.(null)\n  }, [setHeaderActions, children])\n  return null\n}\nPageHeaderActions.displayName = 'PageHeaderActions'\n"],"names":["createContext","useContext","useEffect","PageHeaderActionsContext","displayName","usePageHeaderActions","PageHeaderActions","props","children","setHeaderActions"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD,gEAAgE;AAChE,yEAAyE;AACzE,sDAAsD;AACtD,SAASA,aAAa,EAAEC,UAAU,EAAEC,SAAS,QAAwB,QAAO;AAsC5E,OAAO,MAAMC,2BACXH,cAA6C,CAAC,GAAE;AAClDG,yBAAyBC,WAAW,GAAG;AAEvC,mDAAmD,GACnD,OAAO,SAASC;IACd,OAAOJ,WAAWE;AACpB;AAOA;;;;;;;;;;;;;;;;;;;CAmBC,GACD,OAAO,SAASG,kBAAkBC,KAA6B;IAC7D,MAAM,EAAEC,QAAQ,EAAE,GAAGD;IACrB,MAAM,EAAEE,gBAAgB,EAAE,GAAGJ;IAC7BH,UAAU;QACRO,oCAAAA,iBAAmBD,mBAAAA,WAAY;QAC/B,OAAO,IAAMC,oCAAAA,iBAAmB;IAClC,GAAG;QAACA;QAAkBD;KAAS;IAC/B,OAAO;AACT;AACAF,kBAAkBF,WAAW,GAAG"}

package/src/lib/app-utils/page-header-record-context.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Lets a surface name the RECORD it is showing, for the page header and the
+ * breadcrumb trail — the sibling of `PageHeaderActions`, which does the same
+ * for the header's controls.
+ *
+ * WHAT A RECORD DETAIL PAGE OWES ITS READER. The heading of a page about one
+ * thing names that thing, and the trail ends on it. A detail page whose
+ * heading reads `Forms` says only which list the reader came from, which the
+ * breadcrumb above it already said, and it reads identically on every row of
+ * that list — so two tabs open on two different forms are one string.
+ *
+ * WHY A CONTEXT AND NOT A PROP, for the same reason the actions seam is one:
+ * a route that owns its `DashboardLayout` passes `header` and
+ * `breadcrumbItems` directly, and the detail pages that do — Screens,
+ * Components, Layouts, Templates, entries — already name their record that
+ * way and never touch this. A PLUGIN surface has no such route. The console
+ * shell's generic host page owns the layout, builds the heading from the nav
+ * item's label and the trail from the surface and section, and renders the
+ * surface as a CHILD; a child cannot set its parent's props. So the record
+ * arrives here, published by whichever descendant loaded it.
+ *
+ * WHAT IT REPLACES, precisely: the heading's text and the heading's SECTION
+ * suffix, and it appends one crumb. The icon stays the surface's — a form is
+ * still a form — and every crumb above it stays exactly as the route built
+ * it, so the trail still walks back through the surface and the section the
+ * record sits under.
+ */
+export interface PageHeaderRecordValue {
+    /**
+     * The record's own name, which becomes the page heading and the last crumb.
+     *
+     * Empty and absent both mean "not yet": a surface calls this with whatever
+     * it has this render, and a half-loaded name would flash the heading
+     * through a wrong string on the way to the right one. Until a name arrives
+     * the route's own heading stands, which already names the surface.
+     */
+    title?: string;
+}
+export interface PageHeaderRecordContextValue {
+    /**
+     * Names the record the page is about; `null` clears it.
+     *
+     * Absent when no provider is mounted, so a surface rendered outside one —
+     * a test harness, a storybook mount — publishes nothing rather than
+     * throwing.
+     */
+    setHeaderRecord?: (record: PageHeaderRecordValue | null) => void;
+}
+export declare const PageHeaderRecordContext: import("react").Context<PageHeaderRecordContextValue>;
+/** Hook form of {@link PageHeaderRecordContext}. */
+export declare function usePageHeaderRecord(): PageHeaderRecordContextValue;
+export type PageHeaderRecordProps = PageHeaderRecordValue;
+/**
+ * Names the page's record in the header and the trail, and renders nothing
+ * where it sits.
+ *
+ * Written inside the component that LOADED the record, so the heading and the
+ * body read one document. A shell that resolved the name a second time to
+ * fill its own header would be paying for a second read of a document the
+ * page is already holding — and would answer differently while the two were
+ * in flight.
+ *
+ * THE SLOT IS EMPTIED ON UNMOUNT, which is what keeps one record's name off
+ * the next page. A list and a detail view are different components, so
+ * navigating between them unmounts this publisher and the cleanup runs in the
+ * same commit the incoming surface mounts in.
+ *
+ * Published from a PRIMITIVE rather than an object, deliberately: the effect's
+ * dependency is the string itself, so a surface that re-renders while its data
+ * settles publishes once per actual change rather than once per render.
+ *
+ * The record is named, never LINKED. `BreadcrumbsComponent` renders its last
+ * crumb as text whatever it is handed, because the level the reader is
+ * standing on is a label rather than a way to get there — so an href here
+ * would be an option that silently does nothing.
+ */
+export declare function PageHeaderRecord(props: PageHeaderRecordProps): null;
+export declare namespace PageHeaderRecord {
+    var displayName: string;
+}

package/src/lib/app-utils/page-header-record-context.js

@@ -0,0 +1,64 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ // Same placement rationale as page-header-actions-context.ts: lives in
+// @aglyn/aglyn without a 'use client' banner so both the console app and
+// relocated feature plugins share one context module.
+import { createContext, useContext, useEffect } from "react";
+export const PageHeaderRecordContext = createContext({});
+PageHeaderRecordContext.displayName = 'PageHeaderRecordContext';
+/** Hook form of {@link PageHeaderRecordContext}. */ export function usePageHeaderRecord() {
+    return useContext(PageHeaderRecordContext);
+}
+/**
+ * Names the page's record in the header and the trail, and renders nothing
+ * where it sits.
+ *
+ * Written inside the component that LOADED the record, so the heading and the
+ * body read one document. A shell that resolved the name a second time to
+ * fill its own header would be paying for a second read of a document the
+ * page is already holding — and would answer differently while the two were
+ * in flight.
+ *
+ * THE SLOT IS EMPTIED ON UNMOUNT, which is what keeps one record's name off
+ * the next page. A list and a detail view are different components, so
+ * navigating between them unmounts this publisher and the cleanup runs in the
+ * same commit the incoming surface mounts in.
+ *
+ * Published from a PRIMITIVE rather than an object, deliberately: the effect's
+ * dependency is the string itself, so a surface that re-renders while its data
+ * settles publishes once per actual change rather than once per render.
+ *
+ * The record is named, never LINKED. `BreadcrumbsComponent` renders its last
+ * crumb as text whatever it is handed, because the level the reader is
+ * standing on is a label rather than a way to get there — so an href here
+ * would be an option that silently does nothing.
+ */ export function PageHeaderRecord(props) {
+    const { title } = props;
+    const { setHeaderRecord } = usePageHeaderRecord();
+    useEffect(()=>{
+        setHeaderRecord == null ? void 0 : setHeaderRecord(title ? {
+            title
+        } : null);
+        return ()=>setHeaderRecord == null ? void 0 : setHeaderRecord(null);
+    }, [
+        setHeaderRecord,
+        title
+    ]);
+    return null;
+}
+PageHeaderRecord.displayName = 'PageHeaderRecord';
+
+//# sourceMappingURL=page-header-record-context.js.map

package/src/lib/app-utils/page-header-record-context.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/page-header-record-context.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n// Same placement rationale as page-header-actions-context.ts: lives in\n// @aglyn/aglyn without a 'use client' banner so both the console app and\n// relocated feature plugins share one context module.\nimport { createContext, useContext, useEffect } from 'react'\n\n/**\n * Lets a surface name the RECORD it is showing, for the page header and the\n * breadcrumb trail — the sibling of `PageHeaderActions`, which does the same\n * for the header's controls.\n *\n * WHAT A RECORD DETAIL PAGE OWES ITS READER. The heading of a page about one\n * thing names that thing, and the trail ends on it. A detail page whose\n * heading reads `Forms` says only which list the reader came from, which the\n * breadcrumb above it already said, and it reads identically on every row of\n * that list — so two tabs open on two different forms are one string.\n *\n * WHY A CONTEXT AND NOT A PROP, for the same reason the actions seam is one:\n * a route that owns its `DashboardLayout` passes `header` and\n * `breadcrumbItems` directly, and the detail pages that do — Screens,\n * Components, Layouts, Templates, entries — already name their record that\n * way and never touch this. A PLUGIN surface has no such route. The console\n * shell's generic host page owns the layout, builds the heading from the nav\n * item's label and the trail from the surface and section, and renders the\n * surface as a CHILD; a child cannot set its parent's props. So the record\n * arrives here, published by whichever descendant loaded it.\n *\n * WHAT IT REPLACES, precisely: the heading's text and the heading's SECTION\n * suffix, and it appends one crumb. The icon stays the surface's — a form is\n * still a form — and every crumb above it stays exactly as the route built\n * it, so the trail still walks back through the surface and the section the\n * record sits under.\n */\nexport interface PageHeaderRecordValue {\n  /**\n   * The record's own name, which becomes the page heading and the last crumb.\n   *\n   * Empty and absent both mean \"not yet\": a surface calls this with whatever\n   * it has this render, and a half-loaded name would flash the heading\n   * through a wrong string on the way to the right one. Until a name arrives\n   * the route's own heading stands, which already names the surface.\n   */\n  title?: string\n}\n\nexport interface PageHeaderRecordContextValue {\n  /**\n   * Names the record the page is about; `null` clears it.\n   *\n   * Absent when no provider is mounted, so a surface rendered outside one —\n   * a test harness, a storybook mount — publishes nothing rather than\n   * throwing.\n   */\n  setHeaderRecord?: (record: PageHeaderRecordValue | null) => void\n}\n\nexport const PageHeaderRecordContext =\n  createContext<PageHeaderRecordContextValue>({})\nPageHeaderRecordContext.displayName = 'PageHeaderRecordContext'\n\n/** Hook form of {@link PageHeaderRecordContext}. */\nexport function usePageHeaderRecord(): PageHeaderRecordContextValue {\n  return useContext(PageHeaderRecordContext)\n}\n\nexport type PageHeaderRecordProps = PageHeaderRecordValue\n\n/**\n * Names the page's record in the header and the trail, and renders nothing\n * where it sits.\n *\n * Written inside the component that LOADED the record, so the heading and the\n * body read one document. A shell that resolved the name a second time to\n * fill its own header would be paying for a second read of a document the\n * page is already holding — and would answer differently while the two were\n * in flight.\n *\n * THE SLOT IS EMPTIED ON UNMOUNT, which is what keeps one record's name off\n * the next page. A list and a detail view are different components, so\n * navigating between them unmounts this publisher and the cleanup runs in the\n * same commit the incoming surface mounts in.\n *\n * Published from a PRIMITIVE rather than an object, deliberately: the effect's\n * dependency is the string itself, so a surface that re-renders while its data\n * settles publishes once per actual change rather than once per render.\n *\n * The record is named, never LINKED. `BreadcrumbsComponent` renders its last\n * crumb as text whatever it is handed, because the level the reader is\n * standing on is a label rather than a way to get there — so an href here\n * would be an option that silently does nothing.\n */\nexport function PageHeaderRecord(props: PageHeaderRecordProps): null {\n  const { title } = props\n  const { setHeaderRecord } = usePageHeaderRecord()\n  useEffect(() => {\n    setHeaderRecord?.(title ? { title } : null)\n    return () => setHeaderRecord?.(null)\n  }, [setHeaderRecord, title])\n  return null\n}\nPageHeaderRecord.displayName = 'PageHeaderRecord'\n"],"names":["createContext","useContext","useEffect","PageHeaderRecordContext","displayName","usePageHeaderRecord","PageHeaderRecord","props","title","setHeaderRecord"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD,uEAAuE;AACvE,yEAAyE;AACzE,sDAAsD;AACtD,SAASA,aAAa,EAAEC,UAAU,EAAEC,SAAS,QAAQ,QAAO;AAoD5D,OAAO,MAAMC,0BACXH,cAA4C,CAAC,GAAE;AACjDG,wBAAwBC,WAAW,GAAG;AAEtC,kDAAkD,GAClD,OAAO,SAASC;IACd,OAAOJ,WAAWE;AACpB;AAIA;;;;;;;;;;;;;;;;;;;;;;;CAuBC,GACD,OAAO,SAASG,iBAAiBC,KAA4B;IAC3D,MAAM,EAAEC,KAAK,EAAE,GAAGD;IAClB,MAAM,EAAEE,eAAe,EAAE,GAAGJ;IAC5BH,UAAU;QACRO,mCAAAA,gBAAkBD,QAAQ;YAAEA;QAAM,IAAI;QACtC,OAAO,IAAMC,mCAAAA,gBAAkB;IACjC,GAAG;QAACA;QAAiBD;KAAM;IAC3B,OAAO;AACT;AACAF,iBAAiBF,WAAW,GAAG"}

package/src/lib/app-utils/page-markdown.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** The node shape this serializer reads; keeps callers free of the full type. */
+export interface PageMarkdownNode {
+    componentId?: string;
+    props?: Record<string, unknown> | null;
+    /** Normalized documents carry child IDS; this never reads a denormalized tree. */
+    nodes?: unknown;
+}
+/** A flat node map keyed by node id — exactly what the page route already holds. */
+export type PageMarkdownNodes = Record<string, PageMarkdownNode>;
+/**
+ * Whether a node is navigation rather than content: a chrome component, or
+ * an element its author declared `nav`, `header` or `footer`. Exported so a
+ * reader of a page's CONTENT — the SEO audit's heading and image scan
+ * (AGL-2910) — skips exactly what this serializer skips.
+ */
+export declare function isPageChromeNode(node: PageMarkdownNode | undefined): boolean;
+/**
+ * The heading level a text node publishes, or 0 for body copy.
+ *
+ * `component` wins over `variant` because they answer different questions and
+ * the platform lets them disagree: `variant` is the type STYLE (what size it is
+ * drawn at) and `component` is the ELEMENT (what it means). An author who set a
+ * hero line to look like an h1 but render as a `p` said it is not a heading,
+ * and the Markdown has to agree with the HTML or the two documents describe
+ * different pages.
+ */
+export declare function headingLevelOf(props: Record<string, unknown> | null | undefined): number;
+/**
+ * Escape the Markdown control characters that would otherwise re-parse.
+ *
+ * Only the characters that START a construct at the position they can occur in:
+ * a leading `#`, `>`, `-`, `+` or `1.` on its own line, and the emphasis,
+ * backtick and bracket characters anywhere. Escaping more than that produces
+ * output littered with backslashes, which is worse to read and worse to embed
+ * than the rare false heading it prevents.
+ */
+export declare function escapeMarkdownText(value: string): string;
+/** Resolution context for values that are stored as references, not URLs. */
+export interface PageMarkdownContext {
+    /** Site origin, for absolutizing media and site-relative links. */
+    origin?: string | null;
+    /** Host id, so a restricted org asset resolves for the site rendering it. */
+    hostId?: string;
+    /**
+     * The routing map screen links resolve against (`screenRoutes`), and the
+     * link references in authored markdown with them (AGL-3118).
+     */
+    screenRoutes?: Record<string, string> | null;
+}
+/**
+ * The node the document's content begins at.
+ *
+ * The `main` landmark first — `stampDocumentLandmark` puts it on the layout
+ * slot or the screen root — then the layout slot by component id, then the
+ * document root. Each fallback is wider than the last, so a tree that is
+ * missing the marker still serializes rather than returning nothing.
+ */
+export declare function pageContentRootId(nodes: PageMarkdownNodes | null | undefined, rootId?: string): string | null;
+/** What a Markdown page carries above its body. */
+export interface PageMarkdownFrontMatter {
+    /** The `# ` heading. The page's own title, never the site's. */
+    title?: string;
+    /** The meta description, emitted as the summary blockquote. */
+    description?: string;
+    /** Canonical absolute URL, emitted as the source line. */
+    canonicalUrl?: string;
+    /** ISO-8601 publication date, for a content entry. */
+    publishedAt?: string;
+    /** ISO-8601 last-modified date, for a content entry. */
+    updatedAt?: string;
+    /** Byline, for a content entry. */
+    author?: string;
+}
+/**
+ * The whole Markdown representation of a page.
+ *
+ * @param body - already-Markdown body to use INSTEAD of walking nodes; the
+ *   content-entry case, where the stored body is markdown-lite source and
+ *   round-tripping it through the node tree could only lose fidelity.
+ */
+export declare function buildPageMarkdown(options: {
+    nodes?: PageMarkdownNodes | null;
+    rootId?: string;
+    body?: string | null;
+    front?: PageMarkdownFrontMatter;
+    context?: PageMarkdownContext;
+}): string;