@aglyn/aglyn 1.0.0-beta.285 → 1.0.0-beta.288

package/src/lib/app-utils/site-starter-nodes.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @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 PortableDefinitionNodes } from './node-definition-sanitizer';
+/**
+ * What a site starter's pages and layout may hold (AGL-4049), and the one
+ * pass that makes them so.
+ *
+ * A starter is a whole site, so it has to carry what a real site is made of:
+ * the grids, cards, accordions and icons the default site is built from and
+ * the AI site build lays out, with their styles and their interactions. The
+ * portable rule every other artifact is published under keeps none of that —
+ * it is for a component dropped into someone else's page — so a starter gets
+ * its own allowlist here, a superset of the portable one, and keeps `sx` and
+ * `interactions` once they are checked. Nothing else is widened: the template,
+ * layout and component doors still publish under the portable rule.
+ *
+ * Kept safe the same way, plus two checks of its own:
+ *   - only the component ids below, nothing bound to the source site's data
+ *     (content collections, datasets) or to another plugin;
+ *   - the portable prop hardening (no `on*`, no `dangerouslySetInnerHTML`, an
+ *     `href`/`src` only to a safe address) and the size cap;
+ *   - a style may load an image only from where an image `src` may, and never
+ *     from a protocol-relative address;
+ *   - an interaction may only scroll, show, hide, open, close, toggle a class,
+ *     stick the navigation or play a video: no script, markup, redirect or
+ *     tracking rides a starter onto the sites created from it.
+ *
+ * The publish door runs every page and the layout through
+ * {@link sanitizeSiteStarterNodes}; the first-party seed holds its pages to the
+ * same pass, so a seeded and a published starter store one shape. Pure.
+ */
+/**
+ * The component ids a starter's pages may hold: the portable allowlist, what
+ * `default-site.ts` builds, and the presentational elements the AI site build
+ * lays out (its palette's page surface, less anything bound to a site's data).
+ */
+export declare const SITE_STARTER_COMPONENT_IDS: readonly string[];
+/** The node marking where a page's content grafts into its layout. */
+export declare const SITE_STARTER_LAYOUT_SLOT_ID = "layoutSlot";
+/** A starter's layout may hold the same, plus the slot its pages render in. */
+export declare const SITE_STARTER_LAYOUT_COMPONENT_IDS: readonly string[];
+/**
+ * The interaction steps a starter may carry: each acts on the page it is on
+ * and nothing else. Scripts, markup, redirects, attributes, alerts, popups and
+ * analytics are left out, as is every step a plugin declares.
+ */
+export declare const SITE_STARTER_INTERACTION_STEP_TYPES: ReadonlySet<string>;
+/** A starter's node as stored: a portable node, with its checked styles and interactions. */
+export type SiteStarterNodes = Record<string, PortableDefinitionNodes[string] & {
+    sx?: unknown;
+    interactions?: unknown[];
+}>;
+/**
+ * A starter page's or layout's nodes as a starter stores them, or why they
+ * cannot be: the portable pass under {@link SITE_STARTER_COMPONENT_IDS} (or
+ * the layout list), then each kept node's checked `sx` and `interactions`
+ * put back. Callers decode stored nodes first (`decodeStoredNodes`).
+ */
+export declare function sanitizeSiteStarterNodes(definition: {
+    rootId: string;
+    nodes: Record<string, any>;
+}, options?: {
+    /** A layout: the slot its pages render in is allowed too. */
+    layout?: boolean;
+    /** The properties a layout's tree binds to, as `sanitizePortableDefinition` takes them. */
+    declaredProps?: ReadonlyArray<{
+        name?: unknown;
+        type?: unknown;
+    }>;
+}): {
+    ok: true;
+    rootId: string;
+    nodes: SiteStarterNodes;
+} | {
+    ok: false;
+    error: string;
+};

package/src/lib/app-utils/site-starter-nodes.js

