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

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

@@ -26,9 +26,11 @@ export declare const AI_SITE_IMPORT_WAVE_PAGES = 10;
 /**
  * The most pages one import reads, whatever the plan allows: an unlimited
  * plan is still one crawl's worth, and the crawl's own time budget may stop
- * sooner (the inventory then says so).
+ * sooner (the inventory then says so). Only pages count: a file a link
+ * points at is never fetched as one (AGL-4106), so aglyn.com's 209 pages fit
+ * with room where 136 press-kit files once took 136 of 200.
  */
-export declare const AI_SITE_IMPORT_MAX_PAGES = 200;
+export declare const AI_SITE_IMPORT_MAX_PAGES = 400;
 /** The fewest pages under one address prefix that make it a collection. */
 export declare const AI_SITE_IMPORT_COLLECTION_MIN = 3;
 /** The most photos brought in from one page. */
@@ -45,16 +47,21 @@ export declare const AI_SITE_IMPORT_MAX_SECTIONS = 24;
 export declare const AI_SITE_IMPORT_READ_MAX_BLOCKS = 2000;
 /** The most characters of one page's blocks a wave's read keeps: a long policy is 40,000. */
 export declare const AI_SITE_IMPORT_READ_MAX_CHARS = 120000;
+/** The most characters one page's layout keeps on the job document (AGL-4106): its icons' drawings go first. */
+export declare const AI_SITE_IMPORT_LAYOUT_MAX_CHARS = 48000;
 /**
- * The most characters of blocks the reads of one import hold at once: they
+ * The most characters of blocks (and their layouts, AGL-4106) the reads of one import hold at once: they
  * ride the job document, which Firestore caps at 1 MiB, beside the
  * inventory and the ledger. A wave's later page past it keeps what fits and
  * says it was cut.
  */
 export declare const AI_SITE_IMPORT_WAVE_READ_MAX_CHARS = 400000;
 /**
- * A page with more words of its own than this is copied as it is, never
- * arranged (AGL-4083): a policy, an article, a long story.
+ * A collection's page longer than this is prose: a policy, an article, a
+ * long story (AGL-4083). A collection's page is copied as it is whatever its
+ * length, and since AGL-4106 a main page is arranged whatever its length:
+ * `/product` at 1,072 words is laid out as its source lays it out, not copied
+ * as one column.
  */
 export declare const AI_SITE_IMPORT_PROSE_WORDS = 900;
 /** The answers bot protection and firewalls turn a crawler away with: asked to sign in, refused, or told to slow down. */
@@ -110,7 +117,9 @@ export type AiSiteImportLeftOutReason =
 /** It sends visitors to another website. */
  | 'off-site'
 /** The read stopped (its clock, its bytes, its page count) before it got to it (AGL-4083). */
- | 'not-reached';
+ | 'not-reached'
+/** A link to a file (a download, a PDF with no extension), not a page (AGL-4106). */
+ | 'file';
 export declare const AI_SITE_IMPORT_LEFT_OUT_REASONS: readonly AiSiteImportLeftOutReason[];
 /** The reasons that mean the page was there and AglynBot could not read it: the "could not be read" of what was found. */
 export declare const AI_SITE_IMPORT_UNREAD_REASONS: readonly AiSiteImportLeftOutReason[];
@@ -130,6 +139,250 @@ export interface AiSiteImportPhoto {
     /** The address on the old site it was read from, where a page that is copied places it (AGL-4084). */
     from?: string;
 }
