@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/runtime/ai-abuse-guards.js

@@ -0,0 +1,148 @@
+/**
+ * @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 { resolveEffectivePlan } from "@aglyn/aglyn/app-utils/plan-entitlements";
+import { readClientIp } from "@aglyn/aglyn/app-utils/request-ip";
+import { checkRateLimit } from "@aglyn/tenant-data-admin/server/api-http";
+/**
+ * The request-level rungs the Free AI taste adds to every AI door
+ * (AGL-2925): a per-address limiter and a minimum account age. Both are
+ * small helpers a door calls from its ladder rather than rungs written
+ * into each ladder, so the three doors and the shared gate cannot drift
+ * into three limits.
+ *
+ * Neither touches Firestore. The limiter is the same per-instance window
+ * as the per-uid one and carries the same caveat — it smooths bursts and is
+ * not the spend bound; the reservation is. The account-age rung reads one
+ * Auth record, cached per instance, and applies only to a Free workspace.
+ */ /** Requests one client address may make against the AI doors a minute. */ export const AI_IP_RATE_LIMIT = 60;
+export const AI_IP_RATE_WINDOW_MS = 60000;
+/**
+ * The per-address window shared by every AI door.
+ *
+ * Keyed on the TRUSTED-HOP client address (`readClientIp`), never on a
+ * header a caller can write, for the reason that module exists: on an
+ * appending proxy the leftmost `x-forwarded-for` hop is whatever the caller
+ * typed, and a limiter keyed on it hands out a fresh budget per request.
+ * `null` when no address is readable — the caller skips the rung, because
+ * keying every anonymous request under one placeholder caps the whole
+ * install at sixty requests a minute.
+ *
+ * Sixty a minute is three times the per-uid window (20/min at each door):
+ * an office NAT signing in a team of three fits under it, and a farm
+ * rotating accounts behind one address does not.
+ */ export function checkAiClientIpRateLimit(headers) {
+    const ip = readClientIp(headers);
+    if (!ip) return null;
+    return checkRateLimit(`ai-ip:${ip}`, {
+        limit: AI_IP_RATE_LIMIT,
+        windowMs: AI_IP_RATE_WINDOW_MS
+    });
+}
+/**
+ * How old an account must be before a Free workspace it belongs to may
+ * generate (`AI_FREE_MIN_ACCOUNT_AGE_HOURS`, default 24).
+ *
+ * The signup surface already costs a working inbox per account; a day of
+ * age costs a day, which is the one thing a script minting accounts cannot
+ * buy in bulk. Paid workspaces never consult it. Zero switches the rung
+ * off, which a self-hoster running an invite-only deployment may
+ * reasonably want; junk and an empty value take the default.
+ */ export function aiFreeMinAccountAgeHours() {
+    const raw = process.env.AI_FREE_MIN_ACCOUNT_AGE_HOURS;
+    const parsed = raw ? Number(raw) : Number.NaN;
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : 24;
+}
+/** How long one account's creation time is remembered per instance. */ export const ACCOUNT_AGE_CACHE_TTL_MS = 5 * 60 * 1000;
+/**
+ * Entries the cache holds before it is dropped whole. A creation time is a
+ * few bytes, but a limiter that can be made to remember every uid ever
+ * seen is a memory leak with a use case, so the map is bounded and simply
+ * forgets everything when it fills — the next request re-reads.
+ */ export const ACCOUNT_AGE_CACHE_MAX_ENTRIES = 5000;
+let accountAgeCache = new Map();
+/** Test seam — drops the per-instance cache. */ export function resetAccountAgeCache() {
+    accountAgeCache = new Map();
+}
+/**
+ * When the account was created, in epoch milliseconds, or `null` when the
+ * record carries no usable creation time.
+ *
+ * Read through the caller's `getUser` — the Auth pool the token was minted
+ * in — because the decoded token carries `auth_time` (this sign-in) and
+ * not the account's creation, and a fresh account can sign in as often as
+ * it likes. Cached per instance for a few minutes: the value never changes,
+ * and the doors are called far more often than once per account.
+ */ export async function accountCreationTimeMs(uid, getUser, now = Date.now()) {
+    var _ref;
+    var _record_metadata;
+    const cached = accountAgeCache.get(uid);
+    if (cached && now - cached.at < ACCOUNT_AGE_CACHE_TTL_MS) {
+        return cached.creationTimeMs;
+    }
+    const record = await getUser(uid);
+    const creationTimeMs = Date.parse((_ref = (_record_metadata = record.metadata) == null ? void 0 : _record_metadata.creationTime) != null ? _ref : '');
+    if (!Number.isFinite(creationTimeMs)) return null;
+    if (accountAgeCache.size >= ACCOUNT_AGE_CACHE_MAX_ENTRIES) resetAccountAgeCache();
+    accountAgeCache.set(uid, {
+        creationTimeMs,
+        at: now
+    });
+    return creationTimeMs;
+}
+/**
+ * The account-age rung: the `Response` to send, or `null` to climb on.
+ *
+ * Applies to a FREE workspace only — `resolveEffectivePlan`, so a dead
+ * subscription is Free here as everywhere — and never to staff, who are
+ * the ones verifying the fix during an incident. An account younger than
+ * the minimum is a 403 with `reason: 'account-age'`, and the sentence says
+ * when to come back rather than hinting at a way around it.
+ *
+ * Fails CLOSED for a Free workspace: a record that cannot be read is a
+ * 503, not an admission. The verifier just accepted this token from the
+ * same Auth service, so the read failing is rare, and the rung exists
+ * precisely for the request whose age cannot be vouched for. A paid
+ * workspace never reaches the read.
+ */ export async function freeAccountAgeRefusal(input) {
+    var _input_now;
+    if (input.staff) return null;
+    if (resolveEffectivePlan(input.org) !== 'free') return null;
+    const hours = aiFreeMinAccountAgeHours();
+    if (hours <= 0) return null;
+    const now = (_input_now = input.now) != null ? _input_now : new Date();
+    let createdMs;
+    try {
+        createdMs = await accountCreationTimeMs(input.uid, input.getUser, now.getTime());
+    } catch (error) {
+        console.error('[ai-abuse-guards] account age unavailable', error);
+        return Response.json({
+            error: 'This feature is temporarily unavailable'
+        }, {
+            status: 503
+        });
+    }
+    const ageMs = createdMs === null ? 0 : now.getTime() - createdMs;
+    if (ageMs >= hours * 60 * 60 * 1000) return null;
+    const label = hours === 1 ? '1 hour' : `${hours} hours`;
+    return Response.json({
+        error: `AI generation opens ${label} after an account is created — ` + 'come back then, or upgrade this workspace to use it now.',
+        reason: 'account-age'
+    }, {
+        status: 403
+    });
+}
+
+//# sourceMappingURL=ai-abuse-guards.js.map