@@ -0,0 +1,210 @@
+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 { NODE_MAX_INTERACTIONS } from "./node-interactions.js";
+import { PORTABLE_COMPONENT_ID_ALLOWLIST, PORTABLE_DEFINITION_MAX_BYTES, sanitizePortableDefinition } from "./node-definition-sanitizer.js";
+import { isSafeNodeUrl } from "./node-url-policy.js";
+import { CLIENT_INTERACTION_STEP_LABELS } from "./site-interactions.js";
+/**
+ * What a site starter's pages and layout may hold (AGL-4049), and the one
+ * pass that makes them so.
+ *
+ * A starter is a whole site, so it has to carry what a real site is made of:
+ * the grids, cards, accordions and icons the default site is built from and
+ * the AI site build lays out, with their styles and their interactions. The
+ * portable rule every other artifact is published under keeps none of that —
+ * it is for a component dropped into someone else's page — so a starter gets
+ * its own allowlist here, a superset of the portable one, and keeps `sx` and
+ * `interactions` once they are checked. Nothing else is widened: the template,
+ * layout and component doors still publish under the portable rule.
+ *
+ * Kept safe the same way, plus two checks of its own:
+ *   - only the component ids below, nothing bound to the source site's data
+ *     (content collections, datasets) or to another plugin;
+ *   - the portable prop hardening (no `on*`, no `dangerouslySetInnerHTML`, an
+ *     `href`/`src` only to a safe address) and the size cap;
+ *   - a style may load an image only from where an image `src` may, and never
+ *     from a protocol-relative address;
+ *   - an interaction may only scroll, show, hide, open, close, toggle a class,
+ *     stick the navigation or play a video: no script, markup, redirect or
+ *     tracking rides a starter onto the sites created from it.
+ *
+ * The publish door runs every page and the layout through
+ * {@link sanitizeSiteStarterNodes}; the first-party seed holds its pages to the
+ * same pass, so a seeded and a published starter store one shape. Pure.
+ */ /**
+ * The component ids a starter's pages may hold: the portable allowlist, what
+ * `default-site.ts` builds, and the presentational elements the AI site build
+ * lays out (its palette's page surface, less anything bound to a site's data).
+ */ export const SITE_STARTER_COMPONENT_IDS = [
+    ...new Set([
+        ...PORTABLE_COMPONENT_ID_ALLOWLIST,
+        // The default site (`default-site.ts`).
+        'icon',
+        'muiAccordion',
+        'muiAccordionDetails',
+        'muiAccordionSummary',
+        'muiCard',
+        'muiCardContent',
+        'muiGrid',
+        'themeModeSwitcher',
+        // The AI site build's presentational elements.
+        'dataTable',
+        'muiBox',
+        'muiBreadcrumbs',
+        'muiCardActions',
+        'muiCardHeader',
+        'muiImageList',
+        'muiImageListItem',
+        'video'
+    ])
+].sort();
+/** The node marking where a page's content grafts into its layout. */ export const SITE_STARTER_LAYOUT_SLOT_ID = 'layoutSlot';
+/** A starter's layout may hold the same, plus the slot its pages render in. */ export const SITE_STARTER_LAYOUT_COMPONENT_IDS = [
+    ...SITE_STARTER_COMPONENT_IDS,
+    SITE_STARTER_LAYOUT_SLOT_ID
+].sort();
+/**
+ * The interaction steps a starter may carry: each acts on the page it is on
+ * and nothing else. Scripts, markup, redirects, attributes, alerts, popups and
+ * analytics are left out, as is every step a plugin declares.
+ */ export const SITE_STARTER_INTERACTION_STEP_TYPES = new Set([
+    'addClass',
+    'closeDrawer',
+    'closeMenu',
+    'hideElement',
+    'openDrawer',
+    'openMenu',
+    'playVideo',
+    'removeClass',
+    'scrollTo',
+    'showElement',
+    'stickyNav',
+    'toggleClass',
+    'toggleDrawer',
+    'toggleElement',
+    'toggleMenu'
+]);
+const isRecord = (value)=>!!value && typeof value === 'object' && !Array.isArray(value);
+/** How a refusal names a node: its component, then its id. */ const nodeName = (id, node)=>{
+    var _ref;
+    return `the ${String((_ref = node == null ? void 0 : node.componentId) != null ? _ref : 'element')} "${id}"`;
+};
+const stepLabel = (type)=>{
+    var _CLIENT_INTERACTION_STEP_LABELS_type;
+    return (_CLIENT_INTERACTION_STEP_LABELS_type = CLIENT_INTERACTION_STEP_LABELS[type]) != null ? _CLIENT_INTERACTION_STEP_LABELS_type : type;
+};
+/** Every `url(…)` address in a style value. */ const styleUrls = (value)=>[
+        ...value.matchAll(/url\(\s*(['"]?)(.*?)\1\s*\)/gi)
+    ].map((match)=>match[2].trim());
+/** Why a node's styles cannot ride a starter, or null when they can. */ function styleRefusal(id, node, sx, depth = 0) {
+    if (depth > 12) return `The styles on ${nodeName(id, node)} are nested too deeply`;
+    if (typeof sx === 'string') {
+        if (/url\(/i.test(sx) && !styleUrls(sx).length) {
+            return `A style on ${nodeName(id, node)} loads an address a starter cannot read`;
+        }
+        for (const address of styleUrls(sx)){
+            if (address.startsWith('//') || !isSafeNodeUrl('src', address)) {
+                return `A style on ${nodeName(id, node)} loads "${address.slice(0, 120)}", which a starter cannot carry`;
+            }
+        }
+        return null;
+    }
+    if (sx === null || typeof sx === 'number' || typeof sx === 'boolean') return null;
+    if (Array.isArray(sx)) {
+        for (const entry of sx){
+            const refusal = styleRefusal(id, node, entry, depth + 1);
+            if (refusal) return refusal;
+        }
+        return null;
+    }
+    if (isRecord(sx)) {
+        for (const entry of Object.values(sx)){
+            const refusal = styleRefusal(id, node, entry, depth + 1);
+            if (refusal) return refusal;
+        }
+        return null;
+    }
+    return `The styles on ${nodeName(id, node)} hold something that is not a style`;
+}
+/** Why a node's interactions cannot ride a starter, or null when they can. */ function interactionsRefusal(id, node, interactions) {
+    if (!Array.isArray(interactions)) return `The interactions on ${nodeName(id, node)} are not a list`;
+    if (interactions.length > NODE_MAX_INTERACTIONS) {
+        return `${nodeName(id, node)} has more than ${NODE_MAX_INTERACTIONS} interactions`;
+    }
+    for (const interaction of interactions){
+        if (!isRecord(interaction) || !Array.isArray(interaction['steps'])) {
+            return `An interaction on ${nodeName(id, node)} is not one`;
+        }
+        for (const step of interaction['steps']){
+            const type = isRecord(step) && typeof step['type'] === 'string' ? step['type'] : '';
+            if (!SITE_STARTER_INTERACTION_STEP_TYPES.has(type)) {
+                return `An interaction on ${nodeName(id, node)} runs "${stepLabel(type || 'an unknown step')}", ` + 'which a starter cannot carry: a starter brings no scripts, markup, redirects or ' + 'tracking to the sites created from it';
+            }
+        }
+    }
+    return null;
+}
+/** A JSON copy, so a stored starter never shares an object with its source. */ const copied = (value)=>JSON.parse(JSON.stringify(value));
+/**
+ * A starter page's or layout's nodes as a starter stores them, or why they
+ * cannot be: the portable pass under {@link SITE_STARTER_COMPONENT_IDS} (or
+ * the layout list), then each kept node's checked `sx` and `interactions`
+ * put back. Callers decode stored nodes first (`decodeStoredNodes`).
+ */ export function sanitizeSiteStarterNodes(definition, options = {}) {
+    const portable = sanitizePortableDefinition(definition, _extends({
+        componentIds: options.layout ? SITE_STARTER_LAYOUT_COMPONENT_IDS : SITE_STARTER_COMPONENT_IDS
+    }, options.declaredProps && {
+        declaredProps: options.declaredProps
+    }));
+    if (portable.ok === false) return portable;
+    const nodes = {};
+    for (const [id, kept] of Object.entries(portable.nodes)){
+        var _definition_nodes_id;
+        const source = (_definition_nodes_id = definition.nodes[id]) != null ? _definition_nodes_id : {};
+        const node = _extends({}, kept);
+        if (source.sx !== undefined && source.sx !== null) {
+            const refusal = styleRefusal(id, source, source.sx);
+            if (refusal) return {
+                ok: false,
+                error: refusal
+            };
+            node['sx'] = copied(source.sx);
+        }
+        if (source.interactions !== undefined && source.interactions !== null) {
+            const refusal = interactionsRefusal(id, source, source.interactions);
+            if (refusal) return {
+                ok: false,
+                error: refusal
+            };
+            if (source.interactions.length) node['interactions'] = copied(source.interactions);
+        }
+        nodes[id] = node;
+    }
+    if (JSON.stringify(nodes).length > PORTABLE_DEFINITION_MAX_BYTES) {
+        return {
+            ok: false,
+            error: 'Definition is too large to publish'
+        };
+    }
+    return {
+        ok: true,
+        rootId: portable.rootId,
+        nodes
+    };
+}
+
+//# sourceMappingURL=site-starter-nodes.js.map

package/src/lib/app-utils/site-starter-nodes.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/site-starter-nodes.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 { NODE_MAX_INTERACTIONS } from './node-interactions'\nimport {\n  PORTABLE_COMPONENT_ID_ALLOWLIST,\n  PORTABLE_DEFINITION_MAX_BYTES,\n  sanitizePortableDefinition,\n  type PortableDefinitionNodes,\n} from './node-definition-sanitizer'\nimport { isSafeNodeUrl } from './node-url-policy'\nimport { CLIENT_INTERACTION_STEP_LABELS } from './site-interactions'\n\n/**\n * What a site starter's pages and layout may hold (AGL-4049), and the one\n * pass that makes them so.\n *\n * A starter is a whole site, so it has to carry what a real site is made of:\n * the grids, cards, accordions and icons the default site is built from and\n * the AI site build lays out, with their styles and their interactions. The\n * portable rule every other artifact is published under keeps none of that —\n * it is for a component dropped into someone else's page — so a starter gets\n * its own allowlist here, a superset of the portable one, and keeps `sx` and\n * `interactions` once they are checked. Nothing else is widened: the template,\n * layout and component doors still publish under the portable rule.\n *\n * Kept safe the same way, plus two checks of its own:\n *   - only the component ids below, nothing bound to the source site's data\n *     (content collections, datasets) or to another plugin;\n *   - the portable prop hardening (no `on*`, no `dangerouslySetInnerHTML`, an\n *     `href`/`src` only to a safe address) and the size cap;\n *   - a style may load an image only from where an image `src` may, and never\n *     from a protocol-relative address;\n *   - an interaction may only scroll, show, hide, open, close, toggle a class,\n *     stick the navigation or play a video: no script, markup, redirect or\n *     tracking rides a starter onto the sites created from it.\n *\n * The publish door runs every page and the layout through\n * {@link sanitizeSiteStarterNodes}; the first-party seed holds its pages to the\n * same pass, so a seeded and a published starter store one shape. Pure.\n */\n\n/**\n * The component ids a starter's pages may hold: the portable allowlist, what\n * `default-site.ts` builds, and the presentational elements the AI site build\n * lays out (its palette's page surface, less anything bound to a site's data).\n */\nexport const SITE_STARTER_COMPONENT_IDS: readonly string[] = [\n  ...new Set([\n    ...PORTABLE_COMPONENT_ID_ALLOWLIST,\n    // The default site (`default-site.ts`).\n    'icon',\n    'muiAccordion',\n    'muiAccordionDetails',\n    'muiAccordionSummary',\n    'muiCard',\n    'muiCardContent',\n    'muiGrid',\n    'themeModeSwitcher',\n    // The AI site build's presentational elements.\n    'dataTable',\n    'muiBox',\n    'muiBreadcrumbs',\n    'muiCardActions',\n    'muiCardHeader',\n    'muiImageList',\n    'muiImageListItem',\n    'video',\n  ]),\n].sort()\n\n/** The node marking where a page's content grafts into its layout. */\nexport const SITE_STARTER_LAYOUT_SLOT_ID = 'layoutSlot'\n\n/** A starter's layout may hold the same, plus the slot its pages render in. */\nexport const SITE_STARTER_LAYOUT_COMPONENT_IDS: readonly string[] = [\n  ...SITE_STARTER_COMPONENT_IDS,\n  SITE_STARTER_LAYOUT_SLOT_ID,\n].sort()\n\n/**\n * The interaction steps a starter may carry: each acts on the page it is on\n * and nothing else. Scripts, markup, redirects, attributes, alerts, popups and\n * analytics are left out, as is every step a plugin declares.\n */\nexport const SITE_STARTER_INTERACTION_STEP_TYPES: ReadonlySet<string> = new Set([\n  'addClass',\n  'closeDrawer',\n  'closeMenu',\n  'hideElement',\n  'openDrawer',\n  'openMenu',\n  'playVideo',\n  'removeClass',\n  'scrollTo',\n  'showElement',\n  'stickyNav',\n  'toggleClass',\n  'toggleDrawer',\n  'toggleElement',\n  'toggleMenu',\n])\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  !!value && typeof value === 'object' && !Array.isArray(value)\n\n/** How a refusal names a node: its component, then its id. */\nconst nodeName = (id: string, node: Record<string, any>) =>\n  `the ${String(node?.componentId ?? 'element')} \"${id}\"`\n\nconst stepLabel = (type: string): string =>\n  (CLIENT_INTERACTION_STEP_LABELS as Readonly<Record<string, string>>)[type] ?? type\n\n/** Every `url(…)` address in a style value. */\nconst styleUrls = (value: string): string[] =>\n  [...value.matchAll(/url\\(\\s*(['\"]?)(.*?)\\1\\s*\\)/gi)].map((match) => match[2].trim())\n\n/** Why a node's styles cannot ride a starter, or null when they can. */\nfunction styleRefusal(id: string, node: Record<string, any>, sx: unknown, depth = 0): string | null {\n  if (depth > 12) return `The styles on ${nodeName(id, node)} are nested too deeply`\n  if (typeof sx === 'string') {\n    if (/url\\(/i.test(sx) && !styleUrls(sx).length) {\n      return `A style on ${nodeName(id, node)} loads an address a starter cannot read`\n    }\n    for (const address of styleUrls(sx)) {\n      if (address.startsWith('//') || !isSafeNodeUrl('src', address)) {\n        return `A style on ${nodeName(id, node)} loads \"${address.slice(0, 120)}\", which a starter cannot carry`\n      }\n    }\n    return null\n  }\n  if (sx === null || typeof sx === 'number' || typeof sx === 'boolean') return null\n  if (Array.isArray(sx)) {\n    for (const entry of sx) {\n      const refusal = styleRefusal(id, node, entry, depth + 1)\n      if (refusal) return refusal\n    }\n    return null\n  }\n  if (isRecord(sx)) {\n    for (const entry of Object.values(sx)) {\n      const refusal = styleRefusal(id, node, entry, depth + 1)\n      if (refusal) return refusal\n    }\n    return null\n  }\n  return `The styles on ${nodeName(id, node)} hold something that is not a style`\n}\n\n/** Why a node's interactions cannot ride a starter, or null when they can. */\nfunction interactionsRefusal(id: string, node: Record<string, any>, interactions: unknown): string | null {\n  if (!Array.isArray(interactions)) return `The interactions on ${nodeName(id, node)} are not a list`\n  if (interactions.length > NODE_MAX_INTERACTIONS) {\n    return `${nodeName(id, node)} has more than ${NODE_MAX_INTERACTIONS} interactions`\n  }\n  for (const interaction of interactions) {\n    if (!isRecord(interaction) || !Array.isArray(interaction['steps'])) {\n      return `An interaction on ${nodeName(id, node)} is not one`\n    }\n    for (const step of interaction['steps'] as unknown[]) {\n      const type = isRecord(step) && typeof step['type'] === 'string' ? step['type'] : ''\n      if (!SITE_STARTER_INTERACTION_STEP_TYPES.has(type)) {\n        return (\n          `An interaction on ${nodeName(id, node)} runs \"${stepLabel(type || 'an unknown step')}\", ` +\n          'which a starter cannot carry: a starter brings no scripts, markup, redirects or ' +\n          'tracking to the sites created from it'\n        )\n      }\n    }\n  }\n  return null\n}\n\n/** A starter's node as stored: a portable node, with its checked styles and interactions. */\nexport type SiteStarterNodes = Record<\n  string,\n  PortableDefinitionNodes[string] & { sx?: unknown; interactions?: unknown[] }\n>\n\n/** A JSON copy, so a stored starter never shares an object with its source. */\nconst copied = <T>(value: T): T => JSON.parse(JSON.stringify(value)) as T\n\n/**\n * A starter page's or layout's nodes as a starter stores them, or why they\n * cannot be: the portable pass under {@link SITE_STARTER_COMPONENT_IDS} (or\n * the layout list), then each kept node's checked `sx` and `interactions`\n * put back. Callers decode stored nodes first (`decodeStoredNodes`).\n */\nexport function sanitizeSiteStarterNodes(\n  definition: { rootId: string; nodes: Record<string, any> },\n  options: {\n    /** A layout: the slot its pages render in is allowed too. */\n    layout?: boolean\n    /** The properties a layout's tree binds to, as `sanitizePortableDefinition` takes them. */\n    declaredProps?: ReadonlyArray<{ name?: unknown; type?: unknown }>\n  } = {},\n): { ok: true; rootId: string; nodes: SiteStarterNodes } | { ok: false; error: string } {\n  const portable = sanitizePortableDefinition(definition, {\n    componentIds: options.layout ? SITE_STARTER_LAYOUT_COMPONENT_IDS : SITE_STARTER_COMPONENT_IDS,\n    ...(options.declaredProps && { declaredProps: options.declaredProps }),\n  })\n  if (portable.ok === false) return portable\n  const nodes: SiteStarterNodes = {}\n  for (const [id, kept] of Object.entries(portable.nodes)) {\n    const source = definition.nodes[id] ?? {}\n    const node: SiteStarterNodes[string] = { ...kept }\n    if (source.sx !== undefined && source.sx !== null) {\n      const refusal = styleRefusal(id, source, source.sx)\n      if (refusal) return { ok: false, error: refusal }\n      node['sx'] = copied(source.sx)\n    }\n    if (source.interactions !== undefined && source.interactions !== null) {\n      const refusal = interactionsRefusal(id, source, source.interactions)\n      if (refusal) return { ok: false, error: refusal }\n      if ((source.interactions as unknown[]).length) node['interactions'] = copied(source.interactions)\n    }\n    nodes[id] = node\n  }\n  if (JSON.stringify(nodes).length > PORTABLE_DEFINITION_MAX_BYTES) {\n    return { ok: false, error: 'Definition is too large to publish' }\n  }\n  return { ok: true, rootId: portable.rootId, nodes }\n}\n"],"names":["NODE_MAX_INTERACTIONS","PORTABLE_COMPONENT_ID_ALLOWLIST","PORTABLE_DEFINITION_MAX_BYTES","sanitizePortableDefinition","isSafeNodeUrl","CLIENT_INTERACTION_STEP_LABELS","SITE_STARTER_COMPONENT_IDS","Set","sort","SITE_STARTER_LAYOUT_SLOT_ID","SITE_STARTER_LAYOUT_COMPONENT_IDS","SITE_STARTER_INTERACTION_STEP_TYPES","isRecord","value","Array","isArray","nodeName","id","node","String","componentId","stepLabel","type","styleUrls","matchAll","map","match","trim","styleRefusal","sx","depth","test","length","address","startsWith","slice","entry","refusal","Object","values","interactionsRefusal","interactions","interaction","step","has","copied","JSON","parse","stringify","sanitizeSiteStarterNodes","definition","options","portable","componentIds","layout","declaredProps","ok","nodes","kept","entries","source","undefined","error","rootId"],"mappings":"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"}

package/src/lib/app-utils/site-starter-theme.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @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 { ConsoleThemePreset } from '../plugin-manager/feature-plugins';
+import type { SiteStarterTheme } from './site-starter';
+import { type ThemeLibraryEntryWrite } from './theme-library';
+/**
+ * A site starter's theme on the site it creates (AGL-4049).
+ *
+ * A starter names its look one of two ways (`SiteStarterTheme`): a built-in
+ * theme with its brand colors and font pairing over it, or a full theme of
+ * its author's own. Either way the new site's theme is stored the way a
+ * person's own pick is: the built-in picked through the theme library with
+ * the starter's colors and fonts as the override over it, or the full theme
+ * installed into the library as a marketplace theme is. So the Theme page
+ * names the base a site came from, and every edit there starts from it.
+ *
+ * Planned against an EMPTY host, because the site does not exist yet: the
+ * create writes these fields in the same `set` that makes the host, and the
+ * library entries beside it, in one transaction.
+ *
+ * Pure: no I/O. The caller passes the built-in themes it has registered.
+ */
+/**
+ * The palette keys a built-in starter's brand sets: its three brand colors.
+ * The status colors (error, warning, info, success) stay the base theme's,
+ * since they mean the same thing on every site, and surfaces and text are the
+ * base's design.
+ */
+export declare const SITE_STARTER_BRAND_KEYS: readonly ["primary", "secondary", "tertiary"];
+/** The built-in theme a starter's `base` names, as the themes plugin registers it. */
+export declare const siteStarterPresetId: (base: string) => string;
+type BuiltinStarterTheme = Extract<SiteStarterTheme, {
+    kind: 'builtin';
+}>;
+/**
+ * A built-in base with the starter's brand colors and font pairing over it,
+ * modeled on the AI start's look (`aiSiteTheme`) but driven by the starter's
+ * `brand` and `fonts` rather than a style. Everything the base sets beyond
+ * those stays the base's: its status colors, surfaces, shapes and component
+ * styles. A brand with no `dark` map colors both schemes with `light`; a
+ * `fonts` of `null`, or a pairing id the platform does not have, keeps the
+ * base's own fonts.
+ */
+export declare function siteStarterTheme(theme: BuiltinStarterTheme, base: HostTheme): HostTheme;
+/** What a new site's host document and theme library start with. */
+export interface SiteStarterThemePlan {
+    /** Host fields, written in the `set` that creates the host. */
+    host: Record<string, unknown>;
+    /** Library entries to create under `hosts/{id}/themes`. */
+    entries: ThemeLibraryEntryWrite[];
+}
+/**
+ * The host fields and library entries a new site is born with for a
+ * starter's theme, planned against an empty host through the same planner
+ * the theme library runs (`planThemeLibraryAction`):
+ *
+ * - a full theme is installed, as the marketplace installs a theme, its
+ *   entry named after the starter and its provenance the starter's listing;
+ * - a built-in theme is picked as a preset, with the brand and fonts as the
+ *   override over it;
+ * - the `starter` base, or a base this deployment has no built-in for, is
+ *   the theme every new site is born with (`DEFAULT_SITE_THEME`), with the
+ *   brand and fonts as the override over it, and no library entry.
+ */
+export declare function planSiteStarterTheme(input: {
+    theme: SiteStarterTheme;
+    presets: readonly ConsoleThemePreset[];
+    listing: {
+        listingId: string;
+        version: string | number;
+        displayName: string;
+    };
+    newId: () => string;
+}): SiteStarterThemePlan;
+export {};

package/src/lib/app-utils/site-starter-theme.js

@@ -0,0 +1,241 @@
+/**
+ * @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";
+import { writeThemeFonts } from "@aglyn/shared-util-tools/theme-fonts";
+import { diffOverride, overrideWriteValue } from "./artifact-overrides.js";
+import { DEFAULT_SITE_THEME } from "./default-site.js";
+import { siteFontPairing } from "./site-font-pairings.js";
+import { themeArtifactContent } from "./site-theme.js";
+import { planThemeLibraryAction, THEME_FIELD_DELETE } from "./theme-library.js";
+/**
+ * A site starter's theme on the site it creates (AGL-4049).
+ *
+ * A starter names its look one of two ways (`SiteStarterTheme`): a built-in
+ * theme with its brand colors and font pairing over it, or a full theme of
+ * its author's own. Either way the new site's theme is stored the way a
+ * person's own pick is: the built-in picked through the theme library with
+ * the starter's colors and fonts as the override over it, or the full theme
+ * installed into the library as a marketplace theme is. So the Theme page
+ * names the base a site came from, and every edit there starts from it.
+ *
+ * Planned against an EMPTY host, because the site does not exist yet: the
+ * create writes these fields in the same `set` that makes the host, and the
+ * library entries beside it, in one transaction.
+ *
+ * Pure: no I/O. The caller passes the built-in themes it has registered.
+ */ /**
+ * The palette keys a built-in starter's brand sets: its three brand colors.
+ * The status colors (error, warning, info, success) stay the base theme's,
+ * since they mean the same thing on every site, and surfaces and text are the
+ * base's design.
+ */ export const SITE_STARTER_BRAND_KEYS = [
+    'primary',
+    'secondary',
+    'tertiary'
+];
+/** The built-in theme a starter's `base` names, as the themes plugin registers it. */ export const siteStarterPresetId = (base)=>`theme-presets.${base}`;
+const isRecord = (value)=>!!value && typeof value === 'object' && !Array.isArray(value);
+/**
+ * One scheme's colors with the brand over them, each brand color written the
+ * way the theme editor writes a palette color (`writeThemeColor`): a record of
+ * `main` alone, so MUI derives its light, dark and contrast text from it, and
+ * the base's tint for that color dropped, since it was a wash of the old one.
+ */ function brandScheme(colors, brand) {
+    let next = colors;
+    for (const key of SITE_STARTER_BRAND_KEYS){
+        const hex = brand == null ? void 0 : brand[key];
+        if (typeof hex !== 'string' || !hex.trim()) continue;
+        next = _extends({}, next, {
+            [key]: {
+                main: hex.trim()
+            }
+        });
+        const tint = next.tint;
+        if (tint && key in tint) {
+            const rest = _extends({}, tint);
+            delete rest[key];
+            if (Object.keys(rest).length) next.tint = rest;
+            else delete next.tint;
+        }
+    }
+    return next;
+}
+/**
+ * A built-in base with the starter's brand colors and font pairing over it,
+ * modeled on the AI start's look (`aiSiteTheme`) but driven by the starter's
+ * `brand` and `fonts` rather than a style. Everything the base sets beyond
+ * those stays the base's: its status colors, surfaces, shapes and component
+ * styles. A brand with no `dark` map colors both schemes with `light`; a
+ * `fonts` of `null`, or a pairing id the platform does not have, keeps the
+ * base's own fonts.
+ */ export function siteStarterTheme(theme, base) {
+    var _next_fonts;
+    const brand = isRecord(theme == null ? void 0 : theme.brand) ? theme.brand : {
+        light: {}
+    };
+    const light = isRecord(brand.light) ? brand.light : {};
+    const dark = isRecord(brand.dark) ? brand.dark : light;
+    const brandFor = {
+        light,
+        dark
+    };
+    const colorSchemes = _extends({}, base.colorSchemes);
+    for (const scheme of [
+        'light',
+        'dark'
+    ]){
+        var _base_colorSchemes;
+        const colors = brandScheme((_base_colorSchemes = base.colorSchemes) == null ? void 0 : _base_colorSchemes[scheme], brandFor[scheme]);
+        if (colors) colorSchemes[scheme] = colors;
+    }
+    let next = _extends({}, base);
+    if (Object.keys(colorSchemes).length) next.colorSchemes = colorSchemes;
+    const pairing = siteFontPairing(theme == null ? void 0 : theme.fonts);
+    if (!pairing) return next;
+    // The same write the AI site look makes for a pairing: the body family,
+    // and the heading family where it differs.
+    const sameFamily = pairing.heading.family === pairing.body.family;
+    next = writeThemeFonts(next, {
+        body: {
+            family: pairing.body.family,
+            category: pairing.body.category,
+            weights: [
+                ...pairing.body.weights
+            ],
+            source: 'google'
+        },
+        heading: sameFamily ? null : {
+            family: pairing.heading.family,
+            category: pairing.heading.category,
+            weights: [
+                ...new Set([
+                    pairing.heading.weight,
+                    pairing.heading.sub
+                ])
+            ].sort((a, b)=>a - b),
+            source: 'google'
+        }
+    });
+    // A pairing whose heading is the body family loads the heading weights too.
+    if (sameFamily && ((_next_fonts = next.fonts) == null ? void 0 : _next_fonts[0])) {
+        var _next_fonts__weights;
+        next.fonts = [
+            _extends({}, next.fonts[0], {
+                weights: [
+                    ...new Set([
+                        ...(_next_fonts__weights = next.fonts[0].weights) != null ? _next_fonts__weights : [],
+                        pairing.heading.weight,
+                        pairing.heading.sub
+                    ])
+                ].sort((a, b)=>a - b)
+            }),
+            ...next.fonts.slice(1)
+        ];
+    }
+    return next;
+}
+/**
+ * A plan's host fields as a new document takes them: a field the plan
+ * deletes is simply not written, since an empty host has nothing to delete,
+ * and an empty override is no field at all.
+ */ function creatable(fields) {
+    return Object.fromEntries(Object.entries(fields).filter(([, value])=>value !== THEME_FIELD_DELETE && value !== null));
+}
+/** The override a built-in starter stores over `base`, or `null` when it changes nothing. */ function starterOverride(theme, base) {
+    return overrideWriteValue(diffOverride(base, siteStarterTheme(theme, base)), null);
+}
+/**
+ * The host fields and library entries a new site is born with for a
+ * starter's theme, planned against an empty host through the same planner
+ * the theme library runs (`planThemeLibraryAction`):
+ *
+ * - a full theme is installed, as the marketplace installs a theme, its
+ *   entry named after the starter and its provenance the starter's listing;
+ * - a built-in theme is picked as a preset, with the brand and fonts as the
+ *   override over it;
+ * - the `starter` base, or a base this deployment has no built-in for, is
+ *   the theme every new site is born with (`DEFAULT_SITE_THEME`), with the
+ *   brand and fonts as the override over it, and no library entry.
+ */ export function planSiteStarterTheme(input) {
+    var _presets_find;
+    // `source`, not `listing`: this is the starter's id/version/name, not the
+    // listing document the listing write-deny guard partitions (AGL-1361).
+    const { theme, presets, listing: source, newId } = input;
+    const plan = (action)=>{
+        const planned = planThemeLibraryAction({
+            host: {},
+            entries: {},
+            newId,
+            action
+        });
+        return planned.ok === false ? null : planned;
+    };
+    if ((theme == null ? void 0 : theme.kind) === 'full' && isRecord(theme.theme)) {
+        const planned = plan({
+            action: 'install',
+            listingId: source.listingId,
+            name: `${source.displayName} theme`,
+            theme: themeArtifactContent(theme.theme),
+            installedFrom: {
+                listingId: source.listingId,
+                version: source.version,
+                artifactType: 'siteStarter'
+            }
+        });
+        if (planned) return {
+            host: creatable(planned.host),
+            entries: planned.entries
+        };
+    }
+    const builtin = (theme == null ? void 0 : theme.kind) === 'builtin' ? theme : {
+        kind: 'builtin',
+        base: 'starter',
+        brand: {
+            light: {}
+        },
+        fonts: null
+    };
+    const preset = builtin.base === 'starter' ? null : (_presets_find = presets.find((entry)=>(entry == null ? void 0 : entry.id) === siteStarterPresetId(builtin.base))) != null ? _presets_find : null;
+    if (preset) {
+        const base = themeArtifactContent(preset.theme);
+        const planned = plan({
+            action: 'select',
+            target: {
+                kind: 'preset',
+                id: preset.id,
+                name: preset.name,
+                theme: base
+            }
+        });
+        if (planned) {
+            return {
+                host: creatable(_extends({}, planned.host, {
+                    themeOverride: starterOverride(builtin, base)
+                })),
+                entries: planned.entries
+            };
+        }
+    }
+    return {
+        host: creatable({
+            theme: DEFAULT_SITE_THEME,
+            themeOverride: starterOverride(builtin, DEFAULT_SITE_THEME)
+        }),
+        entries: []
+    };
+}
+
+//# sourceMappingURL=site-starter-theme.js.map