+/**
+ * One line of a page, by its index in the page's main-region blocks
+ * (`AiSiteImportPageRead.blocks`, 0-based). The layout holds no words of
+ * its own: every word is a block's, placed once.
+ */
+export type SiteImportLineRef = number;
+/** A section's background, in the layout language's bands. */
+export type SiteImportBand = 'plain' | 'soft' | 'brand' | 'dark';
+/** How the source draws a button: filled, outlined, or as a link with button padding. */
+export type SiteImportButtonStyle = 'primary' | 'secondary' | 'quiet';
+/** What a repeated group of the source is. */
+export type SiteImportGroupKind = 'cards' | 'steps' | 'stats' | 'faq' | 'quotes' | 'logos' | 'pricing' | 'list' | 'text';
+export declare const SITE_IMPORT_GROUP_KINDS: readonly SiteImportGroupKind[];
+/** One line in place. `role` only where the source's own styling says it (an uppercase eyebrow, a large lede, a small note). */
+export interface SiteImportLayoutLine {
+    kind: 'line';
+    line: SiteImportLineRef;
+    role?: 'eyebrow' | 'lede' | 'note';
+    /** The source draws this line (a link, or a `<button>`'s words) as a button. Its destination is the link block's `href`. */
+    button?: SiteImportButtonStyle;
+}
+/** A picture in place: an image block. */
+export interface SiteImportLayoutPicture {
+    kind: 'picture';
+    line: SiteImportLineRef;
+    /** Where clicking it goes, when it sits in a link. */
+    href?: string;
+    /** It sits in a `<button>` (a video's poster, a lightbox): the picture is kept, the button is not a destination. */
+    button?: true;
+}
+/** An icon standing on its own, by index into `SiteImportLayout.icons`. */
+export interface SiteImportLayoutIcon {
+    kind: 'icon';
+    icon: number;
+}
+/** Where one of the page's forms sat, by index into `AiSiteImportPageRead.forms`. */
+export interface SiteImportLayoutForm {
+    kind: 'form';
+    form: number;
+}
+/**
+ * A row of columns side by side; `cols` are relative widths in twelfths
+ * (`[4, 8]`, `[1, 1, 1]`). Every list of lists is a list of objects: the
+ * layout rides a Firestore document, which holds no array inside an array.
+ */
+export interface SiteImportLayoutRow {
+    kind: 'row';
+    cols: number[];
+    cells: Array<{
+        nodes: SiteImportLayoutNode[];
+    }>;
+}
+/**
+ * One item of a group. Every line of the item is in `lines`, in order, and
+ * in exactly one of the named parts.
+ */
+export interface SiteImportLayoutItem {
+    lines: SiteImportLineRef[];
+    /** The item's name: its heading, its title link, or its first short line. */
+    title?: SiteImportLineRef;
+    /** A stat's figure, a step's number, a plan's price. */
+    figure?: SiteImportLineRef;
+    text?: SiteImportLineRef[];
+    /** Its bullet points (a plan's features). */
+    list?: SiteImportLineRef[];
+    /** Its own call to action: a "See … →" link or a button, last in the item. */
+    link?: SiteImportLineRef[];
+    image?: SiteImportLineRef;
+    /** The icon that leads it, by index into `SiteImportLayout.icons`. */
+    icon?: number;
+    /** The icon each of its bullet points carries (a check mark), when they share one. */
+    listIcon?: number;
+    /** Where the item goes as a whole: its title link's address. */
+    to?: string;
+}
+export interface SiteImportLayoutGroup {
+    kind: 'group';
+    group: SiteImportGroupKind;
+    /** Columns the source lays the items out in on a wide screen. */
+    columns: number;
+    /** Each item is drawn as a box (a border, a shadow or a fill of its own). */
+    boxed: boolean;
+    items: SiteImportLayoutItem[];
+}
+/** A table: rows of cells, each cell its lines (objects, not nested arrays, for Firestore). */
+export interface SiteImportLayoutTable {
+    kind: 'table';
+    /** Whether the first row names the columns. */
+    header: boolean;
+    rows: Array<{
+        cells: Array<{
+            lines: SiteImportLineRef[];
+        }>;
+    }>;
+}
+/** A tab strip and its panels; a panel the source did not draw is empty. */
+export interface SiteImportLayoutTabs {
+    kind: 'tabs';
+    tabs: Array<{
+        label: SiteImportLineRef | null;
+        selected?: true;
+        panel: SiteImportLayoutNode[];
+    }>;
+}
+export type SiteImportLayoutNode = SiteImportLayoutLine | SiteImportLayoutPicture | SiteImportLayoutIcon | SiteImportLayoutForm | SiteImportLayoutRow | SiteImportLayoutGroup | SiteImportLayoutTable | SiteImportLayoutTabs;
+/** Where the hero's picture sits against its words. */
+export type SiteImportHeroPicture = 'beside' | 'behind' | 'below' | 'above';
+export interface SiteImportLayoutSection {
+    /** Its `aria-label`, its heading, or "Section n": neutralized, cut to a label. */
+    name: string;
+    /** How its edges were found: a landmark (`<section>`), a container of its own, or its headings. */
+    from: 'landmark' | 'container' | 'heading';
+    band: SiteImportBand;
+    /** Its background color as `#rrggbb`, when it has one. */
+    background: string | null;
+    /** A gradient or a photo behind it. */
+    backdrop?: {
+        kind: 'gradient';
+    } | {
+        kind: 'picture';
+        url: string;
+    };
+    align: 'start' | 'center';
+    /** Set on the section holding the page's first `<h1>`. */
+    hero?: {
+        picture: SiteImportHeroPicture | null;
+    };
+    nodes: SiteImportLayoutNode[];
+    /** Every line of the section, in order. */
+    lines: SiteImportLineRef[];
+}
+/** An icon the page draws, once however often it repeats. */
+export interface SiteImportIconShape {
+    viewBox: string;
+    /** One path, for the Besigner's icon element (`iconPath`, drawn on a 24-unit square). */
+    path?: string;
+    /** A small drawing of several shapes, geometry only, for a picture of it. */
+    svg?: string;
+}
+/** What the source's look is made of (AGL-4106), read from its stylesheets. */
+export interface SiteImportLookFacts {
+    fonts: {
+        /** The family its body text is set in, as named, when it is not a system font. */
+        body: string | null;
+        /** The family its headings are set in. */
+        headings: string | null;
+        /** The families it loads from Google Fonts, in order. */
+        google: string[];
+    };
+    /** The page's own background, `#rrggbb`. */
+    background: string | null;
+    /** Its body text color. */
+    text: string | null;
+    /** The fill of its filled buttons, the most used first. */
+    buttonFill: string | null;
+    /** The text color on them. */
+    buttonText: string | null;
+    /** Its buttons' corner radius, px. */
+    buttonRadius: number | null;
+    /** The color its text links are drawn in. */
+    link: string | null;
+    /** Its header bar's background. */
+    header: string | null;
+}
+/** A page's layout, as the source lays it out (AGL-4106). */
+export interface SiteImportLayout {
+    v: 1;
+    sections: SiteImportLayoutSection[];
+    icons: SiteImportIconShape[];
+    look: SiteImportLookFacts;
+}
+/** One entry of a menu, as the source's header shows it. */
+export interface SiteImportNavEntry {
+    label: string;
+    /** The line under it in a mega menu. */
+    text?: string;
+    /** Where it goes: absolute http(s), `mailto:` or `tel:`. */
+    href: string;
+    /** Its icon, when it has a one-path icon. */
+    iconPath?: string;
+    viewBox?: string;
+    /** The heading of the menu's column it sits in ("By team"). */
+    column?: string;
+}
+/** A top-level item of the source's menu: a link, or a menu of entries under a name. */
+export interface SiteImportNavGroup {
+    label: string;
+    /** Where the name itself goes; `null` when it only opens its menu. */
+    href: string | null;
+    /** Empty for a plain link. */
+    items: SiteImportNavEntry[];
+}
+/** A button in the source's header outside its menu ("Sign in", "Start free"). */
+export interface SiteImportNavCta {
+    label: string;
+    href: string | null;
+    style: SiteImportButtonStyle;
+}
+/** The source's header menu (AGL-4106). Untrusted data from the owner's site. */
+export interface SiteImportNavTree {
+    items: SiteImportNavGroup[];
+    ctas: SiteImportNavCta[];
+    /** The source shows a menu button on phones. */
+    phoneMenu: boolean;
+    /** The header bar's background, `#rrggbb`. */
+    background: string | null;
+}
+export interface SiteImportFooterLink {
+    label: string;
+    href: string;
+}
+/** The source's footer (AGL-4106): its columns, profiles and facts, as written. */
+export interface SiteImportFooter {
+    columns: Array<{
+        heading: string;
+        links: SiteImportFooterLink[];
+    }>;
+    /** Its links to profiles on other sites. */
+    social: Array<SiteImportFooterLink & {
+        network: string;
+    }>;
+    /** Links outside any column and not a profile (Privacy, Terms, Status). */
+    links: SiteImportFooterLink[];
+    /** Its lines of text outside links (a tagline), as written. */
+    text: string[];
+    address: string | null;
+    phone: string | null;
+    email: string | null;
+    /** Its © line, word for word. */
+    copyright: string | null;
+}
+/** Every line a layout's nodes place, in order. */
+export declare function siteImportLayoutLines(nodes: readonly SiteImportLayoutNode[]): SiteImportLineRef[];
+/** How many characters a layout weighs on the job document. */
+export declare function siteImportLayoutChars(layout: SiteImportLayout | null | undefined): number;
+/**
+ * A layout over only the first `count` lines (a read the wave's budget cut
+ * short): references past the cut are dropped, and what is left empty goes.
+ */
+export declare function siteImportLayoutWithin(layout: SiteImportLayout, count: number): SiteImportLayout;
+/** Nodes with only the lines `keep` keeps; what is left empty goes. */
+export declare function siteImportFilterNodes(list: readonly SiteImportLayoutNode[], keep: (ref: SiteImportLineRef) => boolean): SiteImportLayoutNode[];
+/** A layout with its icons' drawings dropped, for a page that must be lighter. */
+export declare function siteImportLayoutWithoutDrawings(layout: SiteImportLayout): SiteImportLayout;
 /** What a wave's read found on one page, for its model answer. Never on the wire. */
 export interface AiSiteImportPageRead {
     at: string;
@@ -157,6 +410,21 @@ export interface AiSiteImportPageRead {
     words?: number;
     /** The forms the page asks visitors to fill in, by their fields. */
     forms?: SiteImportForm[];
+    /**
+     * How the source lays the page out (AGL-4106): its sections, bands, rows,
+     * groups, pictures, icons and buttons, over `blocks` by index. Absent on a
+     * read made before the reader, or when it did not fit the wave's budget.
+     */
+    layout?: SiteImportLayout | null;
+    /**
+     * The page's browser title and meta description as the source writes them
+     * (AGL-4107), which the new page's listing keeps word for word. Absent on a
+     * read made before they were kept.
+     */
+    meta?: {
+        title: string;
+        description: string;
+    };
 }
 /** How a page is built from its old page, as the step chose: its words copied as they are, or arranged by Aglyn AI. */
 export type AiSiteImportBuild = 'copied' | 'arranged';
@@ -193,7 +461,12 @@ export interface AiSiteImportPage {
         assets: AiSiteImportPhoto[];
     } | null;
 }
