@aglyn/plugins-ai 1.0.0-beta.239 → 1.0.0-beta.241

package/src/lib/runtime/ai-doctrine-validators.d.ts

@@ -689,6 +689,50 @@ export declare function aiSettleDisagreeingNodes(input: unknown): unknown;
  * re-ask. Reads and returns the tree as the model wrote it.
  */
 export declare function aiSettleCutHeadings(input: unknown): unknown;
+/**
+ * THE RULES A CHECK WOULD REFUSE FOR AN ATTRIBUTE, SETTLED IN CODE (AGL-3660).
+ *
+ * A finding whose fix is one attribute, one level or one key, with nothing to
+ * decide about what the page says, is applied before the check reads the
+ * tree, as `aiSettleGridItems` sizes a container's items. A live Free guided
+ * start's Portfolio page (2026-10-10) was refused for rule 16's `eager-image`:
+ * the pictures step loaded every photo of the opening section eagerly, the
+ * last pass reads the stored page and asks no model, and Try again could only
+ * refuse the same page for the same reason. None of these is a choice a model
+ * makes better than the code that knows the answer:
+ *
+ * - `eager-image` (16): only the tree's first image may load eagerly; every
+ *   later one has `loading` unset, so the renderer loads it when reached;
+ * - `autoplay-video` (16), its attribute half: `autoPlay` and `preload: auto`
+ *   are taken off. A film with no poster still needs a picture, and is left;
+ * - `extra-font` (16): an `sx` font family outside an email is taken off, so
+ *   the element reads the theme's typography;
+ * - `multiple-h1` and `skipped-heading` (11): every top-level heading after a
+ *   page's first renders as an h2 (a layout's all do, a component's after its
+ *   first), and a heading after it that skips a level renders one below the
+ *   heading before it. Only the element changes (`component`): the variant,
+ *   and so the look, is kept. A heading before a page's h1, and a page with no
+ *   h1, are the model's to mend;
+ * - `multiple-main` and `landmark-in-fragment` (11): a `main` landmark after
+ *   the first, and any in a component, a form or an email, is unset;
+ * - `grid-gap` (12): a Grid container's `sx` gap is taken off and becomes its
+ *   `spacing` where it sets none, a number gap as itself, anything else 2,
+ *   which is what the re-ask asks for;
+ * - `link-color-on-band` (5): a link or a button whose words are drawn in its
+ *   band's own family is given that family's contrast text as its `sx` color,
+ *   which is what the re-ask asks for.
+ *
+ * A tree with nothing to settle comes back as the same object, so settling is
+ * idempotent; a node that is changed is copied, never edited in place.
+ */
+export declare function aiSettleMechanicalRules<T extends AiDoctrineTree>(tree: T, outputKind: AiOutputKind): T;
+/**
+ * `aiSettleMechanicalRules` on a tree as the model wrote it, before the
+ * palette validator reads it (AGL-3660), as `aiSettleWrittenGridItems` settles
+ * its items. Anything that is no flat node map comes back as it was, and a
+ * node whose shape is not a palette node's is read as nothing and left as written.
+ */
+export declare function aiSettleWrittenMechanicalRules(input: unknown, outputKind: AiOutputKind): unknown;
 export interface AiDoctrineTreeReport {
     ok: boolean;
     /** The palette validator's result: the tree to store, its repairs and its id map. */

package/src/lib/runtime/ai-doctrine-validators.js

@@ -2958,6 +2958,183 @@ const BUDGET_METRICS = [
         nodes
     }) : input;
 }