package/src/lib/runtime/ai-abuse-guards.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/runtime/ai-abuse-guards.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { resolveEffectivePlan } from '@aglyn/aglyn/app-utils/plan-entitlements'\nimport {\n  readClientIp,\n  type ClientIpHeaders,\n} from '@aglyn/aglyn/app-utils/request-ip'\nimport type { AglynOrgBilling } from '@aglyn/aglyn/foundation/definitions/org-billing.types'\nimport { checkRateLimit, type RateLimitResult } from '@aglyn/tenant-data-admin/server/api-http'\n\n/**\n * The request-level rungs the Free AI taste adds to every AI door\n * (AGL-2925): a per-address limiter and a minimum account age. Both are\n * small helpers a door calls from its ladder rather than rungs written\n * into each ladder, so the three doors and the shared gate cannot drift\n * into three limits.\n *\n * Neither touches Firestore. The limiter is the same per-instance window\n * as the per-uid one and carries the same caveat — it smooths bursts and is\n * not the spend bound; the reservation is. The account-age rung reads one\n * Auth record, cached per instance, and applies only to a Free workspace.\n */\n\n/** Requests one client address may make against the AI doors a minute. */\nexport const AI_IP_RATE_LIMIT = 60\nexport const AI_IP_RATE_WINDOW_MS = 60_000\n\n/**\n * The per-address window shared by every AI door.\n *\n * Keyed on the TRUSTED-HOP client address (`readClientIp`), never on a\n * header a caller can write, for the reason that module exists: on an\n * appending proxy the leftmost `x-forwarded-for` hop is whatever the caller\n * typed, and a limiter keyed on it hands out a fresh budget per request.\n * `null` when no address is readable — the caller skips the rung, because\n * keying every anonymous request under one placeholder caps the whole\n * install at sixty requests a minute.\n *\n * Sixty a minute is three times the per-uid window (20/min at each door):\n * an office NAT signing in a team of three fits under it, and a farm\n * rotating accounts behind one address does not.\n */\nexport function checkAiClientIpRateLimit(\n  headers: ClientIpHeaders,\n): RateLimitResult | null {\n  const ip = readClientIp(headers)\n  if (!ip) return null\n  return checkRateLimit(`ai-ip:${ip}`, {\n    limit: AI_IP_RATE_LIMIT,\n    windowMs: AI_IP_RATE_WINDOW_MS,\n  })\n}\n\n/**\n * How old an account must be before a Free workspace it belongs to may\n * generate (`AI_FREE_MIN_ACCOUNT_AGE_HOURS`, default 24).\n *\n * The signup surface already costs a working inbox per account; a day of\n * age costs a day, which is the one thing a script minting accounts cannot\n * buy in bulk. Paid workspaces never consult it. Zero switches the rung\n * off, which a self-hoster running an invite-only deployment may\n * reasonably want; junk and an empty value take the default.\n */\nexport function aiFreeMinAccountAgeHours(): number {\n  const raw = process.env.AI_FREE_MIN_ACCOUNT_AGE_HOURS\n  const parsed = raw ? Number(raw) : Number.NaN\n  return Number.isFinite(parsed) && parsed >= 0 ? parsed : 24\n}\n\n/** How long one account's creation time is remembered per instance. */\nexport const ACCOUNT_AGE_CACHE_TTL_MS = 5 * 60 * 1000\n\n/**\n * Entries the cache holds before it is dropped whole. A creation time is a\n * few bytes, but a limiter that can be made to remember every uid ever\n * seen is a memory leak with a use case, so the map is bounded and simply\n * forgets everything when it fills — the next request re-reads.\n */\nexport const ACCOUNT_AGE_CACHE_MAX_ENTRIES = 5_000\n\nlet accountAgeCache = new Map<string, { creationTimeMs: number; at: number }>()\n\n/** Test seam — drops the per-instance cache. */\nexport function resetAccountAgeCache(): void {\n  accountAgeCache = new Map()\n}\n\n/** The one thing this rung reads off an Auth record. */\nexport interface AccountAgeLookup {\n  (uid: string): Promise<{ metadata: { creationTime?: string | null } }>\n}\n\n/**\n * When the account was created, in epoch milliseconds, or `null` when the\n * record carries no usable creation time.\n *\n * Read through the caller's `getUser` — the Auth pool the token was minted\n * in — because the decoded token carries `auth_time` (this sign-in) and\n * not the account's creation, and a fresh account can sign in as often as\n * it likes. Cached per instance for a few minutes: the value never changes,\n * and the doors are called far more often than once per account.\n */\nexport async function accountCreationTimeMs(\n  uid: string,\n  getUser: AccountAgeLookup,\n  now = Date.now(),\n): Promise<number | null> {\n  const cached = accountAgeCache.get(uid)\n  if (cached && now - cached.at < ACCOUNT_AGE_CACHE_TTL_MS) {\n    return cached.creationTimeMs\n  }\n  const record = await getUser(uid)\n  const creationTimeMs = Date.parse(record.metadata?.creationTime ?? '')\n  if (!Number.isFinite(creationTimeMs)) return null\n  if (accountAgeCache.size >= ACCOUNT_AGE_CACHE_MAX_ENTRIES) resetAccountAgeCache()\n  accountAgeCache.set(uid, { creationTimeMs, at: now })\n  return creationTimeMs\n}\n\n/**\n * The account-age rung: the `Response` to send, or `null` to climb on.\n *\n * Applies to a FREE workspace only — `resolveEffectivePlan`, so a dead\n * subscription is Free here as everywhere — and never to staff, who are\n * the ones verifying the fix during an incident. An account younger than\n * the minimum is a 403 with `reason: 'account-age'`, and the sentence says\n * when to come back rather than hinting at a way around it.\n *\n * Fails CLOSED for a Free workspace: a record that cannot be read is a\n * 503, not an admission. The verifier just accepted this token from the\n * same Auth service, so the read failing is rare, and the rung exists\n * precisely for the request whose age cannot be vouched for. A paid\n * workspace never reaches the read.\n */\nexport async function freeAccountAgeRefusal(input: {\n  uid: string\n  org: Partial<AglynOrgBilling> | null | undefined\n  staff: boolean\n  getUser: AccountAgeLookup\n  now?: Date\n}): Promise<Response | null> {\n  if (input.staff) return null\n  if (resolveEffectivePlan(input.org) !== 'free') return null\n  const hours = aiFreeMinAccountAgeHours()\n  if (hours <= 0) return null\n  const now = input.now ?? new Date()\n  let createdMs: number | null\n  try {\n    createdMs = await accountCreationTimeMs(input.uid, input.getUser, now.getTime())\n  } catch (error) {\n    console.error('[ai-abuse-guards] account age unavailable', error)\n    return Response.json(\n      { error: 'This feature is temporarily unavailable' },\n      { status: 503 },\n    )\n  }\n  const ageMs = createdMs === null ? 0 : now.getTime() - createdMs\n  if (ageMs >= hours * 60 * 60 * 1000) return null\n  const label = hours === 1 ? '1 hour' : `${hours} hours`\n  return Response.json(\n    {\n      error:\n        `AI generation opens ${label} after an account is created — ` +\n        'come back then, or upgrade this workspace to use it now.',\n      reason: 'account-age',\n    },\n    { status: 403 },\n  )\n}\n"],"names":["resolveEffectivePlan","readClientIp","checkRateLimit","AI_IP_RATE_LIMIT","AI_IP_RATE_WINDOW_MS","checkAiClientIpRateLimit","headers","ip","limit","windowMs","aiFreeMinAccountAgeHours","raw","process","env","AI_FREE_MIN_ACCOUNT_AGE_HOURS","parsed","Number","NaN","isFinite","ACCOUNT_AGE_CACHE_TTL_MS","ACCOUNT_AGE_CACHE_MAX_ENTRIES","accountAgeCache","Map","resetAccountAgeCache","accountCreationTimeMs","uid","getUser","now","Date","record","cached","get","at","creationTimeMs","parse","metadata","creationTime","size","set","freeAccountAgeRefusal","input","staff","org","hours","createdMs","getTime","error","console","Response","json","status","ageMs","label","reason"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,oBAAoB,QAAQ,2CAA0C;AAC/E,SACEC,YAAY,QAEP,oCAAmC;AAE1C,SAASC,cAAc,QAA8B,2CAA0C;AAE/F;;;;;;;;;;;CAWC,GAED,wEAAwE,GACxE,OAAO,MAAMC,mBAAmB,GAAE;AAClC,OAAO,MAAMC,uBAAuB,MAAM;AAE1C;;;;;;;;;;;;;;CAcC,GACD,OAAO,SAASC,yBACdC,OAAwB;IAExB,MAAMC,KAAKN,aAAaK;IACxB,IAAI,CAACC,IAAI,OAAO;IAChB,OAAOL,eAAe,CAAC,MAAM,EAAEK,IAAI,EAAE;QACnCC,OAAOL;QACPM,UAAUL;IACZ;AACF;AAEA;;;;;;;;;CASC,GACD,OAAO,SAASM;IACd,MAAMC,MAAMC,QAAQC,GAAG,CAACC,6BAA6B;IACrD,MAAMC,SAASJ,MAAMK,OAAOL,OAAOK,OAAOC,GAAG;IAC7C,OAAOD,OAAOE,QAAQ,CAACH,WAAWA,UAAU,IAAIA,SAAS;AAC3D;AAEA,qEAAqE,GACrE,OAAO,MAAMI,2BAA2B,IAAI,KAAK,KAAI;AAErD;;;;;CAKC,GACD,OAAO,MAAMC,gCAAgC,KAAK;AAElD,IAAIC,kBAAkB,IAAIC;AAE1B,8CAA8C,GAC9C,OAAO,SAASC;IACdF,kBAAkB,IAAIC;AACxB;AAOA;;;;;;;;;CASC,GACD,OAAO,eAAeE,sBACpBC,GAAW,EACXC,OAAyB,EACzBC,MAAMC,KAAKD,GAAG,EAAE;;QAOkBE;IALlC,MAAMC,SAAST,gBAAgBU,GAAG,CAACN;IACnC,IAAIK,UAAUH,MAAMG,OAAOE,EAAE,GAAGb,0BAA0B;QACxD,OAAOW,OAAOG,cAAc;IAC9B;IACA,MAAMJ,SAAS,MAAMH,QAAQD;IAC7B,MAAMQ,iBAAiBL,KAAKM,KAAK,UAACL,mBAAAA,OAAOM,QAAQ,qBAAfN,iBAAiBO,YAAY,mBAAI;IACnE,IAAI,CAACpB,OAAOE,QAAQ,CAACe,iBAAiB,OAAO;IAC7C,IAAIZ,gBAAgBgB,IAAI,IAAIjB,+BAA+BG;IAC3DF,gBAAgBiB,GAAG,CAACb,KAAK;QAAEQ;QAAgBD,IAAIL;IAAI;IACnD,OAAOM;AACT;AAEA;;;;;;;;;;;;;;CAcC,GACD,OAAO,eAAeM,sBAAsBC,KAM3C;QAKaA;IAJZ,IAAIA,MAAMC,KAAK,EAAE,OAAO;IACxB,IAAIzC,qBAAqBwC,MAAME,GAAG,MAAM,QAAQ,OAAO;IACvD,MAAMC,QAAQjC;IACd,IAAIiC,SAAS,GAAG,OAAO;IACvB,MAAMhB,OAAMa,aAAAA,MAAMb,GAAG,YAATa,aAAa,IAAIZ;IAC7B,IAAIgB;IACJ,IAAI;QACFA,YAAY,MAAMpB,sBAAsBgB,MAAMf,GAAG,EAAEe,MAAMd,OAAO,EAAEC,IAAIkB,OAAO;IAC/E,EAAE,OAAOC,OAAO;QACdC,QAAQD,KAAK,CAAC,6CAA6CA;QAC3D,OAAOE,SAASC,IAAI,CAClB;YAAEH,OAAO;QAA0C,GACnD;YAAEI,QAAQ;QAAI;IAElB;IACA,MAAMC,QAAQP,cAAc,OAAO,IAAIjB,IAAIkB,OAAO,KAAKD;IACvD,IAAIO,SAASR,QAAQ,KAAK,KAAK,MAAM,OAAO;IAC5C,MAAMS,QAAQT,UAAU,IAAI,WAAW,GAAGA,MAAM,MAAM,CAAC;IACvD,OAAOK,SAASC,IAAI,CAClB;QACEH,OACE,CAAC,oBAAoB,EAAEM,MAAM,+BAA+B,CAAC,GAC7D;QACFC,QAAQ;IACV,GACA;QAAEH,QAAQ;IAAI;AAElB"}