-export type AiSiteImportWaveStatus = 'waiting' | 'running' | 'review' | 'done';
+/**
+ * A wave's place in its import: waiting to start, running, in and waiting for
+ * the person's review, in, or `stopped` — the import was canceled before the
+ * wave was in, while it ran or before it started (AGL-4107).
+ */
+export type AiSiteImportWaveStatus = 'waiting' | 'running' | 'review' | 'done' | 'stopped';
 export interface AiSiteImportWave {
     index: number;
     label: string;
@@ -235,8 +508,6 @@ export interface AiSiteImportState {
     frame: {
         draftId: string;
     } | null;
-    /** The Trust & Safety row this import is logged under. */
-    reviewId: string | null;
     /**
      * "Start every remaining wave" (AGL-4083): each wave closes and the next
      * starts with no review between them; the last wave's close is the stop.
@@ -286,7 +557,24 @@ export interface AiSiteImportHome {
         social: string[];
         address: string;
     };
+    /**
+     * The source's header menu as its home page builds it (AGL-4108): its
+     * items, their menus, its buttons. The header and footer are drawn from it
+     * with no model; absent on a read made before the reader, or where the home
+     * page has no menu the reader can find.
+     */
+    nav?: SiteImportNavTree | null;
+    /** The source's footer as its home page builds it (AGL-4108): its columns, profiles, facts and © line. */
+    footer?: SiteImportFooter | null;
+    /** What the source's look is made of (AGL-4108): its colors, its button fill and corners, its fonts. */
+    look?: SiteImportLookFacts | null;
 }
+/**
+ * Whether the site's header and footer are built from the source's own menu
+ * (AGL-4108), with no model: the home page's menu was read. Then the frame
+ * costs nothing and is quoted at nothing.
+ */
+export declare function aiSiteImportFrameIsRead(state: Pick<AiSiteImportState, 'home'> | null | undefined): boolean;
 /** What the look pass did (AGL-4084): no model is asked. */
 export interface AiSiteImportLook {
     at: string;
@@ -417,7 +705,6 @@ export interface AiSiteImportInventoryInput {
     existingPages: number;
     /** Mints one draft id; the inventory names every page's draft before any is written. */
     mintId: () => string;
-    reviewId?: string | null;
     wavePages?: number;
 }
 /**
@@ -487,13 +774,20 @@ export declare function aiSiteImportPhotosIn(state: AiSiteImportState, slot: str
 export declare function aiSiteImportPageSettled(state: AiSiteImportState, slot: string): AiSiteImportState;
 /** A wave is in: waiting for its review, or done when no wave follows it. */
 export declare function aiSiteImportWaveClosed(state: AiSiteImportState, index: number, at: string): AiSiteImportState;
+/**
+ * The state of an import a person canceled (AGL-4107): every wave settled. A
+ * wave that ran, or was waiting to, is stopped; one already in, for review or
+ * done, is in. On 10/29 a canceled import still showed its second wave as
+ * running, with nothing running it.
+ */
+export declare function aiSiteImportCanceled(state: AiSiteImportState, at: string): AiSiteImportState;
 /** The state as the console reads it: every page's read text left off. */
 export declare function aiSiteImportWire(state: AiSiteImportState | null | undefined): AiSiteImportState | null;
 /**
  * How a page is built (AGL-4083), decided by code: every page of a collection
- * (a blog, the legal pages, news) and any page longer than
- * `AI_SITE_IMPORT_PROSE_WORDS` is copied as it is; the main pages are
- * arranged by Aglyn AI, their words kept as written.
+ * (a blog, the legal pages, news) is copied as it is; every main page is
+ * arranged by Aglyn AI whatever its length (AGL-4106), its words kept as
+ * written. Both are laid out from the source's own layout.
  */
 export declare function aiSiteImportPageBuild(page: Pick<AiSiteImportPage, 'group' | 'words'>): AiSiteImportBuild;
 /**