@nxisai/agent-harness 0.4.0 → 0.5.0

package/dist/harness/tools/site-nav.d.ts

@@ -0,0 +1,168 @@
+/**
+ * The site as a graph the agent can walk.
+ *
+ * A page publishes one breadcrumb trail: the path from the site's root down to
+ * itself. Every page publishes its own, so the trails together *are* the
+ * hierarchy — inverted, each page gains the sections above it, the pages beside
+ * it, and the pages under it. A page's `significantLink` and `relatedLink` add
+ * the cross-links a hierarchy cannot express: a listing pointing at its service
+ * area, a guide pointing at the form it explains.
+ *
+ * Link names come free. A link usually points at a page the site also has a
+ * record for, so the name shown is that page's own name rather than anchor text
+ * nobody extracted. A link to a page with no record keeps its address.
+ *
+ * Nothing here leaves the origin: a trail level or link on another host is
+ * dropped when the graph is built, not when it is walked.
+ *
+ * @module
+ */
+import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { McpServerInfo, ModelContext, ModelContextTool } from '../../types.js';
+import type { SitePage } from './site-pages.js';
+/** One level of a page's trail. The last is the page itself, and names no URL. */
+export interface TrailLevel {
+    /** What the site calls this level. */
+    name: string;
+    /** Absolute URL, on this origin. Absent on the page's own level. */
+    url?: string;
+}
+/** A page's path from the root, root first. */
+export interface SiteTrail {
+    /** The page whose trail this is, when it can be told from the record's id. */
+    page?: string;
+    levels: TrailLevel[];
+}
+/** Somewhere the agent can go from here, and what to call it. */
+export interface NavLink {
+    url: string;
+    name: string;
+}
+/** What a page is surrounded by. */
+export interface PageNav {
+    /** The sections above it, root first, not including the page itself. */
+    ancestors: NavLink[];
+    /** Pages under the same parent, excluding the page itself. */
+    siblings: NavLink[];
+    /** Pages whose parent is this page. */
+    children: NavLink[];
+    /** Pages this page points a reader at. */
+    links: NavLink[];
+}
+/** The whole site, ready to answer "where am I and what is near me". */
+export interface SiteNav {
+    /** The site's origin, so a graph can be rebuilt from itself. */
+    origin: string;
+    /** Parent page URL, by page URL. */
+    parents: Map<string, string>;
+    /** The trail for each page it was published for. */
+    trails: Map<string, TrailLevel[]>;
+    /** Everything a page points at, by page URL. */
+    links: Map<string, string[]>;
+    /** Every page known, by URL, for naming. */
+    pages: SitePage[];
+}
+/**
+ * Read one typed-retrieval record as a trail.
+ *
+ * @param raw - A `BreadcrumbList` record.
+ * @param origin - The site's origin; levels elsewhere are dropped.
+ * @returns The trail, or null when the record is not one or carries no levels.
+ */
+export declare function parseTrail(raw: unknown, origin: string): SiteTrail | null;
+/**
+ * The graph: who is above whom, and what points at what.
+ *
+ * A trail's parent is its last level with a URL that is not the page itself —
+ * the section directly above. A page with a one-level trail (itself) has no
+ * parent, which is what the root looks like.
+ *
+ * @param pages - The site's pages, for names.
+ * @param trails - Its trails.
+ * @param origin - The site's origin.
+ */
+export declare function buildNav(pages: SitePage[], trails: SiteTrail[], origin: string): SiteNav;
+/**
+ * Fold trails into a graph already in someone's hands.
+ *
+ * The tools are built at connect and hold the graph; the trails may arrive
+ * later, because fetching them is a read the site's rate limit counts. Mutating
+ * in place is what lets a tool built before the fetch answer after it.
+ */
+export declare function applyTrails(nav: SiteNav, trails: SiteTrail[]): SiteNav;
+/** What a URL is called: the page's own name, else the last word of its path. */
+export declare function nameOf(url: string, nav: SiteNav): string;
+/** The page that a URL is under, if the graph knows. */
+export declare function parentOf(url: string, nav: SiteNav): string | undefined;
+/**
+ * Where the agent can go from a page: up, sideways, down, and out along its
+ * own links.
+ *
+ * @param href - The page to place. Defaults to the browser's.
+ */
+export declare function navFor(nav: SiteNav, href: string): PageNav;
+/** Options for {@link loadSiteTrails}. */
+export interface SiteTrailsOptions {
+    /** The origin trails must belong to. Defaults to the page's own. */
+    origin?: string;
+    /** Where the list is cached between page loads. Defaults to `sessionStorage`; null disables. */
+    storage?: Storage | null;
+    /** How long a cached list is reused, in milliseconds. Defaults to ten minutes. */
+    ttlMs?: number;
+    /** The clock, for tests. */
+    now?: () => number;
+}
+/**
+ * Every breadcrumb trail on the site.
+ *
+ * One query, cached in the tab like the page list, because the hierarchy is the
+ * same on every page of it.
+ *
+ * @throws When the query fails. The caller decides whether that matters.
+ */
+export declare function loadSiteTrails(client: Client, info: Pick<McpServerInfo, 'endpoint'>, opts?: SiteTrailsOptions): Promise<SiteTrail[]>;
+/** The tool's registered name. */
+export declare const PAGE_LINKS_TOOL = "page_links";
+/**
+ * What the agent can say about where it is.
+ *
+ * Read rather than navigation: "what else is in this section" is a question,
+ * and answering it by opening a page would be answering a different one. The
+ * names it returns are the names {@link buildOpenPageTool} accepts, so the
+ * model can follow one with the other.
+ *
+ * Always answers. "Where am I" is answerable from the address bar alone, so a
+ * site that publishes no trails and links nothing still gets the page it is on
+ * — an agent that cannot say that reads as an agent with no idea where it is.
+ */
+export declare function describeNav(nav: SiteNav, href: string): string;
+/** Options for the page-links tool: where the visitor is, and how the graph fills in. */
+export interface PageLinksOptions {
+    /** The current page URL. Defaults to the browser's. Read when the tool runs. */
+    href?: () => string;
+    /**
+     * Fetch the site's trails, if they have not been fetched yet.
+     *
+     * Awaited when the tool runs rather than at connect, because the fetch is a
+     * read and a site's rate limit counts reads. Answering "where am I" is what
+     * makes that read worth spending.
+     */
+    loadNav?: () => Promise<SiteNav>;
+}
+/**
+ * Build the tool that reports where this page sits and what it leads to.
+ *
+ * @param nav - The site's graph.
+ */
+export declare function buildPageLinksTool(nav: SiteNav, opts?: PageLinksOptions): ModelContextTool;
+/**
+ * Register the page-links tool, unless the registry already holds one.
+ *
+ * Registered whatever the site publishes. It was once gated on the site having
+ * trails or links, which withheld the tool from exactly the sites where "where
+ * am I" is the only question it could answer.
+ *
+ * @returns Whether it was registered.
+ */
+export declare function registerPageLinksTool(mc: ModelContext, nav: SiteNav, opts?: PageLinksOptions): Promise<boolean>;
+//# sourceMappingURL=site-nav.d.ts.map