package/src/lib/runtime/ai-component-bindings.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @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 { ReusableComponentProp } from '@aglyn/aglyn/foundation/definitions/platform.types';
+import type { AiPaletteEntry } from './ai-palette';
+/**
+ * Which field of a generated reusable component may carry which of the
+ * component's own properties (AGL-2908).
+ *
+ * A component's tree reaches its properties through `{{prop.<name>}}` tokens,
+ * and the graft hands each field the value its property's kind holds
+ * (`resolveComponentPropTokens`). So a binding is right only where the field
+ * can show that value:
+ *
+ * - A field that is not typed into — a switch, a dropdown, a screen picker, a
+ *   slider — takes exactly the properties the Attributes panel offers it
+ *   under its `{}` (AGL-2871): `reusablePropBindsToField`, the editor's own
+ *   judgment, over the field kind the palette records. The token is the
+ *   field's whole value.
+ * - A field that is typed into takes any token in the editor. A generated
+ *   binding is held to what reads right there: copy in copy (Text, Long text
+ *   or Number, whole or inside a sentence), a picture as an image's source
+ *   and a link as an address, each as the whole value.
+ * - The visibility directives are switches the graft reads before anything
+ *   renders: `hideIf` takes a Yes / no, and `hideUnless` a Link, whose
+ *   absence hides the part.
+ *
+ * Pure: the palette validator reads it to keep a token as written, and the
+ * component step's check reads it to hold each token to its property.
+ */
+/** A declared property, as a binding reads it. */
+export type AiComponentPropBinding = Pick<ReusableComponentProp, 'name' | 'type' | 'options' | 'settings'>;
+/** Where a token sits in a field's value: the whole value, or inside copy. */
+export type AiComponentPropPlacement = 'whole' | 'inside';
+/** The node props a component's tree may bind that no element declares. */
+export declare const AI_COMPONENT_VISIBILITY_PROPS: readonly string[];
+/** Kinds whose value reads as copy, which copy may carry inside a sentence. */
+export declare const AI_COMPONENT_COPY_KINDS: ReadonlySet<string>;
+/** Where a property of a kind is bound, for a finding that names it; copy for a kind with no entry. */
+export declare function aiComponentKindBindsTo(type: string): string;
+/** Whether a value is exactly one component property token. */
+export declare function isAiComponentPropToken(value: unknown): value is string;
+/** The property names a value's tokens name, each once, in order. */
+export declare function aiComponentPropNamesIn(value: unknown): string[];
+type PaletteFields = Pick<AiPaletteEntry, 'propsSchema' | 'propRoles' | 'propFields'>;
+/**
+ * Whether a property may be bound to one field of an element, placed as it
+ * is. `field` is a prop the palette declares for the element, or one of the
+ * visibility directives.
+ */
+export declare function aiComponentPropBindsToField(prop: AiComponentPropBinding, entry: PaletteFields | undefined, field: string, placement: AiComponentPropPlacement): boolean;
+/** The answers of a property that the field it is bound to does not list. */
+export declare function aiComponentUnofferedAnswers(prop: AiComponentPropBinding, entry: PaletteFields | undefined, field: string): string[];
+export {};

