@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/runtime/ai-node-tree.d.ts

@@ -0,0 +1,181 @@
+/**
+ * @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 AiSurface } from './ai-palette';
+import { type NodesMap } from '@aglyn/aglyn/types/nodes';
+import type { AiComponentPropTypes } from '../model/ai-site-inventory';
+/**
+ * The one path an AI-emitted node tree takes into storage (AGL-2905).
+ *
+ * A model answers with a flat node map in the shape the canvas persists.
+ * Nothing about that map is trusted: the component ids, the parent/child
+ * pairs, every prop and every `sx` key are what the model chose to write,
+ * and the renderer spreads props onto the DOM. So the tree is first held to
+ * the same sanitizer a marketplace install passes — reachability from the
+ * root, the surface's component allowlist, the persisted node keys, `href`
+ * and `src` protocols, a size cap — and then to what a listing never needed
+ * checking because a human authored it in the editor:
+ *
+ * - the parent/child restrictions the besigner enforces on drop
+ *   (`restrictChildren` / `restrictParent`), and whether an element can hold
+ *   children at all;
+ * - every prop against the generated palette's schema — unknown props are
+ *   dropped, enum values coerced case-insensitively, a required prop that is
+ *   missing refuses the tree;
+ * - `sx` against a fixed key set and a value grammar of theme tokens, numbers
+ *   and CSS lengths or keywords, with nothing that can reach a URL or a
+ *   stylesheet;
+ * - copy length by role — a headline, a paragraph, a button label;
+ * - links to a screen the host has, a root-relative path or an `https:` URL,
+ *   and media to a DAM reference or an `https:` URL;
+ * - the stored-node-map byte ceiling, measured the way the save measures it.
+ *
+ * ## The site's own records, when the caller names them (AGL-2935)
+ *
+ * A reusable-component instance, a form picked on the Forms page and a
+ * dataset are each "a reference into another document", which is why the
+ * palette leaves them off: from a description alone a model can only invent
+ * an id. A generator that has read the site's inventory can name real ones,
+ * and the building doctrine requires it to — a repeat is placed as
+ * instances of one component, and a form is bound by id rather than drawn
+ * inline. So the three are admitted exactly as screen links are: only
+ * against the ids the caller supplies. With no `componentIds` an instance is
+ * still refused; with no `formIds` or `datasetIds` the binding is dropped.
+ *
+ * What comes out is the flat `NodesMap` `encodeStoredNodes` takes, with every
+ * id minted fresh the way a preset graft mints them, so nothing the model
+ * wrote can collide with a node already on the canvas. `sourceIds` maps each
+ * minted id back to the id the model wrote, so a caller can quote a refused
+ * subtree in the model's own words. Every drop is listed in `repairs`; every
+ * refusal names its `code`. The function never throws.
+ */
+export type AiNodeTreeRefusalCode = 
+/** Not an object with a `rootId` and a `nodes` map, or an unknown surface. */
+'invalid-input'
+/** The root node carries a component the surface does not start with. */
+ | 'root'
+/** A structural failure the sanitizer named: missing node, empty tree. */
+ | 'structure'
+/** A component id outside the surface's allowlist. */
+ | 'component'
+/** A parent/child pair the besigner would refuse on drop. */
+ | 'lineage'
+/** A prop the palette marks required is absent. */
+ | 'required-prop'
+/** Over the sanitizer's or the stored-node-map's byte ceiling. */
+ | 'too-large'
+/** A component instance naming a component the site does not have. */
+ | 'reference';
+export type AiNodeTreeResult = {
+    ok: true;
+    rootId: string;
+    nodes: NodesMap;
+    repairs: string[];
+    /** Each minted id → the id the model wrote for that node. */
+    sourceIds: Record<string, string>;
+} | {
+    ok: false;
+    error: string;
+    code: AiNodeTreeRefusalCode;
+};
+export interface AiNodeTreeContext {
+    /** Screen ids a `screen` prop may name. Absent: any well-formed id. */
+    screenIds?: Iterable<string>;
+    /** DAM media ids a `media` prop may reference. Absent: any well-formed reference. */
+    assetIds?: Iterable<string>;
+    /**
+     * Reusable components an instance may place. Absent: no instance is
+     * admitted, which is the palette's own rule for a tree nobody grounded.
+     */
+    componentIds?: Iterable<string>;
+    /** Declared props per component id, which an instance's values are held to. */
+    componentProps?: Record<string, AiComponentPropTypes>;
+    /** Forms on the Forms page a Form element may bind by `formId`. */
+    formIds?: Iterable<string>;
+    /** Datasets a Form element may write to by `datasetId`. */
+    datasetIds?: Iterable<string>;
+    /**
+     * Binding tokens a `url` or `media` prop may hold whole — an Image whose
+     * `src` is `{{entry.coverImage}}` on a page template, filled per record
+     * when the page renders (AGL-2909). Absent: a token in either role is
+     * dropped like any other value that is not an address.
+     */
+    bindingTokens?: Iterable<string>;
+    /**
+     * The tree defines a reusable component (AGL-2908). A field that is not
+     * copy — a switch, a dropdown, a screen, an address, a picture, a number —
+     * and the `hideIf` and `hideUnless` directives may then hold one of the
+     * component's own `{{prop.<name>}}` tokens as their whole value, and a
+     * placed component may be handed one in its `propValues`; each is kept as
+     * written. Which property a token names, and whether its kind binds to that
+     * field, is the component step's check (`ai-component-bindings.ts`).
+     * Absent: such a token is dropped like any value the field cannot hold.
+     */
+    definesComponent?: boolean;
+}
+/**
+ * `sx` keys a model may set: spacing, color, typography, layout, borders,
+ * display, flex and grid. Fixed rather than derived — MUI's system accepts
+ * far more (pseudo-selectors, nested selectors, arbitrary CSS properties)
+ * and every one of those is a way to reach outside the element.
+ */
+export declare const AI_SX_ALLOWED_KEYS: ReadonlySet<string>;
+/**
+ * Substrings no string a model wrote may carry, in a prop or an `sx` value.
+ * Exported for the theme tool's component style values (AGL-2938), which are
+ * the same kind of CSS value written into a theme instead of a node.
+ */
+export declare const HOSTILE_TEXT: RegExp;
+/**
+ * A CSS value a model may write into `sx`: lengths, numbers, keywords,
+ * shorthands (`1px solid`), functions with plain arguments (`repeat(3, 1fr)`,
+ * `rgba(0, 0, 0, 0.2)`), hex colors and theme tokens. No quotes, no
+ * semicolons, no braces, no angle brackets, no colons — which is what keeps
+ * a `url(`, a selector or a second declaration out.
+ */
+export declare const SX_VALUE: RegExp;
+/** An `https:` address that parses as one. */
+export declare function isHttpsUrl(value: string): boolean;
+/** A path on this site: one leading slash, never a scheme-relative `//`. */
+export declare function isRootRelativePath(value: string): boolean;
+/** The instance prop naming the component it places; stored on every instance node. */
+export declare const AI_INSTANCE_REF_PROP = "refId";
+export declare function validateAiNodeTree(input: unknown, surface: AiSurface, context?: AiNodeTreeContext): AiNodeTreeResult;
+export type AiNodePatchResult = {
+    ok: true;
+    props: Record<string, unknown>;
+    sx: Record<string, unknown> | undefined;
+    repairs: string[];
+} | {
+    ok: false;
+    error: string;
+    code: AiNodeTreeRefusalCode;
+};
+/**
+ * One element's prop and style patch, held to the rules `validateAiNodeTree`
+ * holds an element it places — for an edit to an element already on the
+ * canvas, where there is no tree to validate.
+ *
+ * The same passes run: unknown props dropped, enums coerced, every string
+ * held to its role and screened for markup, `sx` held to the key set and the
+ * value grammar. The one difference is `required`: a patch is merged over the
+ * props the element already has, so a required prop the patch does not name
+ * is not missing.
+ */
+export declare function validateAiNodePatch(componentId: string, patch: {
+    props?: unknown;
+    sx?: unknown;
+}, context?: AiNodeTreeContext): AiNodePatchResult;