package/dist/harness/tools/site-nav.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"site-nav.d.ts","sourceRoot":"","sources":["../../../src/harness/tools/site-nav.ts"],"names":[],"mappings":"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"}

package/dist/harness/tools/site-nav.js

@@ -0,0 +1,316 @@
+import { queryTypedRecords, samePage } from './site-actions.js';
+const SCHEMA_NS = 'https://schema.org/';
+const CACHE_TTL_MS = 10 * 60 * 1000;
+const CACHE_PREFIX = 'nxis:site-trails:v1:';
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const schemaValue = (o, prop) => o[prop] ?? o[SCHEMA_NS + prop];
+const str = (v) => typeof v === 'string' && v.trim() ? v.trim() : undefined;
+const bareType = (t) => t.replace(/^.*[/#]/, '');
+const types = (o) => (Array.isArray(o['@type']) ? o['@type'] : [o['@type']])
+    .filter((t) => typeof t === 'string')
+    .map(bareType);
+/** A URL resolved against the origin, if it stays on it. */
+function onOrigin(raw, origin) {
+    const s = str(raw) ?? (isObj(raw) ? str(raw['@id']) ?? str(schemaValue(raw, 'url')) : undefined);
+    if (!s)
+        return undefined;
+    try {
+        const url = new URL(s, origin);
+        url.hash = '';
+        return url.origin === new URL(origin).origin ? url.href : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The page a trail was published for: its record's id, without the fragment. */
+function pageOfTrail(raw, origin) {
+    const id = str(raw['@id']);
+    if (!id || !id.includes('#'))
+        return undefined;
+    return onOrigin(id, origin);
+}
+/**
+ * Read one typed-retrieval record as a trail.
+ *
+ * @param raw - A `BreadcrumbList` record.
+ * @param origin - The site's origin; levels elsewhere are dropped.
+ * @returns The trail, or null when the record is not one or carries no levels.
+ */
+export function parseTrail(raw, origin) {
+    if (!isObj(raw) || !types(raw).includes('BreadcrumbList'))
+        return null;
+    const rawLevels = schemaValue(raw, 'itemListElement');
+    const list = Array.isArray(rawLevels) ? rawLevels : rawLevels ? [rawLevels] : [];
+    const levels = list
+        .filter(isObj)
+        .map((item) => {
+        const position = Number(schemaValue(item, 'position') ?? Number.MAX_SAFE_INTEGER);
+        const name = str(schemaValue(item, 'name'));
+        const url = onOrigin(schemaValue(item, 'item'), origin);
+        return { position, name, url };
+    })
+        .filter((l) => !!l.name)
+        .sort((a, b) => a.position - b.position)
+        .map(({ name, url }) => (url ? { name, url } : { name }));
+    if (!levels.length)
+        return null;
+    const page = pageOfTrail(raw, origin);
+    return page ? { page, levels } : { levels };
+}
+/**
+ * The graph: who is above whom, and what points at what.
+ *
+ * A trail's parent is its last level with a URL that is not the page itself —
+ * the section directly above. A page with a one-level trail (itself) has no
+ * parent, which is what the root looks like.
+ *
+ * @param pages - The site's pages, for names.
+ * @param trails - Its trails.
+ * @param origin - The site's origin.
+ */
+export function buildNav(pages, trails, origin) {
+    const parents = new Map();
+    const byPage = new Map();
+    const links = new Map();
+    for (const trail of trails) {
+        // A trail with no id to place it still names its page in its last level.
+        const page = trail.page ?? trail.levels[trail.levels.length - 1]?.url;
+        if (!page)
+            continue;
+        byPage.set(page, trail.levels);
+        const above = trail.levels.filter((l) => l.url && !samePage(l.url, page));
+        const parent = above[above.length - 1]?.url;
+        if (parent)
+            parents.set(page, parent);
+    }
+    for (const page of pages) {
+        const out = (page.links ?? [])
+            .map((l) => onOrigin(l, origin))
+            .filter((l) => !!l && !samePage(l, page.url));
+        if (out.length)
+            links.set(page.url, [...new Set(out)]);
+    }
+    return { origin, parents, trails: byPage, links, pages };
+}
+/**
+ * Fold trails into a graph already in someone's hands.
+ *
+ * The tools are built at connect and hold the graph; the trails may arrive
+ * later, because fetching them is a read the site's rate limit counts. Mutating
+ * in place is what lets a tool built before the fetch answer after it.
+ */
+export function applyTrails(nav, trails) {
+    const fresh = buildNav(nav.pages, trails, nav.origin);
+    nav.parents.clear();
+    for (const [page, parent] of fresh.parents)
+        nav.parents.set(page, parent);
+    nav.trails.clear();
+    for (const [page, levels] of fresh.trails)
+        nav.trails.set(page, levels);
+    return nav;
+}
+/** What a URL is called: the page's own name, else the last word of its path. */
+export function nameOf(url, nav) {
+    const known = nav.pages.find((p) => samePage(p.url, url));
+    if (known)
+        return known.name;
+    const level = [...nav.trails.values()].flat().find((l) => l.url && samePage(l.url, url));
+    if (level)
+        return level.name;
+    try {
+        const slug = new URL(url).pathname.split('/').filter(Boolean).pop() ?? '';
+        return slug.replace(/\.\w+$/, '').replace(/[-_]+/g, ' ') || 'home';
+    }
+    catch {
+        return url;
+    }
+}
+/** The page that a URL is under, if the graph knows. */
+export function parentOf(url, nav) {
+    const key = [...nav.parents.keys()].find((p) => samePage(p, url));
+    return key ? nav.parents.get(key) : undefined;
+}
+/**
+ * Where the agent can go from a page: up, sideways, down, and out along its
+ * own links.
+ *
+ * @param href - The page to place. Defaults to the browser's.
+ */
+export function navFor(nav, href) {
+    const link = (url) => ({ url, name: nameOf(url, nav) });
+    const ancestors = [];
+    let up = parentOf(href, nav);
+    // A cycle in published trails would otherwise walk forever.
+    while (up && ancestors.length < 8 && !ancestors.some((a) => samePage(a.url, up))) {
+        ancestors.unshift(link(up));
+        up = parentOf(up, nav);
+    }
+    const parent = parentOf(href, nav);
+    const siblings = parent
+        ? [...nav.parents.entries()]
+            .filter(([page, under]) => samePage(under, parent) && !samePage(page, href))
+            .map(([page]) => link(page))
+        : [];
+    const children = [...nav.parents.entries()]
+        .filter(([, under]) => samePage(under, href))
+        .map(([page]) => link(page));
+    const own = [...nav.links.keys()].find((p) => samePage(p, href));
+    const links = (own ? (nav.links.get(own) ?? []) : []).map(link);
+    return { ancestors, siblings, children, links };
+}
+function defaultStorage() {
+    try {
+        return typeof sessionStorage === 'undefined' ? null : sessionStorage;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Every breadcrumb trail on the site.
+ *
+ * One query, cached in the tab like the page list, because the hierarchy is the
+ * same on every page of it.
+ *
+ * @throws When the query fails. The caller decides whether that matters.
+ */
+export async function loadSiteTrails(client, info, opts = {}) {
+    const origin = opts.origin ?? location.origin;
+    const storage = opts.storage === undefined ? defaultStorage() : opts.storage;
+    const now = (opts.now ?? Date.now)();
+    const key = CACHE_PREFIX + info.endpoint;
+    try {
+        const entry = JSON.parse(storage?.getItem(key) || 'null');
+        const fresh = entry && now - entry.fetchedAt <= (opts.ttlMs ?? CACHE_TTL_MS) && entry.fetchedAt <= now;
+        if (fresh && Array.isArray(entry.trails))
+            return entry.trails;
+    }
+    catch {
+        // A corrupt entry is a refetch.
+    }
+    const trails = (await queryTypedRecords(client, 'BreadcrumbList'))
+        .map((r) => parseTrail(r, origin))
+        .filter((t) => t !== null);
+    try {
+        storage?.setItem(key, JSON.stringify({ fetchedAt: now, trails }));
+    }
+    catch {
+        // Full or blocked storage costs a refetch on the next page, nothing more.
+    }
+    return trails;
+}
+/** The tool's registered name. */
+export const PAGE_LINKS_TOOL = 'page_links';
+/** Where a listing stops, so an answer stays readable. */
+const MAX_LISTED = 10;
+const list = (label, links) => links.length ? [`${label}: ${links.slice(0, MAX_LISTED).map((l) => l.name).join(', ')}`] : [];
+/**
+ * What the agent can say about where it is.
+ *
+ * Read rather than navigation: "what else is in this section" is a question,
+ * and answering it by opening a page would be answering a different one. The
+ * names it returns are the names {@link buildOpenPageTool} accepts, so the
+ * model can follow one with the other.
+ *
+ * Always answers. "Where am I" is answerable from the address bar alone, so a
+ * site that publishes no trails and links nothing still gets the page it is on
+ * — an agent that cannot say that reads as an agent with no idea where it is.
+ */
+export function describeNav(nav, href) {
+    const { ancestors, siblings, children, links } = navFor(nav, href);
+    const trail = [...nav.trails.entries()].find(([page]) => samePage(page, href))?.[1];
+    const known = nav.pages.length;
+    const lines = [
+        `You are on ${nameOf(href, nav)} (${pathOf(href, nav)})` +
+            (known ? `, one of ${known} page${known === 1 ? '' : 's'} on this site.` : '.'),
+        ...(trail?.length ? [`Trail: ${trail.map((l) => l.name).join(' › ')}`] : []),
+        ...list('Above', ancestors),
+        ...list('Also in this section', siblings),
+        ...list('Under this page', children),
+        ...list('Linked from here', links),
+    ];
+    if (lines.length > 1)
+        return lines.join('\n');
+    const elsewhere = nav.pages.filter((p) => !samePage(p.url, href)).slice(0, MAX_LISTED);
+    return elsewhere.length
+        ? `${lines[0]} This site publishes no sections, so there is nothing above or beside it. Other pages: ${elsewhere
+            .map((p) => p.name)
+            .join(', ')}.`
+        : `${lines[0]} Nothing else on the site links to or from it.`;
+}
+/**
+ * The address as a visitor reads it, which is what "what page is this" asks for.
+ *
+ * The path of the page the site actually publishes, when one matches. A query a surface put there
+ * — `?surface=window`, `?open=1` — belongs to this tab, not to the site: nothing is indexed under
+ * it, and quoting it back invites the model to ask for a page by an address no record carries.
+ */
+function pathOf(href, nav) {
+    const known = nav.pages.find((p) => samePage(p.url, href));
+    try {
+        // A published page's own query is part of its address; the tab's is not, and with no record to
+        // say otherwise, the path alone is the page.
+        if (known) {
+            const url = new URL(known.url);
+            return url.pathname + url.search;
+        }
+        return new URL(href).pathname;
+    }
+    catch {
+        return known?.url ?? href;
+    }
+}
+/**
+ * Build the tool that reports where this page sits and what it leads to.
+ *
+ * @param nav - The site's graph.
+ */
+export function buildPageLinksTool(nav, opts = {}) {
+    return {
+        name: PAGE_LINKS_TOOL,
+        description: 'Where the visitor is right now and what this page leads to: the page they are on, the sections ' +
+            'above it, the other pages in its section, the pages under it, and the pages it links to. Use for ' +
+            '"where am I", "what page is this" and "what else is here", and before offering to take them somewhere.',
+        inputSchema: { type: 'object', properties: {} },
+        annotations: { readOnlyHint: true },
+        execute: async () => {
+            const filled = (await opts.loadNav?.().catch(() => nav)) ?? nav;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: describeNav(filled, opts.href?.() ?? (typeof location === 'undefined' ? '' : location.href)),
+                    },
+                ],
+            };
+        },
+    };
+}
+/**
+ * Register the page-links tool, unless the registry already holds one.
+ *
+ * Registered whatever the site publishes. It was once gated on the site having
+ * trails or links, which withheld the tool from exactly the sites where "where
+ * am I" is the only question it could answer.
+ *
+ * @returns Whether it was registered.
+ */
+export async function registerPageLinksTool(mc, nav, opts = {}) {
+    try {
+        if ((await mc.getTools()).some((t) => t.name === PAGE_LINKS_TOOL))
+            return false;
+    }
+    catch {
+        // A registry that cannot list may still register.
+    }
+    try {
+        await mc.registerTool(buildPageLinksTool(nav, opts));
+        return true;
+    }
+    catch (err) {
+        console.warn(`[nxis-mcp] could not register ${PAGE_LINKS_TOOL}:`, err);
+        return false;
+    }
+}
+//# sourceMappingURL=site-nav.js.map

package/dist/harness/tools/site-nav.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"site-nav.js","sourceRoot":"","sources":["../../../src/harness/tools/site-nav.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAGhE,MAAM,SAAS,GAAG,qBAAqB,CAAC;AACxC,MAAM,YAAY,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AACpC,MAAM,YAAY,GAAG,sBAAsB,CAAC;AAmD5C,MAAM,KAAK,GAAG,CAAC,CAAU,EAAY,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAC1F,MAAM,WAAW,GAAG,CAAC,CAAM,EAAE,IAAY,EAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;AACtF,MAAM,GAAG,GAAG,CAAC,CAAU,EAAsB,EAAE,CAC7C,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3D,MAAM,QAAQ,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;AAEjE,MAAM,KAAK,GAAG,CAAC,CAAM,EAAY,EAAE,CACjC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;KACpD,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;KACjD,GAAG,CAAC,QAAQ,CAAC,CAAC;AAEnB,4DAA4D;AAC5D,SAAS,QAAQ,CAAC,GAAY,EAAE,MAAc;IAC5C,MAAM,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,GAAG,CAAC,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACjG,IAAI,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACzB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;QAC/B,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC;QACd,OAAO,GAAG,CAAC,MAAM,KAAK,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IACtE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,iFAAiF;AACjF,SAAS,WAAW,CAAC,GAAQ,EAAE,MAAc;IAC3C,MAAM,EAAE,GAAG,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3B,IAAI,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC/C,OAAO,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,GAAY,EAAE,MAAc;IACrD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,gBAAgB,CAAC;QAAE,OAAO,IAAI,CAAC;IACvE,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC;IACtD,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACjF,MAAM,MAAM,GAAG,IAAI;SAChB,MAAM,CAAC,KAAK,CAAC;SACb,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACZ,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,gBAAgB,CAAC,CAAC;QAClF,MAAM,IAAI,GAAG,GAAG,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QAC5C,MAAM,GAAG,GAAG,QAAQ,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;QACxD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;IACjC,CAAC,CAAC;SACD,MAAM,CAAC,CAAC,CAAC,EAAoE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;SACzF,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC;SACvC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC5D,IAAI,CAAC,MAAM,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAChC,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACtC,OAAO,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAiB,EAAE,MAAmB,EAAE,MAAc;IAC7E,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,MAAM,MAAM,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC/C,MAAM,KAAK,GAAG,IAAI,GAAG,EAAoB,CAAC;IAE1C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,yEAAyE;QACzE,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC;QACtE,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAC/B,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;QAC1E,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC;QAC5C,IAAI,MAAM;YAAE,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;aAC3B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;aAC/B,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC7D,IAAI,GAAG,CAAC,MAAM;YAAE,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACzD,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC3D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,GAAY,EAAE,MAAmB;IAC3D,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtD,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACpB,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO;QAAE,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC1E,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACnB,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM;QAAE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACxE,OAAO,GAAG,CAAC;AACb,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,MAAM,CAAC,GAAW,EAAE,GAAY;IAC9C,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IAC1D,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC,IAAI,CAAC;IAC7B,MAAM,KAAK,GAAG,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,QAAQ,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IACzF,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC,IAAI,CAAC;IAC7B,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC;QAC1E,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,CAAC;IACb,CAAC;AACH,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,QAAQ,CAAC,GAAW,EAAE,GAAY;IAChD,MAAM,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAClE,OAAO,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAChD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,MAAM,CAAC,GAAY,EAAE,IAAY;IAC/C,MAAM,IAAI,GAAG,CAAC,GAAW,EAAW,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;IAEzE,MAAM,SAAS,GAAc,EAAE,CAAC;IAChC,IAAI,EAAE,GAAG,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC7B,4DAA4D;IAC5D,OAAO,EAAE,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,EAAE,EAAG,CAAC,CAAC,EAAE,CAAC;QAClF,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;QAC5B,EAAE,GAAG,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IACzB,CAAC;IAED,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACnC,MAAM,QAAQ,GAAG,MAAM;QACrB,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;aACvB,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;aAC3E,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChC,CAAC,CAAC,EAAE,CAAC;IAEP,MAAM,QAAQ,GAAG,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;SACxC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;SAC5C,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAE/B,MAAM,GAAG,GAAG,CAAC,GAAI,GAAG,CAAC,KAAK,CAAC,IAAI,EAAuB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IACvF,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAEhE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AAClD,CAAC;AAcD,SAAS,cAAc;IACrB,IAAI,CAAC;QACH,OAAO,OAAO,cAAc,KAAK,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC;IACvE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAc,EACd,IAAqC,EACrC,OAA0B,EAAE;IAE5B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,QAAQ,CAAC,MAAM,CAAC;IAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;IAC7E,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IACrC,MAAM,GAAG,GAAG,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC;IAEzC,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,IAAI,MAAM,CAAsD,CAAC;QAC/G,MAAM,KAAK,GAAG,KAAK,IAAI,GAAG,GAAG,KAAK,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,YAAY,CAAC,IAAI,KAAK,CAAC,SAAS,IAAI,GAAG,CAAC;QACvG,IAAI,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC;YAAE,OAAO,KAAK,CAAC,MAAM,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,gCAAgC;IAClC,CAAC;IAED,MAAM,MAAM,GAAG,CAAC,MAAM,iBAAiB,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;SAC/D,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;SACjC,MAAM,CAAC,CAAC,CAAC,EAAkB,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;IAC7C,IAAI,CAAC;QACH,OAAO,EAAE,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IACpE,CAAC;IAAC,MAAM,CAAC;QACP,0EAA0E;IAC5E,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,kCAAkC;AAClC,MAAM,CAAC,MAAM,eAAe,GAAG,YAAY,CAAC;AAE5C,0DAA0D;AAC1D,MAAM,UAAU,GAAG,EAAE,CAAC;AAEtB,MAAM,IAAI,GAAG,CAAC,KAAa,EAAE,KAAgB,EAAY,EAAE,CACzD,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,KAAK,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAEhG;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CAAC,GAAY,EAAE,IAAY;IACpD,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACnE,MAAM,KAAK,GAAG,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACpF,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC;IAC/B,MAAM,KAAK,GAAG;QACZ,cAAc,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG;YACtD,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,KAAK,QAAQ,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC;QACjF,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,UAAU,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,GAAG,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC;QAC3B,GAAG,IAAI,CAAC,sBAAsB,EAAE,QAAQ,CAAC;QACzC,GAAG,IAAI,CAAC,iBAAiB,EAAE,QAAQ,CAAC;QACpC,GAAG,IAAI,CAAC,kBAAkB,EAAE,KAAK,CAAC;KACnC,CAAC;IACF,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;IACvF,OAAO,SAAS,CAAC,MAAM;QACrB,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,0FAA0F,SAAS;aAC3G,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;aAClB,IAAI,CAAC,IAAI,CAAC,GAAG;QAClB,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,gDAAgD,CAAC;AAClE,CAAC;AAED;;;;;;GAMG;AACH,SAAS,MAAM,CAAC,IAAY,EAAE,GAAY;IACxC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;IAC3D,IAAI,CAAC;QACH,+FAA+F;QAC/F,6CAA6C;QAC7C,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC/B,OAAO,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC;QACnC,CAAC;QACD,OAAO,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,EAAE,GAAG,IAAI,IAAI,CAAC;IAC5B,CAAC;AACH,CAAC;AAgBD;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAY,EAAE,OAAyB,EAAE;IAC1E,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,WAAW,EACT,iGAAiG;YACjG,mGAAmG;YACnG,wGAAwG;QAC1G,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;QAC/C,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;QACnC,OAAO,EAAE,KAAK,IAAI,EAAE;YAClB,MAAM,MAAM,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC;YAChE,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,IAAI,CAAC,OAAO,QAAQ,KAAK,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;qBACnG;iBACF;aACF,CAAC;QACJ,CAAC;KACkB,CAAC;AACxB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,EAAgB,EAChB,GAAY,EACZ,OAAyB,EAAE;IAE3B,IAAI,CAAC;QACH,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,eAAe,CAAC;YAAE,OAAO,KAAK,CAAC;IAClF,CAAC;IAAC,MAAM,CAAC;QACP,kDAAkD;IACpD,CAAC;IACD,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,YAAY,CAAC,kBAAkB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;QACrD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,IAAI,CAAC,iCAAiC,eAAe,GAAG,EAAE,GAAG,CAAC,CAAC;QACvE,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/harness/tools/site-pages.d.ts

@@ -23,6 +23,10 @@ export interface SitePage {
     name: string;
     /** The `@id`s of the records the page is about, when its record says. */
     about?: string[];
+    /** Pages this one points a reader at: its `significantLink` and `relatedLink`. */
+    links?: string[];
+    /** The `@id` of the breadcrumb trail extracted from this page, when it has one. */
+    breadcrumb?: string;
 }
 type Obj = Record<string, unknown>;
 /**
@@ -51,10 +55,11 @@ export declare function mergePages(...lists: SitePage[][]): SitePage[];
 /**
  * The page a record came from, when it can be told.
  *
- * In order of how much each is to be trusted: the record naming its page, the
- * record being a page, the record's own URL when it is a page of this site
- * rather than its root, a page that says it is about the record, and last a
- * page with the record's exact name.
+ * In order of how much each is to be trusted: the record naming its page, its
+ * id when that is formed from a page (`page.html#organization`), the record
+ * being a page, the record's own URL when it is a page of this site rather than
+ * its root, a page that says it is about the record, and last a page with the
+ * record's exact name.
  *
  * @param entity - The record, compact or IRI-keyed.
  * @param pages - The site's pages.

package/dist/harness/tools/site-pages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"site-pages.d.ts","sourceRoot":"","sources":["../../../src/harness/tools/site-pages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACxE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAO3D,oDAAoD;AACpD,MAAM,WAAW,QAAQ;IACvB,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAoCnC;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAOvE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,EAAE,CAUlF;AAQD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,KAAK,EAAE,QAAQ,EAAE,EAAE,GAAG,QAAQ,EAAE,CAQ7D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CA2B7F;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAY3F;AAED,yCAAyC;AACzC,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gGAAgG;IAChG,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACzB,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAUD;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,CAAC,EACrC,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,QAAQ,EAAE,CAAC,CAyBrB"}
+{"version":3,"file":"site-pages.d.ts","sourceRoot":"","sources":["../../../src/harness/tools/site-pages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACxE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAO3D,oDAAoD;AACpD,MAAM,WAAW,QAAQ;IACvB,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAoCnC;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAiBvE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,EAAE,CAUlF;AAQD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,KAAK,EAAE,QAAQ,EAAE,EAAE,GAAG,QAAQ,EAAE,CAY7D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAiC7F;AAiBD;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAY3F;AAED,yCAAyC;AACzC,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gGAAgG;IAChG,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACzB,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAUD;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,CAAC,EACrC,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,QAAQ,EAAE,CAAC,CAyBrB"}

package/dist/harness/tools/site-pages.js

@@ -49,7 +49,17 @@ export function parsePage(raw, origin) {
     if (!url || !name)
         return null;
     const about = [...refs(schemaValue(raw, 'mainEntity')), ...refs(schemaValue(raw, 'about'))];
-    return about.length ? { url, name, about } : { url, name };
+    // What the page points at, which is how an agent follows a page's own links rather than only
+    // the hierarchy above it. Kept as published; the platform stores them absolute.
+    const links = [...new Set([...refs(schemaValue(raw, 'significantLink')), ...refs(schemaValue(raw, 'relatedLink'))])];
+    const breadcrumb = refs(schemaValue(raw, 'breadcrumb'))[0];
+    return {
+        url,
+        name,
+        ...(about.length ? { about } : {}),
+        ...(links.length ? { links } : {}),
+        ...(breadcrumb ? { breadcrumb } : {}),
+    };
 }
 /**
  * The pages the site's actions live on, named for what each is about.
@@ -87,18 +97,25 @@ export function mergePages(...lists) {
         const same = out.find((p) => samePage(p.url, page.url));
         if (!same)
             out.push({ ...page });
-        else if (page.about?.length)
-            same.about = [...new Set([...(same.about ?? []), ...page.about])];
+        else {
+            if (page.about?.length)
+                same.about = [...new Set([...(same.about ?? []), ...page.about])];
+            if (page.links?.length)
+                same.links = [...new Set([...(same.links ?? []), ...page.links])];
+            if (page.breadcrumb && !same.breadcrumb)
+                same.breadcrumb = page.breadcrumb;
+        }
     }
     return out;
 }
 /**
  * The page a record came from, when it can be told.
  *
- * In order of how much each is to be trusted: the record naming its page, the
- * record being a page, the record's own URL when it is a page of this site
- * rather than its root, a page that says it is about the record, and last a
- * page with the record's exact name.
+ * In order of how much each is to be trusted: the record naming its page, its
+ * id when that is formed from a page (`page.html#organization`), the record
+ * being a page, the record's own URL when it is a page of this site rather than
+ * its root, a page that says it is about the record, and last a page with the
+ * record's exact name.
  *
  * @param entity - The record, compact or IRI-keyed.
  * @param pages - The site's pages.
@@ -115,6 +132,12 @@ export function pageForEntity(entity, pages, origin) {
         if (url)
             return known(url);
     }
+    // An id built from its page (`page.html#organization`) names the page: everything before the
+    // fragment. Only with a fragment and below the root: a site-wide id (`/#organization/...`) names
+    // no page, and the hash-suffixed ids stored before (`page.html/23400b...`) are not pages either.
+    const idPage = pageOfId(str(entity['@id']), origin);
+    if (idPage)
+        return known(idPage);
     const own = onOrigin(schemaValue(entity, 'url'), origin);
     if (own && (types(entity).some((t) => t.endsWith('Page')) || new URL(own).pathname !== '/')) {
         return known(own);
@@ -132,6 +155,22 @@ export function pageForEntity(entity, pages, origin) {
     }
     return null;
 }
+/**
+ * The page an id formed from it names, or null.
+ *
+ * nxis-sdn-api forms a page entity's id as the page URL plus a fragment, so the page is the id with
+ * the fragment removed.
+ */
+function pageOfId(id, origin) {
+    if (!id || !id.includes('#'))
+        return null;
+    const url = onOrigin(id, origin);
+    if (!url)
+        return null;
+    const page = new URL(url);
+    page.hash = '';
+    return page.pathname === '/' ? null : page.href;
+}
 /**
  * The page a visitor or model means, by name or by address.
  *