package/src/lib/runtime/ai-component-bindings.js

@@ -0,0 +1,106 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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 { matchComponentPropToken } from "@aglyn/aglyn/app-utils/compose-reusable-components";
+import { NODE_HIDE_IF_PROP, NODE_HIDE_UNLESS_PROP } from "@aglyn/aglyn/app-utils/reusable-component-keys";
+import { attributeFieldValueShape, reusablePropBindsToField, reusablePropValueShape, unofferedChoiceValues } from "@aglyn/aglyn/foundation/definitions/property-kinds";
+import { aiBindingTokensIn } from "../model/ai-template-subjects.js";
+/** The node props a component's tree may bind that no element declares. */ export const AI_COMPONENT_VISIBILITY_PROPS = [
+    NODE_HIDE_IF_PROP,
+    NODE_HIDE_UNLESS_PROP
+];
+/** Kinds whose value reads as copy, which copy may carry inside a sentence. */ export const AI_COMPONENT_COPY_KINDS = new Set([
+    'text',
+    'richText',
+    'number'
+]);
+/**
+ * Where a property of each offered kind is bound, in the words a re-ask gives
+ * a model that declared one and bound it nowhere (AGL-3054): the fields
+ * `aiComponentPropBindsToField` admits for the kind, by an example.
+ */ const AI_COMPONENT_KIND_BINDS_TO = {
+    text: 'copy, such as a Typography’s children or a Button’s label',
+    richText: 'copy, such as a Typography’s children',
+    number: 'copy, or a number setting',
+    image: 'an Image’s src',
+    href: 'a screenId or an href',
+    icon: 'an Icon element’s iconId',
+    boolean: 'a switch setting such as a Button’s fullWidth, or hideIf on the part it hides',
+    choice: 'a setting with fixed options, such as a Button’s variant'
+};
+/** Where a property of a kind is bound, for a finding that names it; copy for a kind with no entry. */ export function aiComponentKindBindsTo(type) {
+    var _AI_COMPONENT_KIND_BINDS_TO_type;
+    return (_AI_COMPONENT_KIND_BINDS_TO_type = AI_COMPONENT_KIND_BINDS_TO[type]) != null ? _AI_COMPONENT_KIND_BINDS_TO_type : AI_COMPONENT_KIND_BINDS_TO['text'];
+}
+/** Whether a value is exactly one component property token. */ export function isAiComponentPropToken(value) {
+    return matchComponentPropToken(value) !== null;
+}
+/** The property names a value's tokens name, each once, in order. */ export function aiComponentPropNamesIn(value) {
+    if (typeof value !== 'string' || !value.includes('{{')) return [];
+    const names = [];
+    for (const token of aiBindingTokensIn(value)){
+        const name = matchComponentPropToken(token);
+        if (name && !names.includes(name)) names.push(name);
+    }
+    return names;
+}
+/** A palette prop as the attribute field the editor draws it with. */ function attributeField(entry, field) {
+    const schema = entry.propsSchema.properties[field];
+    const component = entry.propFields[field];
+    if (!schema || !component) return null;
+    return _extends({
+        component
+    }, schema.enum ? {
+        options: schema.enum.map((value)=>({
+                value
+            }))
+    } : {});
+}
+/**
+ * Whether a property may be bound to one field of an element, placed as it
+ * is. `field` is a prop the palette declares for the element, or one of the
+ * visibility directives.
+ */ export function aiComponentPropBindsToField(prop, entry, field, placement) {
+    var _prop_type;
+    if (field === NODE_HIDE_IF_PROP) {
+        return placement === 'whole' && reusablePropValueShape(prop) === 'boolean';
+    }
+    if (field === NODE_HIDE_UNLESS_PROP) {
+        return placement === 'whole' && prop.type === 'href';
+    }
+    const declared = entry ? attributeField(entry, field) : null;
+    if (!entry || !declared) return false;
+    if (attributeFieldValueShape(declared) !== undefined) {
+        return placement === 'whole' && reusablePropBindsToField(prop, declared);
+    }
+    const type = (_prop_type = prop.type) != null ? _prop_type : 'text';
+    switch(entry.propRoles[field]){
+        case 'url':
+            return placement === 'whole' && type === 'href';
+        case 'media':
+            return placement === 'whole' && type === 'image';
+        case 'text':
+            return AI_COMPONENT_COPY_KINDS.has(type);
+        default:
+            return false;
+    }
+}
+/** The answers of a property that the field it is bound to does not list. */ export function aiComponentUnofferedAnswers(prop, entry, field) {
+    const declared = entry ? attributeField(entry, field) : null;
+    return unofferedChoiceValues(prop, declared == null ? void 0 : declared.options);
+}
+
+//# sourceMappingURL=ai-component-bindings.js.map

