@aglyn/aglyn 1.0.0-beta.218 → 1.0.0-beta.220

package/src/lib/app-utils/stale-build-error.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/stale-build-error.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\n/**\n * THE TAB THAT WAS OPEN ACROSS A DEPLOY (AGL-3279).\n *\n * Every build names its chunks by content hash and the previous build's are\n * not kept, so a tab loaded before a release asks for a file the origin no\n * longer serves the moment it navigates or opens a lazy route. The browser\n * rejects the import, the boundary above catches it, and the visitor is\n * shown a crash page with a **Try again** button that cannot possibly work:\n * `reset()` re-renders the same tree, which requests the same missing chunk.\n * It reported once in the 48h to 2026-09-23, on `aglyn.com`.\n *\n * A reload fixes it completely, because the fresh document names the chunks\n * the deploy actually shipped. What matters is that it may never LOOP: a\n * genuinely broken deploy would otherwise reload every visitor forever, and\n * an error reporter's first rule — never become the outage — applies twice\n * over to something that reloads pages.\n *\n * So the recovery is RATE-BOUND, held in session storage: at most one\n * reload per tab per {@link RECOVERY_INTERVAL_MS}, and a browser that\n * refuses storage gets none at all rather than an unbounded one. A second\n * failure inside that window renders the crash page and stays there, which\n * is the honest outcome — at that point the build really is broken and\n * reloading is not the answer.\n *\n * An interval rather than a once-ever mark, because a console tab lives for\n * days and this repo ships several times a day: a once-ever mark would\n * spend the tab's only recovery on the first deploy it survived and leave\n * it stranded on the third. Long enough that no plausible loop is\n * comfortable; short enough that the next release is covered.\n *\n * A module of its own, not a function in `error-beacon.ts`, for the reason\n * `redispatch-caught-error.ts` gives: an error boundary's chunk is\n * downloaded by every visitor, and importing one name off the beacon would\n * drag its whole installer in with it.\n */\n\nconst RELOADED_KEY = 'aglyn.staleBuildReloaded'\n\n/** How long one recovery suppresses the next, in this tab. */\nexport const RECOVERY_INTERVAL_MS = 30 * 60 * 1_000\n\n/**\n * Messages the browsers spell differently for one event — the module the\n * document names is not there.\n *\n * Matched on the MESSAGE as well as the name because only webpack's own\n * failure carries `name === 'ChunkLoadError'`; a native dynamic import that\n * 404s rejects with a plain `TypeError` whose wording is the browser's.\n */\nconst STALE_BUILD_MESSAGE =\n  /Loading chunk .* failed|Failed to load chunk|Loading CSS chunk .* failed|error loading dynamically imported module|Importing a module script failed|Failed to fetch dynamically imported module/i\n\n/** Was this thrown because the document names a chunk the origin dropped? */\nexport function isStaleBuildError(error: unknown): boolean {\n  if (!error) return false\n  const thrown = error as { name?: unknown; message?: unknown }\n  if (String(thrown.name ?? '') === 'ChunkLoadError') return true\n  return STALE_BUILD_MESSAGE.test(String(thrown.message ?? ''))\n}\n\n/**\n * Should this tab reload itself for a stale build — and, if so, SPEND the\n * recovery, so asking twice cannot answer yes twice.\n *\n * The decision and the reload are separated on purpose. The decision is\n * the part with the rate limit in it, and the part that must be provable;\n * the reload is one line at the call site, which the boundary writes where\n * a reader can see it happen.\n *\n * Every storage path is guarded: an accessor may throw in a private window\n * or with site data blocked, and a failure to RECOVER from an error must\n * never be a second error.\n */\nexport function shouldReloadForStaleBuild(error: unknown): boolean {\n  if (typeof window === 'undefined') return false\n  if (!isStaleBuildError(error)) return false\n  const now = Date.now()\n  try {\n    const last = Number(window.sessionStorage.getItem(RELOADED_KEY) ?? '')\n    // An unreadable mark is not a recent one: a stored value we cannot\n    // parse must not suppress the recovery forever.\n    if (Number.isFinite(last) && last > 0 && now - last < RECOVERY_INTERVAL_MS) {\n      return false\n    }\n    window.sessionStorage.setItem(RELOADED_KEY, String(now))\n  } catch {\n    // No storage is no rate limit, and an unbounded reload is worse than a\n    // crash page: take the crash page.\n    return false\n  }\n  return true\n}\n"],"names":["RELOADED_KEY","RECOVERY_INTERVAL_MS","STALE_BUILD_MESSAGE","isStaleBuildError","error","thrown","String","name","test","message","shouldReloadForStaleBuild","window","now","Date","last","Number","sessionStorage","getItem","isFinite","setItem"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkCC,GAED,MAAMA,eAAe;AAErB,4DAA4D,GAC5D,OAAO,MAAMC,uBAAuB,KAAK,KAAK,KAAK;AAEnD;;;;;;;CAOC,GACD,MAAMC,sBACJ;AAEF,2EAA2E,GAC3E,OAAO,SAASC,kBAAkBC,KAAc;QAGnCC,cAC4BA;IAHvC,IAAI,CAACD,OAAO,OAAO;IACnB,MAAMC,SAASD;IACf,IAAIE,QAAOD,eAAAA,OAAOE,IAAI,YAAXF,eAAe,QAAQ,kBAAkB,OAAO;IAC3D,OAAOH,oBAAoBM,IAAI,CAACF,QAAOD,kBAAAA,OAAOI,OAAO,YAAdJ,kBAAkB;AAC3D;AAEA;;;;;;;;;;;;CAYC,GACD,OAAO,SAASK,0BAA0BN,KAAc;IACtD,IAAI,OAAOO,WAAW,aAAa,OAAO;IAC1C,IAAI,CAACR,kBAAkBC,QAAQ,OAAO;IACtC,MAAMQ,MAAMC,KAAKD,GAAG;IACpB,IAAI;YACkBD;QAApB,MAAMG,OAAOC,QAAOJ,iCAAAA,OAAOK,cAAc,CAACC,OAAO,CAACjB,yBAA9BW,iCAA+C;QACnE,mEAAmE;QACnE,gDAAgD;QAChD,IAAII,OAAOG,QAAQ,CAACJ,SAASA,OAAO,KAAKF,MAAME,OAAOb,sBAAsB;YAC1E,OAAO;QACT;QACAU,OAAOK,cAAc,CAACG,OAAO,CAACnB,cAAcM,OAAOM;IACrD,EAAE,eAAM;QACN,uEAAuE;QACvE,mCAAmC;QACnC,OAAO;IACT;IACA,OAAO;AACT"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/stale-build-error.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\n/**\n * THE TAB THAT WAS OPEN ACROSS A DEPLOY (AGL-3279).\n *\n * Every build names its chunks by content hash and the previous build's are\n * not kept, so a tab loaded before a release asks for a file the origin no\n * longer serves the moment it navigates or opens a lazy route. The browser\n * rejects the import, the boundary above catches it, and the visitor is\n * shown a crash page with a **Try again** button that cannot possibly work:\n * `reset()` re-renders the same tree, which requests the same missing chunk.\n * It reported once in the 48h to 2026-09-23, on `aglyn.com`.\n *\n * A reload fixes it completely, because the fresh document names the chunks\n * the deploy actually shipped. What matters is that it may never LOOP: a\n * genuinely broken deploy would otherwise reload every visitor forever, and\n * an error reporter's first rule — never become the outage — applies twice\n * over to something that reloads pages.\n *\n * So the recovery is RATE-BOUND, held in session storage: at most one\n * reload per tab per {@link RECOVERY_INTERVAL_MS}, and a browser that\n * refuses storage gets none at all rather than an unbounded one. A second\n * failure inside that window renders the crash page and stays there, which\n * is the honest outcome — at that point the build really is broken and\n * reloading is not the answer.\n *\n * An interval rather than a once-ever mark, because a console tab lives for\n * days and this repo ships several times a day: a once-ever mark would\n * spend the tab's only recovery on the first deploy it survived and leave\n * it stranded on the third. Long enough that no plausible loop is\n * comfortable; short enough that the next release is covered.\n *\n * A module of its own, not a function in `error-beacon.ts`, for the reason\n * `redispatch-caught-error.ts` gives: an error boundary's chunk is\n * downloaded by every visitor, and importing one name off the beacon would\n * drag its whole installer in with it.\n */\n\nimport { redispatchCaughtError } from './redispatch-caught-error'\n\nconst RELOADED_KEY = 'aglyn.staleBuildReloaded'\n\n/** How long one recovery suppresses the next, in this tab. */\nexport const RECOVERY_INTERVAL_MS = 30 * 60 * 1_000\n\n/**\n * Messages the browsers spell differently for one event — the module the\n * document names is not there.\n *\n * Matched on the MESSAGE as well as the name because only webpack's own\n * failure carries `name === 'ChunkLoadError'`; a native dynamic import that\n * 404s rejects with a plain `TypeError` whose wording is the browser's.\n */\nconst STALE_BUILD_MESSAGE =\n  /Loading chunk .* failed|Failed to load chunk|Loading CSS chunk .* failed|error loading dynamically imported module|Importing a module script failed|Failed to fetch dynamically imported module/i\n\n/** Was this thrown because the document names a chunk the origin dropped? */\nexport function isStaleBuildError(error: unknown): boolean {\n  if (!error) return false\n  const thrown = error as { name?: unknown; message?: unknown }\n  if (String(thrown.name ?? '') === 'ChunkLoadError') return true\n  return STALE_BUILD_MESSAGE.test(String(thrown.message ?? ''))\n}\n\n/**\n * Should this tab reload itself for a stale build — and, if so, SPEND the\n * recovery, so asking twice cannot answer yes twice.\n *\n * The decision and the reload are separated on purpose. The decision is\n * the part with the rate limit in it, and the part that must be provable;\n * the reload is one line at the call site, which the boundary writes where\n * a reader can see it happen.\n *\n * Every storage path is guarded: an accessor may throw in a private window\n * or with site data blocked, and a failure to RECOVER from an error must\n * never be a second error.\n */\nexport function shouldReloadForStaleBuild(error: unknown): boolean {\n  if (typeof window === 'undefined') return false\n  if (!isStaleBuildError(error)) return false\n  const now = Date.now()\n  try {\n    const last = Number(window.sessionStorage.getItem(RELOADED_KEY) ?? '')\n    // An unreadable mark is not a recent one: a stored value we cannot\n    // parse must not suppress the recovery forever.\n    if (Number.isFinite(last) && last > 0 && now - last < RECOVERY_INTERVAL_MS) {\n      return false\n    }\n    window.sessionStorage.setItem(RELOADED_KEY, String(now))\n  } catch {\n    // No storage is no rate limit, and an unbounded reload is worse than a\n    // crash page: take the crash page.\n    return false\n  }\n  return true\n}\n\n/**\n * Withdraws the reload {@link recoverStaleBuildRejection} scheduled; true\n * when there was one.\n */\nlet cancelPending: (() => void) | null = null\n\nfunction cancelPendingReload(): boolean {\n  if (!cancelPending) return false\n  cancelPending()\n  return true\n}\n\n/** Re-load the document; a refused reload leaves the tab where it was. */\nfunction reloadDocument(): void {\n  try {\n    window.location.reload()\n  } catch {\n    // Nothing to do: the crash page is already on screen.\n  }\n}\n\n/**\n * What EVERY error boundary does with what it caught: reload once for a stale\n * build, and otherwise hand the error to the beacon. `global-error.tsx`\n * included: it catches what the root layout threw, and a stale tab's root\n * layout asks for its chunks like any other segment.\n *\n * One function so that no boundary can run half of it. The ones that matter\n * most are not the root boundaries but the two below them on a published\n * site — `PageBodyBoundary` around the page body and\n * `[host]/[scheme]/error.tsx` around the page — because a site plugin's chunk\n * is loaded by the page body, so those are what a stale tab reaches. A\n * boundary there that only re-dispatched would leave an empty body, or a\n * **Try again** that cannot work, and report a `ChunkLoadError` for it.\n *\n * A reloaded error is NOT reported; the fresh document is the fix, and the\n * tab it happened in is gone. What still reaches the beacon is the failure a\n * reload did not cure — a second one inside the recovery window, or a\n * browser that refuses storage — which the beacon labels `chunk-load`.\n *\n * `reload` is a parameter only so a spec can observe it: jsdom refuses to let\n * one redefine `location.reload`.\n *\n * @returns whether the tab is reloading.\n */\nexport function recoverStaleBuildOrReport(\n  error: unknown,\n  reload: () => void = reloadDocument,\n): boolean {\n  // A rejection already spent this tab's recovery on a reload that waits for\n  // the tab to be hidden. The page has crashed now, so there is nothing left\n  // on screen to protect: take that reload immediately.\n  if (isStaleBuildError(error) && cancelPendingReload()) {\n    reload()\n    return true\n  }\n  if (shouldReloadForStaleBuild(error)) {\n    reload()\n    return true\n  }\n  redispatchCaughtError(error)\n  return false\n}\n\n/**\n * THE SAME TAB, WHEN NO BOUNDARY SAW IT (AGL-3423).\n *\n * An `import()` that nothing awaits inside a render, a click handler's lazy\n * module or an effect's, rejects past every boundary and reaches `window` as\n * an `unhandledrejection`. The beacon labels it `chunk-load`, and until now\n * that was all: the tab stayed on the old build with one feature silently\n * dead.\n *\n * The recovery differs from a boundary's in WHEN it reloads. A boundary\n * reloads a page that has already crashed. Here the page is still up and\n * may hold work the visitor has not saved: a Besigner edit, a half-typed\n * form. So the reload waits until the tab is hidden, the moment AGL-3280's\n * cross-pool recovery also uses, and runs at once only when the tab is\n * already hidden. The visitor comes back to the build that is deployed.\n *\n * It spends the same rate-bound mark as a boundary, so it can never loop,\n * and it absorbs every later stale-build rejection in the tab while the\n * reload is pending: they are the same stale document, not new failures.\n * A boundary that catches one meanwhile takes the pending reload at once.\n *\n * @returns whether the rejection was recovered, and so should not be\n *   reported. False for any other rejection, and for a stale build whose\n *   recovery is spent, which the beacon still reports as `chunk-load`.\n */\nexport function recoverStaleBuildRejection(\n  reason: unknown,\n  reload: () => void = reloadDocument,\n): boolean {\n  if (typeof document === 'undefined' || !isStaleBuildError(reason)) return false\n  if (cancelPending) return true\n  if (!shouldReloadForStaleBuild(reason)) return false\n  if (document.visibilityState === 'hidden') {\n    reload()\n    return true\n  }\n  const onVisibilityChange = () => {\n    if (document.visibilityState !== 'hidden') return\n    cancelPendingReload()\n    reload()\n  }\n  cancelPending = () => {\n    document.removeEventListener('visibilitychange', onVisibilityChange)\n    cancelPending = null\n  }\n  document.addEventListener('visibilitychange', onVisibilityChange)\n  return true\n}\n"],"names":["redispatchCaughtError","RELOADED_KEY","RECOVERY_INTERVAL_MS","STALE_BUILD_MESSAGE","isStaleBuildError","error","thrown","String","name","test","message","shouldReloadForStaleBuild","window","now","Date","last","Number","sessionStorage","getItem","isFinite","setItem","cancelPending","cancelPendingReload","reloadDocument","location","reload","recoverStaleBuildOrReport","recoverStaleBuildRejection","reason","document","visibilityState","onVisibilityChange","removeEventListener","addEventListener"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkCC,GAED,SAASA,qBAAqB,QAAQ,+BAA2B;AAEjE,MAAMC,eAAe;AAErB,4DAA4D,GAC5D,OAAO,MAAMC,uBAAuB,KAAK,KAAK,KAAK;AAEnD;;;;;;;CAOC,GACD,MAAMC,sBACJ;AAEF,2EAA2E,GAC3E,OAAO,SAASC,kBAAkBC,KAAc;QAGnCC,cAC4BA;IAHvC,IAAI,CAACD,OAAO,OAAO;IACnB,MAAMC,SAASD;IACf,IAAIE,QAAOD,eAAAA,OAAOE,IAAI,YAAXF,eAAe,QAAQ,kBAAkB,OAAO;IAC3D,OAAOH,oBAAoBM,IAAI,CAACF,QAAOD,kBAAAA,OAAOI,OAAO,YAAdJ,kBAAkB;AAC3D;AAEA;;;;;;;;;;;;CAYC,GACD,OAAO,SAASK,0BAA0BN,KAAc;IACtD,IAAI,OAAOO,WAAW,aAAa,OAAO;IAC1C,IAAI,CAACR,kBAAkBC,QAAQ,OAAO;IACtC,MAAMQ,MAAMC,KAAKD,GAAG;IACpB,IAAI;YACkBD;QAApB,MAAMG,OAAOC,QAAOJ,iCAAAA,OAAOK,cAAc,CAACC,OAAO,CAACjB,yBAA9BW,iCAA+C;QACnE,mEAAmE;QACnE,gDAAgD;QAChD,IAAII,OAAOG,QAAQ,CAACJ,SAASA,OAAO,KAAKF,MAAME,OAAOb,sBAAsB;YAC1E,OAAO;QACT;QACAU,OAAOK,cAAc,CAACG,OAAO,CAACnB,cAAcM,OAAOM;IACrD,EAAE,eAAM;QACN,uEAAuE;QACvE,mCAAmC;QACnC,OAAO;IACT;IACA,OAAO;AACT;AAEA;;;CAGC,GACD,IAAIQ,gBAAqC;AAEzC,SAASC;IACP,IAAI,CAACD,eAAe,OAAO;IAC3BA;IACA,OAAO;AACT;AAEA,wEAAwE,GACxE,SAASE;IACP,IAAI;QACFX,OAAOY,QAAQ,CAACC,MAAM;IACxB,EAAE,eAAM;IACN,sDAAsD;IACxD;AACF;AAEA;;;;;;;;;;;;;;;;;;;;;;;CAuBC,GACD,OAAO,SAASC,0BACdrB,KAAc,EACdoB,SAAqBF,cAAc;IAEnC,2EAA2E;IAC3E,2EAA2E;IAC3E,sDAAsD;IACtD,IAAInB,kBAAkBC,UAAUiB,uBAAuB;QACrDG;QACA,OAAO;IACT;IACA,IAAId,0BAA0BN,QAAQ;QACpCoB;QACA,OAAO;IACT;IACAzB,sBAAsBK;IACtB,OAAO;AACT;AAEA;;;;;;;;;;;;;;;;;;;;;;;;CAwBC,GACD,OAAO,SAASsB,2BACdC,MAAe,EACfH,SAAqBF,cAAc;IAEnC,IAAI,OAAOM,aAAa,eAAe,CAACzB,kBAAkBwB,SAAS,OAAO;IAC1E,IAAIP,eAAe,OAAO;IAC1B,IAAI,CAACV,0BAA0BiB,SAAS,OAAO;IAC/C,IAAIC,SAASC,eAAe,KAAK,UAAU;QACzCL;QACA,OAAO;IACT;IACA,MAAMM,qBAAqB;QACzB,IAAIF,SAASC,eAAe,KAAK,UAAU;QAC3CR;QACAG;IACF;IACAJ,gBAAgB;QACdQ,SAASG,mBAAmB,CAAC,oBAAoBD;QACjDV,gBAAgB;IAClB;IACAQ,SAASI,gBAAgB,CAAC,oBAAoBF;IAC9C,OAAO;AACT"}

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

@@ -0,0 +1,137 @@
+/**
+ * @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.
+ */
+/**
+ * What a starter site is, and the kit its pages are built with (AGL-687,
+ * AGL-3080).
+ *
+ * A starter is a bundle of page templates the template gallery offers and
+ * the seed route copies into a site's library on first use. The platform's
+ * own starters live in `starter-templates.ts`; a plugin whose elements a
+ * starter is built around declares its own, built with this same kit, and
+ * the manifest generator compiles them into
+ * `plugin-starter-templates.generated.ts`.
+ *
+ * Leaf imports only, for the reason `starter-templates.ts` states: this is
+ * read from the console's client gallery, its seed route and a plugin's
+ * server alike, so it imports a canvas constant and nothing that drags in
+ * either barrel.
+ *
+ * PERSISTED IDENTIFIERS: `StarterTemplate.id`, `StarterTemplateScreen.key`
+ * and every node id a starter builds appear in stored documents (seeded
+ * template doc ids are derived from the first two). They must never be
+ * renamed.
+ */
+export interface StarterTemplateScreen {
+    /**
+     * Stable, starter-local key. Part of the seeded document id, so it is a
+     * persisted identifier — never rename one.
+     */
+    key: string;
+    displayName: string;
+    description?: string;
+    /**
+     * Routing-map slug. `SCREEN_ROOT_PATH` (`'/'`) asks for the site root — the
+     * home page — and anything else is a single path segment.
+     *
+     * It used to be `''` that meant home, which no normalizer agreed with: both
+     * the apply path and the seed below read an empty string as "no address
+     * authored" and derived one from the display name, so the shop starters'
+     * home page was published at `/home` and the site 404'd at its own URL
+     * (AGL-1575).
+     */
+    slug: string;
+    seo?: {
+        title?: string;
+        description?: string;
+    };
+    /** Flat node map including the canvas root. */
+    nodes: Record<string, any>;
+}
+export interface StarterTemplate {
+    id: string;
+    displayName: string;
+    description: string;
+    category: string;
+    screens: StarterTemplateScreen[];
+}
+/** A materialized starter template document, keyed by its deterministic id. */
+export type StarterNodeSpec = {
+    id: string;
+    componentId: string;
+    /** Bundle owning the component; defaults to 'mui' (AGL-300). */
+    pluginId?: string;
+    props?: Record<string, unknown>;
+    /**
+     * Node-level styles — a SIBLING of props, never `props.sx` (AGL-1346).
+     *
+     * Both records render (`Leaf` composes `(sx, props.sx, node.sx)`, later
+     * wins), but the Styles panel edits `node.sx`. A starter that seeded its
+     * styling into `props.sx` handed the author a document full of values
+     * the panel could show but no click could change or clear.
+     */
+    sx?: Record<string, unknown>;
+    children?: StarterNodeSpec[];
+};
+/** Builds the flat, persisted node map from a nested spec. */
+export declare function buildStarterNodes(children: StarterNodeSpec[]): Record<string, any>;
+/** One line of a starter's copy: a `muiTypography` of the given variant. */
+export declare const starterText: (id: string, variant: string, children: string, extra?: Record<string, unknown>) => StarterNodeSpec;
+/**
+ * The stock widths a starter band may be (AGL-1932, AGL-1298).
+ *
+ * Three cases, and only three, because the standard has three. There is no
+ * pixel case: `1328` is a CONTENT width, not a breakpoint, and the ban on
+ * bespoke numbers is the half of AGL-1298 these templates used to violate
+ * four times over.
+ */
+export type StarterSectionWidth = 'md' | 'lg' | 'xl';
+/**
+ * One page band: a `Container` at a stock width, carrying the band's own
+ * vertical rhythm (AGL-1932).
+ *
+ * The layout standard (AGL-1298): every section is a Container. Full-bleed is
+ * the Container's own full-width attribute, never the absence of a Container,
+ * and anything else is one of three stock widths. A template that seeds no
+ * Container hands every customer a site that starts outside the standard.
+ *
+ * How the three widths are chosen here, stated so the next audit does not
+ * have to guess:
+ *
+ * - `xl` — a marketing band: hero, feature row, product grid, gallery. The
+ *   default width, and what an unremarkable page should be.
+ * - `lg` — the deliberate middle case: wide but text-led and interactive.
+ *   Cart and account are the honest instances, not decoration.
+ * - `md` — long-form prose and narrow form columns, on READING grounds: at
+ *   `xl` a paragraph runs 110–120 characters a line. This is the case the
+ *   `Prose Container` preset exists for.
+ *
+ * Horizontal padding is the Container's own gutters, so bands no longer carry
+ * horizontal padding at all. Only the vertical rhythm rides here, which is
+ * rhythm rather than width.
+ *
+ * Written as the two longhands rather than MUI's `py` (AGL-2207/2208): the
+ * Styles panel's Padding control is named for the four sides, so a band
+ * seeded with `py` handed the customer a document whose padding the panel
+ * showed as empty and no click could clear.
+ */
+export declare const starterSection: (id: string, maxWidth: StarterSectionWidth, verticalPadding: number, children: StarterNodeSpec[]) => StarterNodeSpec;
+/**
+ * The hero band a starter page opens with: a headline, a tagline and a call
+ * to action, centered in an `xl` band. Its node ids are `prefix` plus fixed
+ * names, so a starter's prefix keeps them its own.
+ */
+export declare const starterHeroSection: (prefix: string, headline: string, tagline: string) => StarterNodeSpec;

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

@@ -0,0 +1,129 @@
+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 { CANVAS_ROOT_ELEMENT_ID } from "../foundation/constants/canvas.js";
+/** Builds the flat, persisted node map from a nested spec. */ export function buildStarterNodes(children) {
+    const map = {
+        [CANVAS_ROOT_ELEMENT_ID]: {
+            $id: CANVAS_ROOT_ELEMENT_ID,
+            componentId: 'div',
+            nodes: children.map((child)=>child.id)
+        }
+    };
+    const walk = (spec, parentId)=>{
+        var _spec_pluginId, _spec_props, _spec_children, _spec_children1;
+        map[spec.id] = _extends({
+            $id: spec.id,
+            componentId: spec.componentId,
+            pluginId: (_spec_pluginId = spec.pluginId) != null ? _spec_pluginId : 'mui',
+            parentId,
+            props: (_spec_props = spec.props) != null ? _spec_props : {}
+        }, spec.sx ? {
+            sx: spec.sx
+        } : {}, {
+            nodes: ((_spec_children = spec.children) != null ? _spec_children : []).map((child)=>child.id)
+        });
+        for (const child of (_spec_children1 = spec.children) != null ? _spec_children1 : [])walk(child, spec.id);
+    };
+    for (const child of children)walk(child, CANVAS_ROOT_ELEMENT_ID);
+    return map;
+}
+/** One line of a starter's copy: a `muiTypography` of the given variant. */ export const starterText = (id, variant, children, extra)=>({
+        id,
+        componentId: 'muiTypography',
+        props: _extends({
+            variant,
+            children
+        }, extra)
+    });
+/**
+ * One page band: a `Container` at a stock width, carrying the band's own
+ * vertical rhythm (AGL-1932).
+ *
+ * The layout standard (AGL-1298): every section is a Container. Full-bleed is
+ * the Container's own full-width attribute, never the absence of a Container,
+ * and anything else is one of three stock widths. A template that seeds no
+ * Container hands every customer a site that starts outside the standard.
+ *
+ * How the three widths are chosen here, stated so the next audit does not
+ * have to guess:
+ *
+ * - `xl` — a marketing band: hero, feature row, product grid, gallery. The
+ *   default width, and what an unremarkable page should be.
+ * - `lg` — the deliberate middle case: wide but text-led and interactive.
+ *   Cart and account are the honest instances, not decoration.
+ * - `md` — long-form prose and narrow form columns, on READING grounds: at
+ *   `xl` a paragraph runs 110–120 characters a line. This is the case the
+ *   `Prose Container` preset exists for.
+ *
+ * Horizontal padding is the Container's own gutters, so bands no longer carry
+ * horizontal padding at all. Only the vertical rhythm rides here, which is
+ * rhythm rather than width.
+ *
+ * Written as the two longhands rather than MUI's `py` (AGL-2207/2208): the
+ * Styles panel's Padding control is named for the four sides, so a band
+ * seeded with `py` handed the customer a document whose padding the panel
+ * showed as empty and no click could clear.
+ */ export const starterSection = (id, maxWidth, verticalPadding, children)=>({
+        id,
+        componentId: 'muiContainer',
+        props: {
+            maxWidth
+        },
+        sx: {
+            paddingTop: verticalPadding,
+            paddingBottom: verticalPadding
+        },
+        children
+    });
+/**
+ * The hero band a starter page opens with: a headline, a tagline and a call
+ * to action, centered in an `xl` band. Its node ids are `prefix` plus fixed
+ * names, so a starter's prefix keeps them its own.
+ */ export const starterHeroSection = (prefix, headline, tagline)=>// The Container is a NEW node (`…heroSection`); `…hero` keeps its id and
+    // stays the Stack. Node ids here are persisted identifiers, so bands are
+    // wrapped rather than re-pointed.
+    starterSection(`${prefix}heroSection`, 'xl', 10, [
+        {
+            id: `${prefix}hero`,
+            componentId: 'muiStack',
+            props: {
+                spacing: 2
+            },
+            sx: {
+                alignItems: 'center'
+            },
+            children: [
+                starterText(`${prefix}heroTitle`, 'h2', headline, {
+                    align: 'center'
+                }),
+                starterText(`${prefix}heroSub`, 'h6', tagline, {
+                    align: 'center'
+                }),
+                {
+                    id: `${prefix}heroCta`,
+                    componentId: 'muiButton',
+                    props: {
+                        variant: 'contained',
+                        size: 'large',
+                        children: 'Get in touch'
+                    }
+                }
+            ]
+        }
+    ]);
+
+//# sourceMappingURL=starter-template-nodes.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/starter-template-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 { CANVAS_ROOT_ELEMENT_ID } from '../foundation/constants/canvas'\n\n/**\n * What a starter site is, and the kit its pages are built with (AGL-687,\n * AGL-3080).\n *\n * A starter is a bundle of page templates the template gallery offers and\n * the seed route copies into a site's library on first use. The platform's\n * own starters live in `starter-templates.ts`; a plugin whose elements a\n * starter is built around declares its own, built with this same kit, and\n * the manifest generator compiles them into\n * `plugin-starter-templates.generated.ts`.\n *\n * Leaf imports only, for the reason `starter-templates.ts` states: this is\n * read from the console's client gallery, its seed route and a plugin's\n * server alike, so it imports a canvas constant and nothing that drags in\n * either barrel.\n *\n * PERSISTED IDENTIFIERS: `StarterTemplate.id`, `StarterTemplateScreen.key`\n * and every node id a starter builds appear in stored documents (seeded\n * template doc ids are derived from the first two). They must never be\n * renamed.\n */\nexport interface StarterTemplateScreen {\n  /**\n   * Stable, starter-local key. Part of the seeded document id, so it is a\n   * persisted identifier — never rename one.\n   */\n  key: string\n  displayName: string\n  description?: string\n  /**\n   * Routing-map slug. `SCREEN_ROOT_PATH` (`'/'`) asks for the site root — the\n   * home page — and anything else is a single path segment.\n   *\n   * It used to be `''` that meant home, which no normalizer agreed with: both\n   * the apply path and the seed below read an empty string as \"no address\n   * authored\" and derived one from the display name, so the shop starters'\n   * home page was published at `/home` and the site 404'd at its own URL\n   * (AGL-1575).\n   */\n  slug: string\n  seo?: { title?: string; description?: string }\n  /** Flat node map including the canvas root. */\n  nodes: Record<string, any>\n}\n\nexport interface StarterTemplate {\n  id: string\n  displayName: string\n  description: string\n  category: string\n  screens: StarterTemplateScreen[]\n}\n\n/** A materialized starter template document, keyed by its deterministic id. */\n\nexport type StarterNodeSpec = {\n  id: string\n  componentId: string\n  /** Bundle owning the component; defaults to 'mui' (AGL-300). */\n  pluginId?: string\n  props?: Record<string, unknown>\n  /**\n   * Node-level styles — a SIBLING of props, never `props.sx` (AGL-1346).\n   *\n   * Both records render (`Leaf` composes `(sx, props.sx, node.sx)`, later\n   * wins), but the Styles panel edits `node.sx`. A starter that seeded its\n   * styling into `props.sx` handed the author a document full of values\n   * the panel could show but no click could change or clear.\n   */\n  sx?: Record<string, unknown>\n  children?: StarterNodeSpec[]\n}\n\n/** Builds the flat, persisted node map from a nested spec. */\nexport function buildStarterNodes(children: StarterNodeSpec[]): Record<string, any> {\n  const map: Record<string, any> = {\n    [CANVAS_ROOT_ELEMENT_ID]: {\n      $id: CANVAS_ROOT_ELEMENT_ID,\n      componentId: 'div',\n      nodes: children.map((child) => child.id),\n    },\n  }\n  const walk = (spec: StarterNodeSpec, parentId: string) => {\n    map[spec.id] = {\n      $id: spec.id,\n      componentId: spec.componentId,\n      pluginId: spec.pluginId ?? 'mui',\n      parentId,\n      props: spec.props ?? {},\n      ...(spec.sx ? { sx: spec.sx } : {}),\n      nodes: (spec.children ?? []).map((child) => child.id),\n    }\n    for (const child of spec.children ?? []) walk(child, spec.id)\n  }\n  for (const child of children) walk(child, CANVAS_ROOT_ELEMENT_ID)\n  return map\n}\n\n/** One line of a starter's copy: a `muiTypography` of the given variant. */\nexport const starterText = (\n  id: string,\n  variant: string,\n  children: string,\n  extra?: Record<string, unknown>,\n): StarterNodeSpec => ({\n  id,\n  componentId: 'muiTypography',\n  props: { variant, children, ...extra },\n})\n\n/**\n * The stock widths a starter band may be (AGL-1932, AGL-1298).\n *\n * Three cases, and only three, because the standard has three. There is no\n * pixel case: `1328` is a CONTENT width, not a breakpoint, and the ban on\n * bespoke numbers is the half of AGL-1298 these templates used to violate\n * four times over.\n */\nexport type StarterSectionWidth = 'md' | 'lg' | 'xl'\n\n/**\n * One page band: a `Container` at a stock width, carrying the band's own\n * vertical rhythm (AGL-1932).\n *\n * The layout standard (AGL-1298): every section is a Container. Full-bleed is\n * the Container's own full-width attribute, never the absence of a Container,\n * and anything else is one of three stock widths. A template that seeds no\n * Container hands every customer a site that starts outside the standard.\n *\n * How the three widths are chosen here, stated so the next audit does not\n * have to guess:\n *\n * - `xl` — a marketing band: hero, feature row, product grid, gallery. The\n *   default width, and what an unremarkable page should be.\n * - `lg` — the deliberate middle case: wide but text-led and interactive.\n *   Cart and account are the honest instances, not decoration.\n * - `md` — long-form prose and narrow form columns, on READING grounds: at\n *   `xl` a paragraph runs 110–120 characters a line. This is the case the\n *   `Prose Container` preset exists for.\n *\n * Horizontal padding is the Container's own gutters, so bands no longer carry\n * horizontal padding at all. Only the vertical rhythm rides here, which is\n * rhythm rather than width.\n *\n * Written as the two longhands rather than MUI's `py` (AGL-2207/2208): the\n * Styles panel's Padding control is named for the four sides, so a band\n * seeded with `py` handed the customer a document whose padding the panel\n * showed as empty and no click could clear.\n */\nexport const starterSection = (\n  id: string,\n  maxWidth: StarterSectionWidth,\n  verticalPadding: number,\n  children: StarterNodeSpec[],\n): StarterNodeSpec => ({\n  id,\n  componentId: 'muiContainer',\n  props: { maxWidth },\n  sx: { paddingTop: verticalPadding, paddingBottom: verticalPadding },\n  children,\n})\n\n/**\n * The hero band a starter page opens with: a headline, a tagline and a call\n * to action, centered in an `xl` band. Its node ids are `prefix` plus fixed\n * names, so a starter's prefix keeps them its own.\n */\nexport const starterHeroSection = (\n  prefix: string,\n  headline: string,\n  tagline: string,\n): StarterNodeSpec =>\n  // The Container is a NEW node (`…heroSection`); `…hero` keeps its id and\n  // stays the Stack. Node ids here are persisted identifiers, so bands are\n  // wrapped rather than re-pointed.\n  starterSection(`${prefix}heroSection`, 'xl', 10, [\n    {\n      id: `${prefix}hero`,\n      componentId: 'muiStack',\n      props: { spacing: 2 },\n      sx: { alignItems: 'center' },\n      children: [\n        starterText(`${prefix}heroTitle`, 'h2', headline, { align: 'center' }),\n        starterText(`${prefix}heroSub`, 'h6', tagline, { align: 'center' }),\n        {\n          id: `${prefix}heroCta`,\n          componentId: 'muiButton',\n          props: {\n            variant: 'contained',\n            size: 'large',\n            children: 'Get in touch',\n          },\n        },\n      ],\n    },\n  ])\n"],"names":["CANVAS_ROOT_ELEMENT_ID","buildStarterNodes","children","map","$id","componentId","nodes","child","id","walk","spec","parentId","pluginId","props","sx","starterText","variant","extra","starterSection","maxWidth","verticalPadding","paddingTop","paddingBottom","starterHeroSection","prefix","headline","tagline","spacing","alignItems","align","size"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,sBAAsB,QAAQ,oCAAgC;AA2EvE,4DAA4D,GAC5D,OAAO,SAASC,kBAAkBC,QAA2B;IAC3D,MAAMC,MAA2B;QAC/B,CAACH,uBAAuB,EAAE;YACxBI,KAAKJ;YACLK,aAAa;YACbC,OAAOJ,SAASC,GAAG,CAAC,CAACI,QAAUA,MAAMC,EAAE;QACzC;IACF;IACA,MAAMC,OAAO,CAACC,MAAuBC;YAIvBD,gBAEHA,aAECA,gBAEUA;QATpBP,GAAG,CAACO,KAAKF,EAAE,CAAC,GAAG;YACbJ,KAAKM,KAAKF,EAAE;YACZH,aAAaK,KAAKL,WAAW;YAC7BO,QAAQ,GAAEF,iBAAAA,KAAKE,QAAQ,YAAbF,iBAAiB;YAC3BC;YACAE,KAAK,GAAEH,cAAAA,KAAKG,KAAK,YAAVH,cAAc,CAAC;WAClBA,KAAKI,EAAE,GAAG;YAAEA,IAAIJ,KAAKI,EAAE;QAAC,IAAI,CAAC;YACjCR,OAAO,EAACI,iBAAAA,KAAKR,QAAQ,YAAbQ,iBAAiB,EAAE,EAAEP,GAAG,CAAC,CAACI,QAAUA,MAAMC,EAAE;;QAEtD,KAAK,MAAMD,UAASG,kBAAAA,KAAKR,QAAQ,YAAbQ,kBAAiB,EAAE,CAAED,KAAKF,OAAOG,KAAKF,EAAE;IAC9D;IACA,KAAK,MAAMD,SAASL,SAAUO,KAAKF,OAAOP;IAC1C,OAAOG;AACT;AAEA,0EAA0E,GAC1E,OAAO,MAAMY,cAAc,CACzBP,IACAQ,SACAd,UACAe,QACqB,CAAA;QACrBT;QACAH,aAAa;QACbQ,OAAO;YAAEG;YAASd;WAAae;IACjC,CAAA,EAAE;AAYF;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BC,GACD,OAAO,MAAMC,iBAAiB,CAC5BV,IACAW,UACAC,iBACAlB,WACqB,CAAA;QACrBM;QACAH,aAAa;QACbQ,OAAO;YAAEM;QAAS;QAClBL,IAAI;YAAEO,YAAYD;YAAiBE,eAAeF;QAAgB;QAClElB;IACF,CAAA,EAAE;AAEF;;;;CAIC,GACD,OAAO,MAAMqB,qBAAqB,CAChCC,QACAC,UACAC,UAEA,yEAAyE;IACzE,yEAAyE;IACzE,kCAAkC;IAClCR,eAAe,GAAGM,OAAO,WAAW,CAAC,EAAE,MAAM,IAAI;QAC/C;YACEhB,IAAI,GAAGgB,OAAO,IAAI,CAAC;YACnBnB,aAAa;YACbQ,OAAO;gBAAEc,SAAS;YAAE;YACpBb,IAAI;gBAAEc,YAAY;YAAS;YAC3B1B,UAAU;gBACRa,YAAY,GAAGS,OAAO,SAAS,CAAC,EAAE,MAAMC,UAAU;oBAAEI,OAAO;gBAAS;gBACpEd,YAAY,GAAGS,OAAO,OAAO,CAAC,EAAE,MAAME,SAAS;oBAAEG,OAAO;gBAAS;gBACjE;oBACErB,IAAI,GAAGgB,OAAO,OAAO,CAAC;oBACtBnB,aAAa;oBACbQ,OAAO;wBACLG,SAAS;wBACTc,MAAM;wBACN5B,UAAU;oBACZ;gBACF;aACD;QACH;KACD,EAAC"}

package/src/lib/app-utils/starter-templates.d.ts

@@ -14,6 +14,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import { type StarterTemplate, type StarterTemplateScreen } from './starter-template-nodes';
+export type { StarterNodeSpec, StarterSectionWidth, StarterTemplate, StarterTemplateScreen, } from './starter-template-nodes';
+export { buildStarterNodes, starterHeroSection, starterSection, starterText, } from './starter-template-nodes';
 /**
  * First-party starter definitions (AGL-78/79), SEED INPUT (AGL-687).
  *
@@ -36,40 +39,6 @@
  * and every node id below appear in stored documents (seeded template doc
  * ids are derived from the first two). They must never be renamed.
  */
-export interface StarterTemplateScreen {
-    /**
-     * Stable, starter-local key. Part of the seeded document id, so it is a
-     * persisted identifier — never rename one.
-     */
-    key: string;
-    displayName: string;
-    description?: string;
-    /**
-     * Routing-map slug. `SCREEN_ROOT_PATH` (`'/'`) asks for the site root — the
-     * home page — and anything else is a single path segment.
-     *
-     * It used to be `''` that meant home, which no normalizer agreed with: both
-     * the apply path and the seed below read an empty string as "no address
-     * authored" and derived one from the display name, so the shop starters'
-     * home page was published at `/home` and the site 404'd at its own URL
-     * (AGL-1575).
-     */
-    slug: string;
-    seo?: {
-        title?: string;
-        description?: string;
-    };
-    /** Flat node map including the canvas root. */
-    nodes: Record<string, any>;
-}
-export interface StarterTemplate {
-    id: string;
-    displayName: string;
-    description: string;
-    category: string;
-    screens: StarterTemplateScreen[];
-}
-/** A materialized starter template document, keyed by its deterministic id. */
 export interface StarterTemplateDoc {
     id: string;
     /** Which starter this page belongs to — lets one starter be selected. */
@@ -116,4 +85,12 @@ export declare function buildAllStarterTemplateDocs(): StarterTemplateDoc[];
  * PERSISTED IDENTIFIERS: every node id below is stored on every new site.
  */
 export declare function buildDefaultHomeScreen(siteName: string): StarterTemplateScreen;
+/**
+ * Every starter in this build, in gallery order: the platform's own, then
+ * each plugin's in config order (AGL-3080). A plugin whose elements a starter
+ * is built around — a storefront's product grid and cart — declares it under
+ * `starterTemplates` in plugins.config.json, and the manifest generator
+ * compiles what it returns, so the gallery, the seed route and a model
+ * shown examples all read one list without loading any plugin.
+ */
 export declare const STARTER_TEMPLATES: StarterTemplate[];