@aglyn/aglyn 1.0.0-beta.172 → 1.0.0-beta.173

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/aglyn",
-  "version": "1.0.0-beta.172",
+  "version": "1.0.0-beta.173",
   "license": "Apache-2.0",
   "homepage": "https://aglyn.com",
   "repository": {
@@ -33,15 +33,15 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@aglyn/shared-data-enums": "1.0.0-beta.172",
-    "@aglyn/shared-data-mdi": "1.0.0-beta.172",
-    "@aglyn/shared-data-types": "1.0.0-beta.172",
-    "@aglyn/shared-util-email": "1.0.0-beta.172",
-    "@aglyn/shared-util-http": "1.0.0-beta.172",
-    "@aglyn/shared-util-logger": "1.0.0-beta.172",
-    "@aglyn/shared-util-timestamp": "1.0.0-beta.172",
-    "@aglyn/shared-util-tools": "1.0.0-beta.172",
-    "@aglyn/shared-util-vendor": "1.0.0-beta.172",
+    "@aglyn/shared-data-enums": "1.0.0-beta.173",
+    "@aglyn/shared-data-mdi": "1.0.0-beta.173",
+    "@aglyn/shared-data-types": "1.0.0-beta.173",
+    "@aglyn/shared-util-email": "1.0.0-beta.173",
+    "@aglyn/shared-util-http": "1.0.0-beta.173",
+    "@aglyn/shared-util-logger": "1.0.0-beta.173",
+    "@aglyn/shared-util-timestamp": "1.0.0-beta.173",
+    "@aglyn/shared-util-tools": "1.0.0-beta.173",
+    "@aglyn/shared-util-vendor": "1.0.0-beta.173",
     "@data-driven-forms/react-form-renderer": "^4.2.0",
     "@msgpack/msgpack": "^3.1.3",
     "@types/unist": "^3.0.3",

package/src/lib/app-utils/compose-layout-props.d.ts

@@ -61,11 +61,15 @@ export declare function applyLayoutProps<N extends AglynNodeSchema = AglynNodeSc
 /**
  * A screen grafted through its whole layout chain, innermost first, with each
  * layout's properties applied from the screen's values for that layout
- * (`layoutPropValues`, keyed by layout id).
+ * (`layoutPropValues`, keyed by layout id), and then the screen's per-page
+ * restyling of that layout's elements (`layoutStyleOverrides`, AGL-3286) —
+ * after the properties, so a page's style wins over whatever a property
+ * bound, and before the graft, so an element the layout hides for this page
+ * is simply not there to be styled.
  *
  * The one composition the published page, the besigner's Preview and its
  * layout chrome all run, so none of them can disagree about which value a
  * layout renders with.
  */
-export declare function composeLayoutChainWithProps<N extends AglynNodeSchema = AglynNodeSchema>(chain: ReadonlyArray<LayoutChainEntry<N> | null | undefined>, screenNodes: NormalizedNodes<N>, layoutPropValues?: unknown): NormalizedNodes<N>;
+export declare function composeLayoutChainWithProps<N extends AglynNodeSchema = AglynNodeSchema>(chain: ReadonlyArray<LayoutChainEntry<N> | null | undefined>, screenNodes: NormalizedNodes<N>, layoutPropValues?: unknown, layoutStyleOverrides?: unknown): NormalizedNodes<N>;
 export default composeLayoutChainWithProps;

package/src/lib/app-utils/compose-layout-props.js

@@ -16,6 +16,7 @@
  */ import { NODE_ROOT_ID } from "../canvas-manager/canvas-manager.js";
 import { composeLayoutChainAndScreenNodes } from "./compose-layout-nodes.js";
 import { applyDeclaredProps } from "./compose-reusable-components.js";
+import { applyLayoutStyleOverrides, layoutStyleOverridesFor } from "./layout-style-overrides.js";
 /**
  * Screen-version key holding the screen's values for the layouts it renders
  * inside, beside the `layoutId` binding. Persisted in screen version documents
@@ -48,13 +49,17 @@ import { applyDeclaredProps } from "./compose-reusable-components.js";
 /**
  * A screen grafted through its whole layout chain, innermost first, with each
  * layout's properties applied from the screen's values for that layout
- * (`layoutPropValues`, keyed by layout id).
+ * (`layoutPropValues`, keyed by layout id), and then the screen's per-page
+ * restyling of that layout's elements (`layoutStyleOverrides`, AGL-3286) —
+ * after the properties, so a page's style wins over whatever a property
+ * bound, and before the graft, so an element the layout hides for this page
+ * is simply not there to be styled.
  *
  * The one composition the published page, the besigner's Preview and its
  * layout chrome all run, so none of them can disagree about which value a
  * layout renders with.
- */ export function composeLayoutChainWithProps(chain, screenNodes, layoutPropValues) {
-    return composeLayoutChainAndScreenNodes(chain.map((entry)=>applyLayoutProps(entry == null ? void 0 : entry.nodes, entry == null ? void 0 : entry.props, layoutPropValuesFor(layoutPropValues, entry == null ? void 0 : entry.layoutId))), screenNodes);
+ */ export function composeLayoutChainWithProps(chain, screenNodes, layoutPropValues, layoutStyleOverrides) {
+    return composeLayoutChainAndScreenNodes(chain.map((entry)=>applyLayoutStyleOverrides(applyLayoutProps(entry == null ? void 0 : entry.nodes, entry == null ? void 0 : entry.props, layoutPropValuesFor(layoutPropValues, entry == null ? void 0 : entry.layoutId)), layoutStyleOverridesFor(layoutStyleOverrides, entry == null ? void 0 : entry.layoutId))), screenNodes);
 }
 export default composeLayoutChainWithProps;
 

package/src/lib/app-utils/compose-layout-props.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/compose-layout-props.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 {\n  AglynNodeSchema,\n  NodeId,\n  ReusableComponentProp,\n} from '../foundation'\nimport { NODE_ROOT_ID } from '../canvas-manager/canvas-manager'\nimport { composeLayoutChainAndScreenNodes } from './compose-layout-nodes'\nimport { applyDeclaredProps } from './compose-reusable-components'\n\n/**\n * Layout properties (AGL-2893): a shared layout declares properties exactly as\n * a reusable component does, binds its own nodes to them with `{{prop.*}}`,\n * and each screen rendering inside it sets the values.\n *\n * The values are applied to each layout's OWN nodes before the screen is\n * grafted into its slot, so a `{{prop.*}}` the screen's own copy happens to\n * contain is never touched, and a component the layout places receives the\n * values it is handed before it is grafted.\n */\n\ntype NormalizedNodes<N extends AglynNodeSchema> = Record<NodeId, N>\n\n/**\n * Screen-version key holding the screen's values for the layouts it renders\n * inside, beside the `layoutId` binding. Persisted in screen version documents\n * — never rename.\n */\nexport const SCREEN_LAYOUT_PROP_VALUES_KEY = 'layoutPropValues'\n\n/** One layout of a screen's chain, as composition reads it. */\nexport interface LayoutChainEntry<N extends AglynNodeSchema = AglynNodeSchema> {\n  /** The layout document's id, which a screen's values are keyed by. */\n  layoutId?: string | null\n  /** The published version's nodes. */\n  nodes?: NormalizedNodes<N> | null\n  /** The published version's declared properties. */\n  props?: ReusableComponentProp[] | null\n}\n\n/**\n * A screen's values for one layout of its chain, or `undefined` where it set\n * none. Anything that is not a map of values is read as none.\n */\nexport function layoutPropValuesFor(\n  layoutPropValues: unknown,\n  layoutId: string | null | undefined,\n): Record<string, unknown> | undefined {\n  if (!layoutId || !layoutPropValues || typeof layoutPropValues !== 'object') {\n    return undefined\n  }\n  const values = (layoutPropValues as Record<string, unknown>)[layoutId]\n  return values && typeof values === 'object' && !Array.isArray(values)\n    ? (values as Record<string, unknown>)\n    : undefined\n}\n\n/**\n * A layout's nodes with its declared properties applied for one screen: each\n * `{{prop.*}}` takes the screen's value or the property's default, a field\n * bound to one property receives the value its kind holds, and the parts the\n * screen hides (`hideIf` / `hideUnless`) are pruned — the sequence a reusable\n * component's graft runs, over the layout's root.\n *\n * A layout with no root is returned as it is, for the reason\n * `composeLayoutAndScreenNodes` gives: a broken layout degrades to the bare\n * screen rather than taking a page down.\n */\nexport function applyLayoutProps<N extends AglynNodeSchema = AglynNodeSchema>(\n  nodes: NormalizedNodes<N> | null | undefined,\n  props: ReusableComponentProp[] | null | undefined,\n  values: Readonly<Record<string, unknown>> | null | undefined,\n): NormalizedNodes<N> | undefined {\n  if (!nodes || !nodes[NODE_ROOT_ID]) return nodes ?? undefined\n  return applyDeclaredProps(nodes, props, values, NODE_ROOT_ID)\n}\n\n/**\n * A screen grafted through its whole layout chain, innermost first, with each\n * layout's properties applied from the screen's values for that layout\n * (`layoutPropValues`, keyed by layout id).\n *\n * The one composition the published page, the besigner's Preview and its\n * layout chrome all run, so none of them can disagree about which value a\n * layout renders with.\n */\nexport function composeLayoutChainWithProps<\n  N extends AglynNodeSchema = AglynNodeSchema,\n>(\n  chain: ReadonlyArray<LayoutChainEntry<N> | null | undefined>,\n  screenNodes: NormalizedNodes<N>,\n  layoutPropValues?: unknown,\n): NormalizedNodes<N> {\n  return composeLayoutChainAndScreenNodes(\n    chain.map((entry) =>\n      applyLayoutProps(\n        entry?.nodes,\n        entry?.props,\n        layoutPropValuesFor(layoutPropValues, entry?.layoutId),\n      ),\n    ),\n    screenNodes,\n  )\n}\n\nexport default composeLayoutChainWithProps\n"],"names":["NODE_ROOT_ID","composeLayoutChainAndScreenNodes","applyDeclaredProps","SCREEN_LAYOUT_PROP_VALUES_KEY","layoutPropValuesFor","layoutPropValues","layoutId","undefined","values","Array","isArray","applyLayoutProps","nodes","props","composeLayoutChainWithProps","chain","screenNodes","map","entry"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAOD,SAASA,YAAY,QAAQ,sCAAkC;AAC/D,SAASC,gCAAgC,QAAQ,4BAAwB;AACzE,SAASC,kBAAkB,QAAQ,mCAA+B;AAelE;;;;CAIC,GACD,OAAO,MAAMC,gCAAgC,mBAAkB;AAY/D;;;CAGC,GACD,OAAO,SAASC,oBACdC,gBAAyB,EACzBC,QAAmC;IAEnC,IAAI,CAACA,YAAY,CAACD,oBAAoB,OAAOA,qBAAqB,UAAU;QAC1E,OAAOE;IACT;IACA,MAAMC,SAAS,AAACH,gBAA4C,CAACC,SAAS;IACtE,OAAOE,UAAU,OAAOA,WAAW,YAAY,CAACC,MAAMC,OAAO,CAACF,UACzDA,SACDD;AACN;AAEA;;;;;;;;;;CAUC,GACD,OAAO,SAASI,iBACdC,KAA4C,EAC5CC,KAAiD,EACjDL,MAA4D;IAE5D,IAAI,CAACI,SAAS,CAACA,KAAK,CAACZ,aAAa,EAAE,OAAOY,gBAAAA,QAASL;IACpD,OAAOL,mBAAmBU,OAAOC,OAAOL,QAAQR;AAClD;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASc,4BAGdC,KAA4D,EAC5DC,WAA+B,EAC/BX,gBAA0B;IAE1B,OAAOJ,iCACLc,MAAME,GAAG,CAAC,CAACC,QACTP,iBACEO,yBAAAA,MAAON,KAAK,EACZM,yBAAAA,MAAOL,KAAK,EACZT,oBAAoBC,kBAAkBa,yBAAAA,MAAOZ,QAAQ,KAGzDU;AAEJ;AAEA,eAAeF,4BAA2B"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/compose-layout-props.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 {\n  AglynNodeSchema,\n  NodeId,\n  ReusableComponentProp,\n} from '../foundation'\nimport { NODE_ROOT_ID } from '../canvas-manager/canvas-manager'\nimport { composeLayoutChainAndScreenNodes } from './compose-layout-nodes'\nimport { applyDeclaredProps } from './compose-reusable-components'\nimport {\n  applyLayoutStyleOverrides,\n  layoutStyleOverridesFor,\n} from './layout-style-overrides'\n\n/**\n * Layout properties (AGL-2893): a shared layout declares properties exactly as\n * a reusable component does, binds its own nodes to them with `{{prop.*}}`,\n * and each screen rendering inside it sets the values.\n *\n * The values are applied to each layout's OWN nodes before the screen is\n * grafted into its slot, so a `{{prop.*}}` the screen's own copy happens to\n * contain is never touched, and a component the layout places receives the\n * values it is handed before it is grafted.\n */\n\ntype NormalizedNodes<N extends AglynNodeSchema> = Record<NodeId, N>\n\n/**\n * Screen-version key holding the screen's values for the layouts it renders\n * inside, beside the `layoutId` binding. Persisted in screen version documents\n * — never rename.\n */\nexport const SCREEN_LAYOUT_PROP_VALUES_KEY = 'layoutPropValues'\n\n/** One layout of a screen's chain, as composition reads it. */\nexport interface LayoutChainEntry<N extends AglynNodeSchema = AglynNodeSchema> {\n  /** The layout document's id, which a screen's values are keyed by. */\n  layoutId?: string | null\n  /** The published version's nodes. */\n  nodes?: NormalizedNodes<N> | null\n  /** The published version's declared properties. */\n  props?: ReusableComponentProp[] | null\n}\n\n/**\n * A screen's values for one layout of its chain, or `undefined` where it set\n * none. Anything that is not a map of values is read as none.\n */\nexport function layoutPropValuesFor(\n  layoutPropValues: unknown,\n  layoutId: string | null | undefined,\n): Record<string, unknown> | undefined {\n  if (!layoutId || !layoutPropValues || typeof layoutPropValues !== 'object') {\n    return undefined\n  }\n  const values = (layoutPropValues as Record<string, unknown>)[layoutId]\n  return values && typeof values === 'object' && !Array.isArray(values)\n    ? (values as Record<string, unknown>)\n    : undefined\n}\n\n/**\n * A layout's nodes with its declared properties applied for one screen: each\n * `{{prop.*}}` takes the screen's value or the property's default, a field\n * bound to one property receives the value its kind holds, and the parts the\n * screen hides (`hideIf` / `hideUnless`) are pruned — the sequence a reusable\n * component's graft runs, over the layout's root.\n *\n * A layout with no root is returned as it is, for the reason\n * `composeLayoutAndScreenNodes` gives: a broken layout degrades to the bare\n * screen rather than taking a page down.\n */\nexport function applyLayoutProps<N extends AglynNodeSchema = AglynNodeSchema>(\n  nodes: NormalizedNodes<N> | null | undefined,\n  props: ReusableComponentProp[] | null | undefined,\n  values: Readonly<Record<string, unknown>> | null | undefined,\n): NormalizedNodes<N> | undefined {\n  if (!nodes || !nodes[NODE_ROOT_ID]) return nodes ?? undefined\n  return applyDeclaredProps(nodes, props, values, NODE_ROOT_ID)\n}\n\n/**\n * A screen grafted through its whole layout chain, innermost first, with each\n * layout's properties applied from the screen's values for that layout\n * (`layoutPropValues`, keyed by layout id), and then the screen's per-page\n * restyling of that layout's elements (`layoutStyleOverrides`, AGL-3286) —\n * after the properties, so a page's style wins over whatever a property\n * bound, and before the graft, so an element the layout hides for this page\n * is simply not there to be styled.\n *\n * The one composition the published page, the besigner's Preview and its\n * layout chrome all run, so none of them can disagree about which value a\n * layout renders with.\n */\nexport function composeLayoutChainWithProps<\n  N extends AglynNodeSchema = AglynNodeSchema,\n>(\n  chain: ReadonlyArray<LayoutChainEntry<N> | null | undefined>,\n  screenNodes: NormalizedNodes<N>,\n  layoutPropValues?: unknown,\n  layoutStyleOverrides?: unknown,\n): NormalizedNodes<N> {\n  return composeLayoutChainAndScreenNodes(\n    chain.map((entry) =>\n      applyLayoutStyleOverrides(\n        applyLayoutProps(\n          entry?.nodes,\n          entry?.props,\n          layoutPropValuesFor(layoutPropValues, entry?.layoutId),\n        ),\n        layoutStyleOverridesFor(layoutStyleOverrides, entry?.layoutId),\n      ),\n    ),\n    screenNodes,\n  )\n}\n\nexport default composeLayoutChainWithProps\n"],"names":["NODE_ROOT_ID","composeLayoutChainAndScreenNodes","applyDeclaredProps","applyLayoutStyleOverrides","layoutStyleOverridesFor","SCREEN_LAYOUT_PROP_VALUES_KEY","layoutPropValuesFor","layoutPropValues","layoutId","undefined","values","Array","isArray","applyLayoutProps","nodes","props","composeLayoutChainWithProps","chain","screenNodes","layoutStyleOverrides","map","entry"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAOD,SAASA,YAAY,QAAQ,sCAAkC;AAC/D,SAASC,gCAAgC,QAAQ,4BAAwB;AACzE,SAASC,kBAAkB,QAAQ,mCAA+B;AAClE,SACEC,yBAAyB,EACzBC,uBAAuB,QAClB,8BAA0B;AAejC;;;;CAIC,GACD,OAAO,MAAMC,gCAAgC,mBAAkB;AAY/D;;;CAGC,GACD,OAAO,SAASC,oBACdC,gBAAyB,EACzBC,QAAmC;IAEnC,IAAI,CAACA,YAAY,CAACD,oBAAoB,OAAOA,qBAAqB,UAAU;QAC1E,OAAOE;IACT;IACA,MAAMC,SAAS,AAACH,gBAA4C,CAACC,SAAS;IACtE,OAAOE,UAAU,OAAOA,WAAW,YAAY,CAACC,MAAMC,OAAO,CAACF,UACzDA,SACDD;AACN;AAEA;;;;;;;;;;CAUC,GACD,OAAO,SAASI,iBACdC,KAA4C,EAC5CC,KAAiD,EACjDL,MAA4D;IAE5D,IAAI,CAACI,SAAS,CAACA,KAAK,CAACd,aAAa,EAAE,OAAOc,gBAAAA,QAASL;IACpD,OAAOP,mBAAmBY,OAAOC,OAAOL,QAAQV;AAClD;AAEA;;;;;;;;;;;;CAYC,GACD,OAAO,SAASgB,4BAGdC,KAA4D,EAC5DC,WAA+B,EAC/BX,gBAA0B,EAC1BY,oBAA8B;IAE9B,OAAOlB,iCACLgB,MAAMG,GAAG,CAAC,CAACC,QACTlB,0BACEU,iBACEQ,yBAAAA,MAAOP,KAAK,EACZO,yBAAAA,MAAON,KAAK,EACZT,oBAAoBC,kBAAkBc,yBAAAA,MAAOb,QAAQ,IAEvDJ,wBAAwBe,sBAAsBE,yBAAAA,MAAOb,QAAQ,KAGjEU;AAEJ;AAEA,eAAeF,4BAA2B"}

package/src/lib/app-utils/compose-reusable-components.d.ts

@@ -17,11 +17,53 @@
 import type { AglynNodeSchema, NodeId, ReusableComponentIcon, ReusableComponentProp } from '../foundation';
 export * from './reusable-component-keys';
 export * from './reusable-prop-values';
+/**
+ * Whether a node is a placed form that names a form entity — the second kind
+ * of node that stands for a tree stored on another document (see
+ * {@link PlacementKind}). A `form` node with no `formId` is an ordinary form
+ * whose fields are its own children, and has no override layer.
+ *
+ * The ref test matches the graft's own resolution rule (a non-empty string),
+ * so the editor and the renderer agree about which forms are placements.
+ */
+export declare function isPlacedFormNode(node: {
+    componentId?: string;
+    props?: unknown;
+} | undefined | null): boolean;
+/**
+ * Whether a node is a placement that GRAFTS a definition — a reusable
+ * component instance or a placed form — and therefore carries the two
+ * per-placement override layers (`styleOverrides`, `attrOverrides`, AGL-3285).
+ *
+ * One predicate for both kinds on purpose: the graft already expands them in
+ * one pass, and an override layer that one kind honoured and the other
+ * silently ignored would be the canvas/Preview/tenant disagreement this file
+ * exists to prevent.
+ */
+export declare function isDefinitionPlacement(node: {
+    componentId?: string;
+    props?: unknown;
+} | undefined | null): boolean;
+/**
+ * The tree a placement grafts, from whichever map its kind reads — the
+ * component definitions for an instance, the published form designs for a
+ * placed form — or `undefined` when it is not a placement or its ref resolves
+ * to nothing (AGL-3285). The editor panels use it to offer the same targets
+ * the graft will consult.
+ */
+export declare function placementDefinitionFor<N extends AglynNodeSchema = AglynNodeSchema>(node: {
+    componentId?: string;
+    props?: unknown;
+} | undefined | null, sources: {
+    definitions?: Record<string, ReusableComponentTree<N> | undefined>;
+    formDesigns?: Record<string, Pick<ReusableComponentTree<N>, 'rootId' | 'nodes'> | undefined>;
+}): Pick<ReusableComponentTree<N>, 'rootId' | 'nodes'> | undefined;
 /**
  * Every per-instance style override an instance node carries, keyed the way
  * it is stored (AGL-1332): {@link STYLE_OVERRIDES_ROOT_KEY} for the
  * component root, and a DEFINITION-internal node id for each overridden
- * leaf. Empty for a node that is not an instance or carries none.
+ * leaf. Empty for a node that is not a placement ({@link
+ * isDefinitionPlacement}: an instance or a placed form) or carries none.
  *
  * Keyed on the definition's own id, never the grafted `cmp__…` id: the
  * graft id is DERIVED from the instance id, so keying on it would break the
@@ -39,6 +81,7 @@ export * from './reusable-prop-values';
  */
 export declare function getInstanceStyleOverrides(node: {
     componentId?: string;
+    props?: unknown;
     styleOverrides?: unknown;
 } | undefined | null): Record<string, Record<string, unknown>>;
 /**
@@ -48,8 +91,48 @@ export declare function getInstanceStyleOverrides(node: {
  */
 export declare function getInstanceRootStyleOverride(node: {
     componentId?: string;
+    props?: unknown;
     styleOverrides?: unknown;
 } | undefined | null): Record<string, unknown> | undefined;
+/**
+ * Props a placed form's attribute overrides must never address, on any node
+ * of its design (AGL-3285).
+ *
+ * A form is edited once and every page placing it follows — that is the
+ * whole point of the form entity. Its submission list, its dataset columns,
+ * its consent tick and its routing are all keyed to what the ENTITY declares,
+ * so a page that renamed a field, retyped it, made it optional, rewrote its
+ * choices or re-pointed where the form sends would file answers the form's
+ * own schema does not describe, from one page only, with nothing on the
+ * Forms page saying so. Per page, a form may LOOK different; it may not
+ * collect something different.
+ *
+ * - The form node's identity and submission config: `formId`, `formName`,
+ *   `datasetId`, `datasetName`, and the after-submit outcome
+ *   (`afterSubmit`, `redirectScreenId`, `redirectUrl`, `revealNodeId`).
+ * - Each field's contract: `fieldName` (the submission key),
+ *   `datasetFieldId`, `fieldType`, `options` (a ticked option's TEXT is the
+ *   posted value, and the consent check reads it) and `required`.
+ * - Element attributes a browser submission reads directly: `name`, `type`
+ *   (a submit button made a plain button no longer submits), `value`,
+ *   `action`, `method`, and `disabled` (a disabled input is not posted).
+ * - The hide directives: a hidden field is pruned from the page, so its
+ *   value is never sent.
+ *
+ * Label, placeholder, help text, the submit label and success message, and
+ * everything about styling stay overridable.
+ */
+export declare const PLACED_FORM_REFUSED_ATTR_PROPS: ReadonlySet<string>;
+/**
+ * Whether `prop` may never be an attribute override on this placement — `sx`
+ * on every placement, plus {@link PLACED_FORM_REFUSED_ATTR_PROPS} on a placed
+ * form. The render layer and the editor's writer both ask this, so a refused
+ * prop can neither be offered nor take effect.
+ */
+export declare function isAttrOverrideRefused(placement: {
+    componentId?: string;
+    props?: unknown;
+} | undefined | null, prop: string): boolean;
 /**
  * Every per-instance ATTRIBUTE override an instance node carries, keyed the
  * way {@link getInstanceStyleOverrides} keys styles — `root` for the
@@ -62,6 +145,7 @@ export declare function getInstanceRootStyleOverride(node: {
  */
 export declare function getInstanceAttrOverrides(node: {
     componentId?: string;
+    props?: unknown;
     attrOverrides?: unknown;
 } | undefined | null): Record<string, Record<string, unknown>>;
 /** One styleable target inside an instance — see {@link listInstanceStyleTargets}. */

package/src/lib/app-utils/compose-reusable-components.js

@@ -20,6 +20,7 @@ import { iconPathPropName } from "@aglyn/shared-data-mdi/utils/icon-path-prop-na
 import { reusablePropValueClass } from "../foundation/definitions/property-kinds.js";
 import { COMPONENT_NODE_ID_PREFIX, COMPONENT_PROP_TOKEN_PREFIX, INSTANCE_CARRIED_NODE_FIELDS, INSTANCE_CARRIED_PROPS, NODE_HIDE_IF_PROP, NODE_HIDE_UNLESS_PROP, REUSABLE_INSTANCE_COMPONENT_ID, REUSABLE_INSTANCE_PROP_VALUES_KEY, STYLE_OVERRIDES_ROOT_KEY } from "./reusable-component-keys.js";
 import { REPEAT_DIRECTIVE_PROPS, REPEAT_SELF_PROP, repeatKey, withoutRepeatDirective } from "./expand-repeatables.js";
+import { FORM_COMPONENT_ID, FORM_ID_PROP } from "./forms.js";
 import { mergeNodeSx } from "./merge-node-sx.js";
 import { hasUrlScheme, isSafeNodeUrl, NODE_URL_PROPS } from "./node-url-policy.js";
 import { readInstanceIconValue, readYesNoValue, resolveReusablePropValues } from "./reusable-prop-values.js";
@@ -36,11 +37,60 @@ const isStyleRecord = (value)=>typeof value === 'object' && value !== null && !A
         ...new Set(names)
     ].join(' ') : undefined;
 }