package/src/lib/runtime/ai-component-bindings.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/runtime/ai-component-bindings.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { matchComponentPropToken } from '@aglyn/aglyn/app-utils/compose-reusable-components'\nimport {\n  NODE_HIDE_IF_PROP,\n  NODE_HIDE_UNLESS_PROP,\n} from '@aglyn/aglyn/app-utils/reusable-component-keys'\nimport type { ReusableComponentProp } from '@aglyn/aglyn/foundation/definitions/platform.types'\nimport {\n  attributeFieldValueShape,\n  reusablePropBindsToField,\n  reusablePropValueShape,\n  unofferedChoiceValues,\n} from '@aglyn/aglyn/foundation/definitions/property-kinds'\nimport { aiBindingTokensIn } from '../model/ai-template-subjects'\nimport type { AiPaletteEntry } from './ai-palette'\n\n/**\n * Which field of a generated reusable component may carry which of the\n * component's own properties (AGL-2908).\n *\n * A component's tree reaches its properties through `{{prop.<name>}}` tokens,\n * and the graft hands each field the value its property's kind holds\n * (`resolveComponentPropTokens`). So a binding is right only where the field\n * can show that value:\n *\n * - A field that is not typed into — a switch, a dropdown, a screen picker, a\n *   slider — takes exactly the properties the Attributes panel offers it\n *   under its `{}` (AGL-2871): `reusablePropBindsToField`, the editor's own\n *   judgment, over the field kind the palette records. The token is the\n *   field's whole value.\n * - A field that is typed into takes any token in the editor. A generated\n *   binding is held to what reads right there: copy in copy (Text, Long text\n *   or Number, whole or inside a sentence), a picture as an image's source\n *   and a link as an address, each as the whole value.\n * - The visibility directives are switches the graft reads before anything\n *   renders: `hideIf` takes a Yes / no, and `hideUnless` a Link, whose\n *   absence hides the part.\n *\n * Pure: the palette validator reads it to keep a token as written, and the\n * component step's check reads it to hold each token to its property.\n */\n\n/** A declared property, as a binding reads it. */\nexport type AiComponentPropBinding = Pick<\n  ReusableComponentProp,\n  'name' | 'type' | 'options' | 'settings'\n>\n\n/** Where a token sits in a field's value: the whole value, or inside copy. */\nexport type AiComponentPropPlacement = 'whole' | 'inside'\n\n/** The node props a component's tree may bind that no element declares. */\nexport const AI_COMPONENT_VISIBILITY_PROPS: readonly string[] = [\n  NODE_HIDE_IF_PROP,\n  NODE_HIDE_UNLESS_PROP,\n]\n\n/** Kinds whose value reads as copy, which copy may carry inside a sentence. */\nexport const AI_COMPONENT_COPY_KINDS: ReadonlySet<string> = new Set(['text', 'richText', 'number'])\n\n/**\n * Where a property of each offered kind is bound, in the words a re-ask gives\n * a model that declared one and bound it nowhere (AGL-3054): the fields\n * `aiComponentPropBindsToField` admits for the kind, by an example.\n */\nconst AI_COMPONENT_KIND_BINDS_TO: Readonly<Record<string, string>> = {\n  text: 'copy, such as a Typography’s children or a Button’s label',\n  richText: 'copy, such as a Typography’s children',\n  number: 'copy, or a number setting',\n  image: 'an Image’s src',\n  href: 'a screenId or an href',\n  icon: 'an Icon element’s iconId',\n  boolean: 'a switch setting such as a Button’s fullWidth, or hideIf on the part it hides',\n  choice: 'a setting with fixed options, such as a Button’s variant',\n}\n\n/** Where a property of a kind is bound, for a finding that names it; copy for a kind with no entry. */\nexport function aiComponentKindBindsTo(type: string): string {\n  return AI_COMPONENT_KIND_BINDS_TO[type] ?? AI_COMPONENT_KIND_BINDS_TO['text']\n}\n\n/** Whether a value is exactly one component property token. */\nexport function isAiComponentPropToken(value: unknown): value is string {\n  return matchComponentPropToken(value) !== null\n}\n\n/** The property names a value's tokens name, each once, in order. */\nexport function aiComponentPropNamesIn(value: unknown): string[] {\n  if (typeof value !== 'string' || !value.includes('{{')) return []\n  const names: string[] = []\n  for (const token of aiBindingTokensIn(value)) {\n    const name = matchComponentPropToken(token)\n    if (name && !names.includes(name)) names.push(name)\n  }\n  return names\n}\n\ntype PaletteFields = Pick<AiPaletteEntry, 'propsSchema' | 'propRoles' | 'propFields'>\n\n/** A palette prop as the attribute field the editor draws it with. */\nfunction attributeField(\n  entry: PaletteFields,\n  field: string,\n): { component: string; options?: Array<{ value: string }> } | null {\n  const schema = entry.propsSchema.properties[field]\n  const component = entry.propFields[field]\n  if (!schema || !component) return null\n  return {\n    component,\n    ...(schema.enum ? { options: schema.enum.map((value) => ({ value })) } : {}),\n  }\n}\n\n/**\n * Whether a property may be bound to one field of an element, placed as it\n * is. `field` is a prop the palette declares for the element, or one of the\n * visibility directives.\n */\nexport function aiComponentPropBindsToField(\n  prop: AiComponentPropBinding,\n  entry: PaletteFields | undefined,\n  field: string,\n  placement: AiComponentPropPlacement,\n): boolean {\n  if (field === NODE_HIDE_IF_PROP) {\n    return placement === 'whole' && reusablePropValueShape(prop) === 'boolean'\n  }\n  if (field === NODE_HIDE_UNLESS_PROP) {\n    return placement === 'whole' && prop.type === 'href'\n  }\n  const declared = entry ? attributeField(entry, field) : null\n  if (!entry || !declared) return false\n  if (attributeFieldValueShape(declared) !== undefined) {\n    return placement === 'whole' && reusablePropBindsToField(prop, declared)\n  }\n  const type = prop.type ?? 'text'\n  switch (entry.propRoles[field]) {\n    case 'url':\n      return placement === 'whole' && type === 'href'\n    case 'media':\n      return placement === 'whole' && type === 'image'\n    case 'text':\n      return AI_COMPONENT_COPY_KINDS.has(type)\n    default:\n      return false\n  }\n}\n\n/** The answers of a property that the field it is bound to does not list. */\nexport function aiComponentUnofferedAnswers(\n  prop: AiComponentPropBinding,\n  entry: PaletteFields | undefined,\n  field: string,\n): string[] {\n  const declared = entry ? attributeField(entry, field) : null\n  return unofferedChoiceValues(prop, declared?.options)\n}\n"],"names":["matchComponentPropToken","NODE_HIDE_IF_PROP","NODE_HIDE_UNLESS_PROP","attributeFieldValueShape","reusablePropBindsToField","reusablePropValueShape","unofferedChoiceValues","aiBindingTokensIn","AI_COMPONENT_VISIBILITY_PROPS","AI_COMPONENT_COPY_KINDS","Set","AI_COMPONENT_KIND_BINDS_TO","text","richText","number","image","href","icon","boolean","choice","aiComponentKindBindsTo","type","isAiComponentPropToken","value","aiComponentPropNamesIn","includes","names","token","name","push","attributeField","entry","field","schema","propsSchema","properties","component","propFields","enum","options","map","aiComponentPropBindsToField","prop","placement","declared","undefined","propRoles","has","aiComponentUnofferedAnswers"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,uBAAuB,QAAQ,qDAAoD;AAC5F,SACEC,iBAAiB,EACjBC,qBAAqB,QAChB,iDAAgD;AAEvD,SACEC,wBAAwB,EACxBC,wBAAwB,EACxBC,sBAAsB,EACtBC,qBAAqB,QAChB,qDAAoD;AAC3D,SAASC,iBAAiB,QAAQ,mCAA+B;AAsCjE,yEAAyE,GACzE,OAAO,MAAMC,gCAAmD;IAC9DP;IACAC;CACD,CAAA;AAED,6EAA6E,GAC7E,OAAO,MAAMO,0BAA+C,IAAIC,IAAI;IAAC;IAAQ;IAAY;CAAS,EAAC;AAEnG;;;;CAIC,GACD,MAAMC,6BAA+D;IACnEC,MAAM;IACNC,UAAU;IACVC,QAAQ;IACRC,OAAO;IACPC,MAAM;IACNC,MAAM;IACNC,SAAS;IACTC,QAAQ;AACV;AAEA,qGAAqG,GACrG,OAAO,SAASC,uBAAuBC,IAAY;QAC1CV;IAAP,QAAOA,mCAAAA,0BAA0B,CAACU,KAAK,YAAhCV,mCAAoCA,0BAA0B,CAAC,OAAO;AAC/E;AAEA,6DAA6D,GAC7D,OAAO,SAASW,uBAAuBC,KAAc;IACnD,OAAOvB,wBAAwBuB,WAAW;AAC5C;AAEA,mEAAmE,GACnE,OAAO,SAASC,uBAAuBD,KAAc;IACnD,IAAI,OAAOA,UAAU,YAAY,CAACA,MAAME,QAAQ,CAAC,OAAO,OAAO,EAAE;IACjE,MAAMC,QAAkB,EAAE;IAC1B,KAAK,MAAMC,SAASpB,kBAAkBgB,OAAQ;QAC5C,MAAMK,OAAO5B,wBAAwB2B;QACrC,IAAIC,QAAQ,CAACF,MAAMD,QAAQ,CAACG,OAAOF,MAAMG,IAAI,CAACD;IAChD;IACA,OAAOF;AACT;AAIA,oEAAoE,GACpE,SAASI,eACPC,KAAoB,EACpBC,KAAa;IAEb,MAAMC,SAASF,MAAMG,WAAW,CAACC,UAAU,CAACH,MAAM;IAClD,MAAMI,YAAYL,MAAMM,UAAU,CAACL,MAAM;IACzC,IAAI,CAACC,UAAU,CAACG,WAAW,OAAO;IAClC,OAAO;QACLA;OACIH,OAAOK,IAAI,GAAG;QAAEC,SAASN,OAAOK,IAAI,CAACE,GAAG,CAAC,CAACjB,QAAW,CAAA;gBAAEA;YAAM,CAAA;IAAI,IAAI,CAAC;AAE9E;AAEA;;;;CAIC,GACD,OAAO,SAASkB,4BACdC,IAA4B,EAC5BX,KAAgC,EAChCC,KAAa,EACbW,SAAmC;QAatBD;IAXb,IAAIV,UAAU/B,mBAAmB;QAC/B,OAAO0C,cAAc,WAAWtC,uBAAuBqC,UAAU;IACnE;IACA,IAAIV,UAAU9B,uBAAuB;QACnC,OAAOyC,cAAc,WAAWD,KAAKrB,IAAI,KAAK;IAChD;IACA,MAAMuB,WAAWb,QAAQD,eAAeC,OAAOC,SAAS;IACxD,IAAI,CAACD,SAAS,CAACa,UAAU,OAAO;IAChC,IAAIzC,yBAAyByC,cAAcC,WAAW;QACpD,OAAOF,cAAc,WAAWvC,yBAAyBsC,MAAME;IACjE;IACA,MAAMvB,QAAOqB,aAAAA,KAAKrB,IAAI,YAATqB,aAAa;IAC1B,OAAQX,MAAMe,SAAS,CAACd,MAAM;QAC5B,KAAK;YACH,OAAOW,cAAc,WAAWtB,SAAS;QAC3C,KAAK;YACH,OAAOsB,cAAc,WAAWtB,SAAS;QAC3C,KAAK;YACH,OAAOZ,wBAAwBsC,GAAG,CAAC1B;QACrC;YACE,OAAO;IACX;AACF;AAEA,2EAA2E,GAC3E,OAAO,SAAS2B,4BACdN,IAA4B,EAC5BX,KAAgC,EAChCC,KAAa;IAEb,MAAMY,WAAWb,QAAQD,eAAeC,OAAOC,SAAS;IACxD,OAAO1B,sBAAsBoC,MAAME,4BAAAA,SAAUL,OAAO;AACtD"}

