@aglyn/plugins-ai 1.0.0-beta.296 → 1.1.0

package/src/lib/model/ai-site-import-fidelity.d.ts

@@ -0,0 +1,175 @@
+/**
+ * @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 { SiteImportBlock } from '../site-import/site-import-html';
+import type { SiteImportBand, SiteImportFooter, SiteImportGroupKind, SiteImportLayout, SiteImportNavTree } from './ai-site-import';
+/** The lowest score of structure a page brought in ships at (AGL-4109); words are held at exactly 1. */
+export declare const SITE_IMPORT_FIDELITY_THRESHOLD = 0.9;
+/** A node of a page or a layout, as the compiler draws it or Firestore stores it, decoded. */
+export interface SiteImportFidelityNode {
+    componentId?: string;
+    props?: Record<string, unknown> | null;
+    sx?: Record<string, unknown> | null;
+    nodes?: readonly string[] | null;
+    parentId?: string | null;
+    interactions?: readonly unknown[] | null;
+}
+/** A built page or layout: its nodes and the one they hang from. */
+export interface SiteImportFidelityTree {
+    rootId: string;
+    nodes: Readonly<Record<string, SiteImportFidelityNode>>;
+}
+/** What the source had, what the built page kept of it, and the share kept. */
+export interface SiteImportFidelityCount {
+    source: number;
+    built: number;
+    ratio: number;
+}
+/** The words of a page: every one of the source's, as written, exactly once, and none of its own. */
+export interface SiteImportFidelityWords {
+    /** Words the source's lines hold. */
+    source: number;
+    /** Words the built page shows. */
+    built: number;
+    /** The source's words the page does not show (counted as often as they are missing). */
+    missing: number;
+    /** Words the page shows that are not the source's, or are shown more often than the source says them. */
+    extra: number;
+    /** Words shown once each, over the larger of the two. */
+    ratio: number;
+    /** A few of the missing and extra words, for a report. */
+    examples: {
+        missing: string[];
+        extra: string[];
+    };
+}
+export interface SiteImportFidelityGroup {
+    /** Groups of the kind kept whole: every item of them its own element, with its parts. */
+    groups: SiteImportFidelityCount;
+    /** Items of the kind kept, each its own element with its parts. */
+    items: SiteImportFidelityCount;
+}
+/** A page brought in, scored against its source. */
+export interface SiteImportPageFidelity {
+    /** The lowest ratio of the structure: what the page ships on, at `SITE_IMPORT_FIDELITY_THRESHOLD` or above. */
+    score: number;
+    /** The measure that set the score; `null` when every measure is whole. */
+    lowest: string | null;
+    words: SiteImportFidelityWords;
+    sections: SiteImportFidelityCount;
+    /** Sections drawn in the source's band, in order. */
+    bands: SiteImportFidelityCount & {
+        read: SiteImportBand[];
+        drawn: SiteImportBand[];
+    };
+    /** The source's rows of two or more columns, set side by side on the page. */
+    rows: SiteImportFidelityCount;
+    /** The source's groups by kind. A group of lines that only share a shape (`text`) is drawn as its lines, and is not scored. */
+    groups: Partial<Record<SiteImportGroupKind, SiteImportFidelityGroup>>;
+    tables: SiteImportFidelityCount;
+    tabs: SiteImportFidelityCount;
+    /** The source's pictures placed on the page. */
+    pictures: SiteImportFidelityCount;
+    /**
+     * The source's icons drawn: each group item's own, each bullet's mark. An
+     * icon standing alone in the source (a video's play mark) is no word and no
+     * picture of the page, and the build leaves it out (AGL-4107): it is
+     * counted in `lone` and not scored.
+     */
+    icons: SiteImportFidelityCount & {
+        lone: number;
+    };
+    /**
+     * The lines the source draws as buttons that go somewhere (a page, an
+     * address, an email, a phone), drawn as buttons of the same style with
+     * their destinations. A button that goes nowhere a page can send a visitor
+     * (a film's play button its script runs) is kept as its words: counted in
+     * `unlinked`, not scored.
+     */
+    buttons: SiteImportFidelityCount & {
+        unlinked: number;
+    };
+    /** The source's headings, drawn as headings. */
+    headings: SiteImportFidelityCount;
+    /** The source's forms, where the site has a form a page places. */
+    forms: SiteImportFidelityCount;
+}
+/** A page's source as the import read it: its layout over its main-region blocks, and its photos as the library holds them. */
+export interface SiteImportFidelitySource {
+    layout: SiteImportLayout;
+    /** The page's main-region blocks, which the layout's lines are indexes of. */
+    blocks: readonly SiteImportBlock[];
+    /** The source's pictures as the site's library holds them (`from` → `src`); without them a picture is counted, not placed. */
+    photos?: ReadonlyArray<{
+        from?: string;
+        src: string;
+    }>;
+}
+/** A section's band as the compiler draws it: a dark scheme, the paper ground, the brand fill, else plain. */
+export declare function siteImportFidelityBandOf(node: SiteImportFidelityNode | undefined): SiteImportBand;
+/** The node a stored page or layout hangs from: the canvas root, else the one with no parent. */
+export declare function siteImportFidelityTreeOf(nodes: Readonly<Record<string, SiteImportFidelityNode>>): SiteImportFidelityTree;
+/**
+ * A built page scored against its source (AGL-4109): the words, each once;
+ * the sections and their bands; the rows of columns; the groups by kind, each
+ * item an element of its own with its parts; the tables, tabs, pictures,
+ * icons, buttons, headings and forms. The score is the lowest ratio of the
+ * structure.
+ */
+export declare function siteImportFidelity(source: SiteImportFidelitySource, tree: SiteImportFidelityTree): SiteImportPageFidelity;
+/** A built header and footer, scored against the source's. */
+export interface SiteImportFrameFidelity {
+    /** The lowest ratio of the header's and footer's measures. */
+    score: number;
+    lowest: string | null;
+    /** The source's top-level items, in the header's row, over the larger of the two (a row of page titles scores low). */
+    items: SiteImportFidelityCount;
+    /** Whether the row's items are in the source's order. */
+    inOrder: boolean;
+    /** The source's menus drawn as menus under their names. */
+    menus: SiteImportFidelityCount;
+    /** The source's menu entries, each a link in its menu. */
+    entries: SiteImportFidelityCount;
+    /** The lines under entries and their icons, in their menus. */
+    details: SiteImportFidelityCount;
+    /** The header's buttons, drawn as the source draws them, each with its destination. */
+    ctas: SiteImportFidelityCount;
+    /** Everything of the row in the phone menu: each menu's name and entries, the links, the buttons. */
+    drawer: SiteImportFidelityCount;
+    /** A menu button shown where the row is not, opening the phone menu. */
+    phone: SiteImportFidelityCount;
+    /** The row's labels held to one line. */
+    nowrap: SiteImportFidelityCount;
+    /** The footer's columns under their headings. */
+    columns: SiteImportFidelityCount;
+    /** The footer's links, its columns' and its own. */
+    links: SiteImportFidelityCount;
+    /** Its profiles on other sites. */
+    social: SiteImportFidelityCount;
+    /** Its words, address, phone, email and © line, word for word. */
+    facts: SiteImportFidelityCount;
+}
+/**
+ * A built header and footer scored against the source's (AGL-4109): the
+ * header's top-level items in order, each menu's entries with the lines and
+ * icons under them, its buttons, the phone menu holding all of it, the row's
+ * labels on one line; the footer's columns, links, profiles and facts. The
+ * score is the lowest ratio.
+ */
+export declare function siteImportFrameFidelity(source: {
+    nav: SiteImportNavTree | null | undefined;
+    footer: SiteImportFooter | null | undefined;
+}, tree: SiteImportFidelityTree): SiteImportFrameFidelity;