+/**
+ * Whether a node is a placed form that names a form entity — the second kind
+ * of node that stands for a tree stored on another document (see
+ * {@link PlacementKind}). A `form` node with no `formId` is an ordinary form
+ * whose fields are its own children, and has no override layer.
+ *
+ * The ref test matches the graft's own resolution rule (a non-empty string),
+ * so the editor and the renderer agree about which forms are placements.
+ */ export function isPlacedFormNode(node) {
+    var _node_props;
+    if ((node == null ? void 0 : node.componentId) !== FORM_COMPONENT_ID) return false;
+    const formId = (_node_props = node.props) == null ? void 0 : _node_props[FORM_ID_PROP];
+    return typeof formId === 'string' && formId !== '';
+}
+/**
+ * Whether a node is a placement that GRAFTS a definition — a reusable
+ * component instance or a placed form — and therefore carries the two
+ * per-placement override layers (`styleOverrides`, `attrOverrides`, AGL-3285).
+ *
+ * One predicate for both kinds on purpose: the graft already expands them in
+ * one pass, and an override layer that one kind honoured and the other
+ * silently ignored would be the canvas/Preview/tenant disagreement this file
+ * exists to prevent.
+ */ export function isDefinitionPlacement(node) {
+    return (node == null ? void 0 : node.componentId) === REUSABLE_INSTANCE_COMPONENT_ID || isPlacedFormNode(node);
+}
+/**
+ * The tree a placement grafts, from whichever map its kind reads — the
+ * component definitions for an instance, the published form designs for a
+ * placed form — or `undefined` when it is not a placement or its ref resolves
+ * to nothing (AGL-3285). The editor panels use it to offer the same targets
+ * the graft will consult.
+ */ export function placementDefinitionFor(node, sources) {
+    const props = node == null ? void 0 : node.props;
+    if ((node == null ? void 0 : node.componentId) === REUSABLE_INSTANCE_COMPONENT_ID) {
+        var _sources_definitions;
+        const refId = props == null ? void 0 : props['refId'];
+        return typeof refId === 'string' && refId ? (_sources_definitions = sources.definitions) == null ? void 0 : _sources_definitions[refId] : undefined;
+    }
+    if (isPlacedFormNode(node)) {
+        var _sources_formDesigns, _design_nodes;
+        const design = (_sources_formDesigns = sources.formDesigns) == null ? void 0 : _sources_formDesigns[props == null ? void 0 : props[FORM_ID_PROP]];
+        // The graft's resolution rule: a design whose root is not among its own
+        // nodes grafts nothing, so it offers nothing to override either.
+        return (design == null ? void 0 : design.rootId) && ((_design_nodes = design.nodes) == null ? void 0 : _design_nodes[design.rootId]) ? design : undefined;
+    }
+    return undefined;
+}
 /**
  * Every per-instance style override an instance node carries, keyed the way
  * it is stored (AGL-1332): {@link STYLE_OVERRIDES_ROOT_KEY} for the
  * component root, and a DEFINITION-internal node id for each overridden
- * leaf. Empty for a node that is not an instance or carries none.
+ * leaf. Empty for a node that is not a placement ({@link
+ * isDefinitionPlacement}: an instance or a placed form) or carries none.
  *
  * Keyed on the definition's own id, never the grafted `cmp__…` id: the
  * graft id is DERIVED from the instance id, so keying on it would break the
@@ -56,7 +106,7 @@ const isStyleRecord = (value)=>typeof value === 'object' && value !== null && !A
  * {@link composeReusableComponentNodes}, so they cannot disagree about
  * what an override means.
  */ export function getInstanceStyleOverrides(node) {
-    if ((node == null ? void 0 : node.componentId) !== REUSABLE_INSTANCE_COMPONENT_ID) return {};
+    if (!isDefinitionPlacement(node)) return {};
     const overrides = node == null ? void 0 : node.styleOverrides;
     if (!isStyleRecord(overrides)) return {};
     const clean = {};
@@ -117,6 +167,65 @@ const isStyleRecord = (value)=>typeof value === 'object' && value !== null && !A
  */ const ATTR_OVERRIDE_REFUSED_PROPS = new Set([
     'sx'
 ]);
+/**
+ * Props a placed form's attribute overrides must never address, on any node
+ * of its design (AGL-3285).
+ *
+ * A form is edited once and every page placing it follows — that is the
+ * whole point of the form entity. Its submission list, its dataset columns,
+ * its consent tick and its routing are all keyed to what the ENTITY declares,
+ * so a page that renamed a field, retyped it, made it optional, rewrote its
+ * choices or re-pointed where the form sends would file answers the form's
+ * own schema does not describe, from one page only, with nothing on the
+ * Forms page saying so. Per page, a form may LOOK different; it may not
+ * collect something different.
+ *
+ * - The form node's identity and submission config: `formId`, `formName`,
+ *   `datasetId`, `datasetName`, and the after-submit outcome
+ *   (`afterSubmit`, `redirectScreenId`, `redirectUrl`, `revealNodeId`).
+ * - Each field's contract: `fieldName` (the submission key),
+ *   `datasetFieldId`, `fieldType`, `options` (a ticked option's TEXT is the
+ *   posted value, and the consent check reads it) and `required`.
+ * - Element attributes a browser submission reads directly: `name`, `type`
+ *   (a submit button made a plain button no longer submits), `value`,
+ *   `action`, `method`, and `disabled` (a disabled input is not posted).
+ * - The hide directives: a hidden field is pruned from the page, so its
+ *   value is never sent.
+ *
+ * Label, placeholder, help text, the submit label and success message, and
+ * everything about styling stay overridable.
+ */ export const PLACED_FORM_REFUSED_ATTR_PROPS = new Set([
+    FORM_ID_PROP,
+    'formName',
+    'datasetId',
+    'datasetName',
+    'afterSubmit',
+    'redirectScreenId',
+    'redirectUrl',
+    'revealNodeId',
+    'fieldName',
+    'datasetFieldId',
+    'fieldType',
+    'options',
+    'required',
+    'name',
+    'type',
+    'value',
+    'action',
+    'method',
+    'disabled',
+    NODE_HIDE_IF_PROP,
+    NODE_HIDE_UNLESS_PROP
+]);
+/**
+ * Whether `prop` may never be an attribute override on this placement — `sx`
+ * on every placement, plus {@link PLACED_FORM_REFUSED_ATTR_PROPS} on a placed
+ * form. The render layer and the editor's writer both ask this, so a refused
+ * prop can neither be offered nor take effect.
+ */ export function isAttrOverrideRefused(placement, prop) {
+    if (ATTR_OVERRIDE_REFUSED_PROPS.has(prop)) return true;
+    return isPlacedFormNode(placement) && PLACED_FORM_REFUSED_ATTR_PROPS.has(prop);
+}
 /**
  * Every per-instance ATTRIBUTE override an instance node carries, keyed the
  * way {@link getInstanceStyleOverrides} keys styles — `root` for the
@@ -127,7 +236,7 @@ const isStyleRecord = (value)=>typeof value === 'object' && value !== null && !A
  * that reached storage before a refusal existed (or by any path that did not
  * go through the panel) still cannot take effect.
  */ export function getInstanceAttrOverrides(node) {
-    if ((node == null ? void 0 : node.componentId) !== REUSABLE_INSTANCE_COMPONENT_ID) return {};
+    if (!isDefinitionPlacement(node)) return {};
     const overrides = node == null ? void 0 : node.attrOverrides;
     if (!isStyleRecord(overrides)) return {};
     const clean = {};
@@ -135,7 +244,7 @@ const isStyleRecord = (value)=>typeof value === 'object' && value !== null && !A
         if (!key || !isStyleRecord(value)) continue;
         const slice = {};
         for (const [prop, propValue] of Object.entries(value)){
-            if (ATTR_OVERRIDE_REFUSED_PROPS.has(prop)) continue;
+            if (isAttrOverrideRefused(node, prop)) continue;
             slice[prop] = propValue;
         }
         if (Object.keys(slice).length > 0) clean[key] = slice;
@@ -850,6 +959,9 @@ function hasVisibilityDirective(props) {
             // Per-leaf is not a nicety: a component's text leaves usually set
             // their OWN colour, so a root-level `color` never reaches them and an
             // instance given a white background renders white-on-white (AGL-1318).
+            //
+            // A placed form carries the same two layers (AGL-3285), so one page can
+            // restyle a field's label without editing the form for every page.
             const styleOverrides = getInstanceStyleOverrides(instanceNode);
             // Attribute overrides (AGL-1899) ride the same graft for the same
             // reason: this is the one point where per-instance scope exists, so
@@ -909,6 +1021,7 @@ function hasVisibilityDirective(props) {
             const rootNamesItself = Boolean(grafting) && refIdOf(definitionRoot) === grafting;
             const graftedRoot = next[graftedRootId];
             if (rootNamesItself && graftedRoot) {
+                var _instanceNode_props;
                 const adopted = Array.isArray(graftedRoot.nodes) ? graftedRoot.nodes : [];
                 for (const childId of adopted){
                     if (next[childId]) {
@@ -918,11 +1031,24 @@ function hasVisibilityDirective(props) {
                     }
                 }
                 delete next[graftedRootId];
-                next[instanceId] = _extends({}, instanceNode, {
+                /*
+         * The root's own override slices land on the instance, because the
+         * instance IS the root here (AGL-3285). The grafted root carried them
+         * and has just been dropped; without this a placed form's `root`
+         * target would save and never render. Same precedence as the merge
+         * branch below: the slice first, the placement's own `sx` over it.
+         */ const rootSx = styleOverrides[STYLE_OVERRIDES_ROOT_KEY];
+                const rootAttrs = attrOverrides[STYLE_OVERRIDES_ROOT_KEY];
+                const unwrappedSx = rootSx ? mergeNodeSx(rootSx, instanceNode.sx) : undefined;
+                next[instanceId] = _extends({}, instanceNode, unwrappedSx === undefined ? {} : {
+                    sx: unwrappedSx
+                }, rootAttrs ? {
+                    props: _extends({}, (_instanceNode_props = instanceNode.props) != null ? _instanceNode_props : {}, rootAttrs)
+                } : {}, {
                     nodes: adopted
                 });
             } else if (graftedRoot) {
-                var _graftedRoot_props, _instanceNode_props;
+                var _graftedRoot_props, _instanceNode_props1;
                 /*
          * THE INSTANCE AND THE DEFINITION'S ROOT ARE ONE ELEMENT (AGL-2521).
          *
@@ -979,8 +1105,8 @@ function hasVisibilityDirective(props) {
                 ];
                 const carried = {};
                 for (const key of INSTANCE_CARRIED_PROPS){
-                    var _instanceNode_props1;
-                    const value = (_instanceNode_props1 = instanceNode.props) == null ? void 0 : _instanceNode_props1[key];
+                    var _instanceNode_props2;
+                    const value = (_instanceNode_props2 = instanceNode.props) == null ? void 0 : _instanceNode_props2[key];
                     if (value !== undefined) carried[key] = value;
                 }
                 /*
@@ -998,8 +1124,8 @@ function hasVisibilityDirective(props) {
          */ const repeatsPlacement = repeatKey(instanceNode) !== '';
                 if (repeatsPlacement) {
                     for (const key of REPEAT_DIRECTIVE_PROPS){
-                        var _instanceNode_props2;
-                        const value = (_instanceNode_props2 = instanceNode.props) == null ? void 0 : _instanceNode_props2[key];
+                        var _instanceNode_props3;
+                        const value = (_instanceNode_props3 = instanceNode.props) == null ? void 0 : _instanceNode_props3[key];
                         if (value !== undefined) carried[key] = value;
                     }
                     carried[REPEAT_SELF_PROP] = true;
@@ -1014,7 +1140,7 @@ function hasVisibilityDirective(props) {
          * element answering to the placement's id, which after the merge is
          * this one. Keeping either list alone drops the other author's names,
          * so the two are joined, each name once, in `props` and on the node.
-         */ const propsClassName = joinClassNames((_graftedRoot_props = graftedRoot.props) == null ? void 0 : _graftedRoot_props['className'], (_instanceNode_props = instanceNode.props) == null ? void 0 : _instanceNode_props['className']);
+         */ const propsClassName = joinClassNames((_graftedRoot_props = graftedRoot.props) == null ? void 0 : _graftedRoot_props['className'], (_instanceNode_props1 = instanceNode.props) == null ? void 0 : _instanceNode_props1['className']);
                 if (propsClassName) carried['className'] = propsClassName;
                 const nodeClassName = joinClassNames(graftedRoot.className, instanceNode.className);
                 // The override slices and the reference are DOCUMENT state living on