package/src/lib/runtime/ai-device-audit.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @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 { HostTheme } from '@aglyn/shared-data-types';
+import type { AiInventoryTheme } from '../model/ai-site-inventory';
+/**
+ * THE DEVICE AUDIT (AGL-3020): what a generated document looks like at every
+ * width the besigner's device switcher previews, and the rule a recording of
+ * it is held to.
+ *
+ * Rule 12 is held on the tree: no fixed width, and a Grid of columns is a
+ * container of items full width on a phone (`detectUnresponsiveGrids`). What a
+ * tree cannot show is what renders: a Stack that stays a row on a phone, a
+ * line of copy wider than the screen. `tools/scripts/record-ai-page-axe.mts`
+ * renders each golden page and each rendered eval answer at the switcher's
+ * five devices — through `devicePreviewWidth` and the canvas's own pinned
+ * theme, in a real browser — and records what it measured here, in the
+ * shapes below. Specs read the recording; nothing here renders.
+ */
+/** The devices the switcher previews, narrowest first, by their flag names. */
+export declare const AI_AUDIT_DEVICES: readonly ["XS", "SM", "MD", "LG", "XL"];
+export type AiAuditDevice = (typeof AI_AUDIT_DEVICES)[number];
+/** One axe-core violation, as a recording keeps it. */
+export interface AiAuditViolation {
+    id: string;
+    impact: string | null;
+    help: string;
+    /** How many elements break it. */
+    nodes: number;
+}
+/** A document rendered at one device's width. */
+export interface AiDeviceRender {
+    device: AiAuditDevice;
+    /** The viewport width the switcher previews the device at, in CSS pixels. */
+    width: number;
+    /**
+     * The deepest elements whose box runs past the viewport's edge, in document
+     * order; empty when the page is no wider than the screen.
+     */
+    overflow: string[];
+    /**
+     * axe-core's violations, every rule on. Recorded for the golden pages, whose
+     * sites author the colors their pages are measured against; an eval answer
+     * is recorded for its widths alone.
+     */
+    violations?: AiAuditViolation[];
+}
+/**
+ * A row a layout element draws: a Stack, Grid, Box, Section or Container of
+ * the palette (its schema's Layout category) laid out as a flex or grid box.
+ */
+export interface AiLayoutRow {
+    /** The element: the id the model wrote for it, or its section and position. */
+    node: string;
+    component: string;
+    /** Whether it is a Grid container, which rule 12 holds to one column on a phone. */
+    grid: boolean;
+    /**
+     * Its children that hold content. A child drawn by an Input or a Navigation
+     * element of the palette, or an icon, is a control: a row of buttons, links
+     * or an icon beside its label reads as one line on a phone.
+     */
+    content: number;
+    /** The children on its first line, per device. */
+    columns: Record<AiAuditDevice, number>;
+}
+/** What a recording holds for one document. */
+export interface AiDeviceAudit {
+    devices: AiDeviceRender[];
+    rows: AiLayoutRow[];
+}
+/**
+ * A band: a row of two or more columns of content at LG, which the palette's
+ * own Grid row stacks on a phone ("three columns that stack on mobile").
+ */
+export declare function aiLayoutRowIsBand(row: AiLayoutRow): boolean;
+/**
+ * What a recorded document gets wrong at the switcher's widths, as findings:
+ *
+ *  - `widths-missing:<device>`: a device the recording never rendered;
+ *  - `overflow:<device>:<element>`: an element wider than the device's screen,
+ *    which scrolls the page sideways;
+ *  - `band-not-broken-down:<element>`: a band with as many columns on a phone
+ *    (XS) as on a desktop (LG).
+ *
+ * Empty when the document works at every width.
+ */
+export declare function aiDeviceAuditFindings(audit: AiDeviceAudit): string[];
+/**
+ * The theme document a site inventory's theme summarizes: its light scheme's
+ * colors, from the flat `primary.main` paths the inventory lists them by, and
+ * its fonts. A golden site has no theme document of its own, so this is the
+ * theme its pages were built against and are rendered with; `null` renders
+ * the brand base alone, as a site with no theme does.
+ */
+export declare function aiInventoryHostTheme(theme: AiInventoryTheme | null): HostTheme | null;