+// ── Mechanical rules, settled in code (AGL-3660) ─────────────────────────
+/**
+ * THE RULES A CHECK WOULD REFUSE FOR AN ATTRIBUTE, SETTLED IN CODE (AGL-3660).
+ *
+ * A finding whose fix is one attribute, one level or one key, with nothing to
+ * decide about what the page says, is applied before the check reads the
+ * tree, as `aiSettleGridItems` sizes a container's items. A live Free guided
+ * start's Portfolio page (2026-10-10) was refused for rule 16's `eager-image`:
+ * the pictures step loaded every photo of the opening section eagerly, the
+ * last pass reads the stored page and asks no model, and Try again could only
+ * refuse the same page for the same reason. None of these is a choice a model
+ * makes better than the code that knows the answer:
+ *
+ * - `eager-image` (16): only the tree's first image may load eagerly; every
+ *   later one has `loading` unset, so the renderer loads it when reached;
+ * - `autoplay-video` (16), its attribute half: `autoPlay` and `preload: auto`
+ *   are taken off. A film with no poster still needs a picture, and is left;
+ * - `extra-font` (16): an `sx` font family outside an email is taken off, so
+ *   the element reads the theme's typography;
+ * - `multiple-h1` and `skipped-heading` (11): every top-level heading after a
+ *   page's first renders as an h2 (a layout's all do, a component's after its
+ *   first), and a heading after it that skips a level renders one below the
+ *   heading before it. Only the element changes (`component`): the variant,
+ *   and so the look, is kept. A heading before a page's h1, and a page with no
+ *   h1, are the model's to mend;
+ * - `multiple-main` and `landmark-in-fragment` (11): a `main` landmark after
+ *   the first, and any in a component, a form or an email, is unset;
+ * - `grid-gap` (12): a Grid container's `sx` gap is taken off and becomes its
+ *   `spacing` where it sets none, a number gap as itself, anything else 2,
+ *   which is what the re-ask asks for;
+ * - `link-color-on-band` (5): a link or a button whose words are drawn in its
+ *   band's own family is given that family's contrast text as its `sx` color,
+ *   which is what the re-ask asks for.
+ *
+ * A tree with nothing to settle comes back as the same object, so settling is
+ * idempotent; a node that is changed is copied, never edited in place.
+ */ export function aiSettleMechanicalRules(tree, outputKind) {
+    if (!tree.nodes[tree.rootId]) return tree;
+    const nodes = _extends({}, tree.nodes);
+    const copied = new Set();
+    const edit = (id)=>{
+        if (!copied.has(id)) {
+            const node = nodes[id];
+            nodes[id] = _extends({}, node, node.props ? {
+                props: _extends({}, node.props)
+            } : {}, node.sx ? {
+                sx: _extends({}, node.sx)
+            } : {});
+            copied.add(id);
+        }
+        return nodes[id];
+    };
+    const unsetProp = (id, name)=>{
+        var _nodes_id_props;
+        if (((_nodes_id_props = nodes[id].props) == null ? void 0 : _nodes_id_props[name]) === undefined) return;
+        delete edit(id).props[name];
+    };
+    const setProp = (id, name, value)=>{
+        var _node_props;
+        var _nodes_id_props;
+        if (((_nodes_id_props = nodes[id].props) == null ? void 0 : _nodes_id_props[name]) === value) return;
+        const node = edit(id);
+        node.props = _extends({}, (_node_props = node.props) != null ? _node_props : {}, {
+            [name]: value
+        });
+    };
+    const unsetSx = (id, name)=>{
+        var _nodes_id_sx;
+        if (((_nodes_id_sx = nodes[id].sx) == null ? void 0 : _nodes_id_sx[name]) === undefined) return;
+        delete edit(id).sx[name];
+    };
+    const visits = walkTree(tree);
+    const email = outputKind === 'email';
+    const framed = !email && outputKind !== 'form';
+    const fragment = outputKind === 'component' || email || outputKind === 'form';
+    let images = 0;
+    let mains = 0;
+    for (const { id, node } of visits){
+        var _node_sx, _node_props;
+        // Rule 16: one eager image, the first; the rest load when they are reached.
+        if (node.componentId === 'image') {
+            var _node_props1;
+            images += 1;
+            if (images > 1 && ((_node_props1 = node.props) == null ? void 0 : _node_props1['loading']) === 'eager') unsetProp(id, 'loading');
+        }
+        // Rule 16: a film loads nothing before it is played.
+        if (node.componentId === 'video') {
+            var _node_props2, _node_props3;
+            if (((_node_props2 = node.props) == null ? void 0 : _node_props2['autoPlay']) === true) unsetProp(id, 'autoPlay');
+            if (((_node_props3 = node.props) == null ? void 0 : _node_props3['preload']) === 'auto') unsetProp(id, 'preload');
+        }
+        // Rule 16: the theme's typography, outside an email.
+        if (!email && ((_node_sx = node.sx) == null ? void 0 : _node_sx['fontFamily']) !== undefined) unsetSx(id, 'fontFamily');
+        // Rule 11: one main landmark, and none in what is placed inside pages.
+        if (elementOf(node) === 'main') {
+            mains += 1;
+            if (fragment || mains > 1) {
+                var _node_props4, _node_props5;
+                if (((_node_props4 = node.props) == null ? void 0 : _node_props4['component']) === 'main') unsetProp(id, 'component');
+                if (((_node_props5 = node.props) == null ? void 0 : _node_props5['element']) === 'main') unsetProp(id, 'element');
+            }
+        }
+        // Rule 12: a container is spaced by its `spacing`, never an sx gap.
+        if (framed && node.componentId === GRID && ((_node_props = node.props) == null ? void 0 : _node_props['container']) === true) {
+            const gap = GRID_GAP_SX_KEYS.find((key)=>{
+                var _node_sx;
+                return ((_node_sx = node.sx) == null ? void 0 : _node_sx[key]) !== undefined;
+            });
+            if (gap) {
+                var _node_sx1, _node_props6;
+                const value = (_node_sx1 = node.sx) == null ? void 0 : _node_sx1[gap];
+                for (const key of GRID_GAP_SX_KEYS)unsetSx(id, key);
+                if (((_node_props6 = node.props) == null ? void 0 : _node_props6['spacing']) === undefined) setProp(id, 'spacing', typeof value === 'number' ? value : 2);
+            }
+        }
+    }
+    // Rule 11: the heading outline, in document order.
+    if (framed) {
+        const headings = visits.map((visit)=>({
+                id: visit.id,
+                level: aiHeadingLevel(nodes[visit.id])
+            })).filter((entry)=>entry.level !== null);
+        const page = outputKind === 'page' || outputKind === 'template';
+        const firstH1 = headings.findIndex((heading)=>heading.level === 1);
+        // A page's outline is settled from its h1 on; a layout's and a component's from their first heading.
+        const start = page ? firstH1 : 0;
+        let previous = page ? 0 : null;
+        for(let index = Math.max(start, 0); start >= 0 && index < headings.length; index += 1){
+            const heading = headings[index];
+            // A page keeps its first h1, a component its first, and a layout none.
+            const keepsH1 = outputKind !== 'layout' && index === firstH1;
+            let level = heading.level === 1 && !keepsH1 ? 2 : heading.level;
+            previous != null ? previous : previous = level - 1;
+            if (level > previous + 1) level = previous + 1;
+            if (level !== heading.level) setProp(heading.id, 'component', `h${level}`);
+            previous = level;
+        }
+    }
+    // Rule 5: a link's words in its band's contrast text, read on the tree as settled so far.
+    if (framed) {
+        const settled = {
+            rootId: tree.rootId,
+            nodes
+        };
+        for (const visit of walkTree(settled)){
+            var _node_sx2;
+            if (!LINK_COMPONENTS.has(visit.node.componentId)) continue;
+            const family = linkWordsFamily(visit.node);
+            const band = family ? bandOf(settled, visit) : null;
+            if (!band || band.family !== family) continue;
+            const node = edit(visit.id);
+            node.sx = _extends({}, (_node_sx2 = node.sx) != null ? _node_sx2 : {}, {
+                color: `${family}.contrastText`
+            });
+        }
+    }
+    return copied.size ? _extends({}, tree, {
+        nodes
+    }) : tree;
+}
+/**
+ * `aiSettleMechanicalRules` on a tree as the model wrote it, before the
+ * palette validator reads it (AGL-3660), as `aiSettleWrittenGridItems` settles
+ * its items. Anything that is no flat node map comes back as it was, and a
+ * node whose shape is not a palette node's is read as nothing and left as written.
+ */ export function aiSettleWrittenMechanicalRules(input, outputKind) {
+    if (!isRecord(input) || typeof input['rootId'] !== 'string' || !isRecord(input['nodes'])) return input;
+    const readable = Object.entries(input['nodes']).filter(([, node])=>isRecord(node) && typeof node['componentId'] === 'string' && (node['props'] === undefined || isRecord(node['props'])) && (node['sx'] === undefined || isRecord(node['sx'])) && (node['nodes'] === undefined || Array.isArray(node['nodes']) && node['nodes'].every((child)=>typeof child === 'string')));
+    const tree = {
+        rootId: input['rootId'],
+        nodes: Object.fromEntries(readable)
+    };
+    const settled = aiSettleMechanicalRules(tree, outputKind);
+    return settled === tree ? input : _extends({}, input, {
+        nodes: _extends({}, input['nodes'], settled.nodes)
+    });
+}
 /**
  * The whole check on one emitted tree: the palette validator first, then
  * every tree rule, then the budget. `otherPages` are the trees generated