package/src/lib/runtime/ai-device-audit.js

@@ -0,0 +1,97 @@
+/**
+ * @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 { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * THE DEVICE AUDIT (AGL-3020): what a generated document looks like at every
+ * width the besigner's device switcher previews, and the rule a recording of
+ * it is held to.
+ *
+ * Rule 12 is held on the tree: no fixed width, and a Grid of columns is a
+ * container of items full width on a phone (`detectUnresponsiveGrids`). What a
+ * tree cannot show is what renders: a Stack that stays a row on a phone, a
+ * line of copy wider than the screen. `tools/scripts/record-ai-page-axe.mts`
+ * renders each golden page and each rendered eval answer at the switcher's
+ * five devices — through `devicePreviewWidth` and the canvas's own pinned
+ * theme, in a real browser — and records what it measured here, in the
+ * shapes below. Specs read the recording; nothing here renders.
+ */ /** The devices the switcher previews, narrowest first, by their flag names. */ export const AI_AUDIT_DEVICES = [
+    'XS',
+    'SM',
+    'MD',
+    'LG',
+    'XL'
+];
+/**
+ * A band: a row of two or more columns of content at LG, which the palette's
+ * own Grid row stacks on a phone ("three columns that stack on mobile").
+ */ export function aiLayoutRowIsBand(row) {
+    return row.content >= 2 && row.columns.LG >= 2;
+}
+/**
+ * What a recorded document gets wrong at the switcher's widths, as findings:
+ *
+ *  - `widths-missing:<device>`: a device the recording never rendered;
+ *  - `overflow:<device>:<element>`: an element wider than the device's screen,
+ *    which scrolls the page sideways;
+ *  - `band-not-broken-down:<element>`: a band with as many columns on a phone
+ *    (XS) as on a desktop (LG).
+ *
+ * Empty when the document works at every width.
+ */ export function aiDeviceAuditFindings(audit) {
+    const findings = [];
+    for (const device of AI_AUDIT_DEVICES){
+        if (!audit.devices.some((render)=>render.device === device)) findings.push(`widths-missing:${device}`);
+    }
+    for (const render of audit.devices){
+        for (const element of render.overflow)findings.push(`overflow:${render.device}:${element}`);
+    }
+    for (const row of audit.rows){
+        if (aiLayoutRowIsBand(row) && row.columns.XS >= row.columns.LG) findings.push(`band-not-broken-down:${row.node}`);
+    }
+    return findings;
+}
+const isRecord = (value)=>typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * The theme document a site inventory's theme summarizes: its light scheme's
+ * colors, from the flat `primary.main` paths the inventory lists them by, and
+ * its fonts. A golden site has no theme document of its own, so this is the
+ * theme its pages were built against and are rendered with; `null` renders
+ * the brand base alone, as a site with no theme does.
+ */ export function aiInventoryHostTheme(theme) {
+    if (!theme) return null;
+    const light = {};
+    for (const [path, value] of Object.entries(theme.colors)){
+        const keys = path.split('.').filter(Boolean);
+        if (!keys.length) continue;
+        let cursor = light;
+        for (const key of keys.slice(0, -1)){
+            if (!isRecord(cursor[key])) cursor[key] = {};
+            cursor = cursor[key];
+        }
+        cursor[keys[keys.length - 1]] = value;
+    }
+    return _extends({
+        colorSchemes: {
+            light: light
+        }
+    }, theme.fonts.length ? {
+        fonts: theme.fonts.map((family)=>({
+                family
+            }))
+    } : {});
+}
+
+//# sourceMappingURL=ai-device-audit.js.map

package/src/lib/runtime/ai-device-audit.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/runtime/ai-device-audit.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { HostTheme, HostThemeSchemeColors } from '@aglyn/shared-data-types'\nimport type { AiInventoryTheme } from '../model/ai-site-inventory'\n\n/**\n * THE DEVICE AUDIT (AGL-3020): what a generated document looks like at every\n * width the besigner's device switcher previews, and the rule a recording of\n * it is held to.\n *\n * Rule 12 is held on the tree: no fixed width, and a Grid of columns is a\n * container of items full width on a phone (`detectUnresponsiveGrids`). What a\n * tree cannot show is what renders: a Stack that stays a row on a phone, a\n * line of copy wider than the screen. `tools/scripts/record-ai-page-axe.mts`\n * renders each golden page and each rendered eval answer at the switcher's\n * five devices — through `devicePreviewWidth` and the canvas's own pinned\n * theme, in a real browser — and records what it measured here, in the\n * shapes below. Specs read the recording; nothing here renders.\n */\n\n/** The devices the switcher previews, narrowest first, by their flag names. */\nexport const AI_AUDIT_DEVICES = ['XS', 'SM', 'MD', 'LG', 'XL'] as const\nexport type AiAuditDevice = (typeof AI_AUDIT_DEVICES)[number]\n\n/** One axe-core violation, as a recording keeps it. */\nexport interface AiAuditViolation {\n  id: string\n  impact: string | null\n  help: string\n  /** How many elements break it. */\n  nodes: number\n}\n\n/** A document rendered at one device's width. */\nexport interface AiDeviceRender {\n  device: AiAuditDevice\n  /** The viewport width the switcher previews the device at, in CSS pixels. */\n  width: number\n  /**\n   * The deepest elements whose box runs past the viewport's edge, in document\n   * order; empty when the page is no wider than the screen.\n   */\n  overflow: string[]\n  /**\n   * axe-core's violations, every rule on. Recorded for the golden pages, whose\n   * sites author the colors their pages are measured against; an eval answer\n   * is recorded for its widths alone.\n   */\n  violations?: AiAuditViolation[]\n}\n\n/**\n * A row a layout element draws: a Stack, Grid, Box, Section or Container of\n * the palette (its schema's Layout category) laid out as a flex or grid box.\n */\nexport interface AiLayoutRow {\n  /** The element: the id the model wrote for it, or its section and position. */\n  node: string\n  component: string\n  /** Whether it is a Grid container, which rule 12 holds to one column on a phone. */\n  grid: boolean\n  /**\n   * Its children that hold content. A child drawn by an Input or a Navigation\n   * element of the palette, or an icon, is a control: a row of buttons, links\n   * or an icon beside its label reads as one line on a phone.\n   */\n  content: number\n  /** The children on its first line, per device. */\n  columns: Record<AiAuditDevice, number>\n}\n\n/** What a recording holds for one document. */\nexport interface AiDeviceAudit {\n  devices: AiDeviceRender[]\n  rows: AiLayoutRow[]\n}\n\n/**\n * A band: a row of two or more columns of content at LG, which the palette's\n * own Grid row stacks on a phone (\"three columns that stack on mobile\").\n */\nexport function aiLayoutRowIsBand(row: AiLayoutRow): boolean {\n  return row.content >= 2 && row.columns.LG >= 2\n}\n\n/**\n * What a recorded document gets wrong at the switcher's widths, as findings:\n *\n *  - `widths-missing:<device>`: a device the recording never rendered;\n *  - `overflow:<device>:<element>`: an element wider than the device's screen,\n *    which scrolls the page sideways;\n *  - `band-not-broken-down:<element>`: a band with as many columns on a phone\n *    (XS) as on a desktop (LG).\n *\n * Empty when the document works at every width.\n */\nexport function aiDeviceAuditFindings(audit: AiDeviceAudit): string[] {\n  const findings: string[] = []\n  for (const device of AI_AUDIT_DEVICES) {\n    if (!audit.devices.some((render) => render.device === device)) findings.push(`widths-missing:${device}`)\n  }\n  for (const render of audit.devices) {\n    for (const element of render.overflow) findings.push(`overflow:${render.device}:${element}`)\n  }\n  for (const row of audit.rows) {\n    if (aiLayoutRowIsBand(row) && row.columns.XS >= row.columns.LG) findings.push(`band-not-broken-down:${row.node}`)\n  }\n  return findings\n}\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value)\n\n/**\n * The theme document a site inventory's theme summarizes: its light scheme's\n * colors, from the flat `primary.main` paths the inventory lists them by, and\n * its fonts. A golden site has no theme document of its own, so this is the\n * theme its pages were built against and are rendered with; `null` renders\n * the brand base alone, as a site with no theme does.\n */\nexport function aiInventoryHostTheme(theme: AiInventoryTheme | null): HostTheme | null {\n  if (!theme) return null\n  const light: Record<string, unknown> = {}\n  for (const [path, value] of Object.entries(theme.colors)) {\n    const keys = path.split('.').filter(Boolean)\n    if (!keys.length) continue\n    let cursor = light\n    for (const key of keys.slice(0, -1)) {\n      if (!isRecord(cursor[key])) cursor[key] = {}\n      cursor = cursor[key] as Record<string, unknown>\n    }\n    cursor[keys[keys.length - 1]] = value\n  }\n  return {\n    colorSchemes: { light: light as HostThemeSchemeColors },\n    ...(theme.fonts.length ? { fonts: theme.fonts.map((family) => ({ family })) } : {}),\n  }\n}\n"],"names":["AI_AUDIT_DEVICES","aiLayoutRowIsBand","row","content","columns","LG","aiDeviceAuditFindings","audit","findings","device","devices","some","render","push","element","overflow","rows","XS","node","isRecord","value","Array","isArray","aiInventoryHostTheme","theme","light","path","Object","entries","colors","keys","split","filter","Boolean","length","cursor","key","slice","colorSchemes","fonts","map","family"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC;AAKD;;;;;;;;;;;;;CAaC,GAED,6EAA6E,GAC7E,OAAO,MAAMA,mBAAmB;IAAC;IAAM;IAAM;IAAM;IAAM;CAAK,CAAS;AAwDvE;;;CAGC,GACD,OAAO,SAASC,kBAAkBC,GAAgB;IAChD,OAAOA,IAAIC,OAAO,IAAI,KAAKD,IAAIE,OAAO,CAACC,EAAE,IAAI;AAC/C;AAEA;;;;;;;;;;CAUC,GACD,OAAO,SAASC,sBAAsBC,KAAoB;IACxD,MAAMC,WAAqB,EAAE;IAC7B,KAAK,MAAMC,UAAUT,iBAAkB;QACrC,IAAI,CAACO,MAAMG,OAAO,CAACC,IAAI,CAAC,CAACC,SAAWA,OAAOH,MAAM,KAAKA,SAASD,SAASK,IAAI,CAAC,CAAC,eAAe,EAAEJ,QAAQ;IACzG;IACA,KAAK,MAAMG,UAAUL,MAAMG,OAAO,CAAE;QAClC,KAAK,MAAMI,WAAWF,OAAOG,QAAQ,CAAEP,SAASK,IAAI,CAAC,CAAC,SAAS,EAAED,OAAOH,MAAM,CAAC,CAAC,EAAEK,SAAS;IAC7F;IACA,KAAK,MAAMZ,OAAOK,MAAMS,IAAI,CAAE;QAC5B,IAAIf,kBAAkBC,QAAQA,IAAIE,OAAO,CAACa,EAAE,IAAIf,IAAIE,OAAO,CAACC,EAAE,EAAEG,SAASK,IAAI,CAAC,CAAC,qBAAqB,EAAEX,IAAIgB,IAAI,EAAE;IAClH;IACA,OAAOV;AACT;AAEA,MAAMW,WAAW,CAACC,QAChB,OAAOA,UAAU,YAAYA,UAAU,QAAQ,CAACC,MAAMC,OAAO,CAACF;AAEhE;;;;;;CAMC,GACD,OAAO,SAASG,qBAAqBC,KAA8B;IACjE,IAAI,CAACA,OAAO,OAAO;IACnB,MAAMC,QAAiC,CAAC;IACxC,KAAK,MAAM,CAACC,MAAMN,MAAM,IAAIO,OAAOC,OAAO,CAACJ,MAAMK,MAAM,EAAG;QACxD,MAAMC,OAAOJ,KAAKK,KAAK,CAAC,KAAKC,MAAM,CAACC;QACpC,IAAI,CAACH,KAAKI,MAAM,EAAE;QAClB,IAAIC,SAASV;QACb,KAAK,MAAMW,OAAON,KAAKO,KAAK,CAAC,GAAG,CAAC,GAAI;YACnC,IAAI,CAAClB,SAASgB,MAAM,CAACC,IAAI,GAAGD,MAAM,CAACC,IAAI,GAAG,CAAC;YAC3CD,SAASA,MAAM,CAACC,IAAI;QACtB;QACAD,MAAM,CAACL,IAAI,CAACA,KAAKI,MAAM,GAAG,EAAE,CAAC,GAAGd;IAClC;IACA,OAAO;QACLkB,cAAc;YAAEb,OAAOA;QAA+B;OAClDD,MAAMe,KAAK,CAACL,MAAM,GAAG;QAAEK,OAAOf,MAAMe,KAAK,CAACC,GAAG,CAAC,CAACC,SAAY,CAAA;gBAAEA;YAAO,CAAA;IAAI,IAAI,CAAC;AAErF"}