@aglyn/aglyn 1.0.0-beta.217 → 1.0.0-beta.219

package/src/lib/types/nodes.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/types/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 type {\n  ConditionDefinition,\n  DataType,\n  Validator,\n} from '@data-driven-forms/react-form-renderer'\nimport type {\n  FieldActions,\n  ResolvePropsFunction,\n} from '@data-driven-forms/react-form-renderer/common-types'\nimport type { MuiStyledOptions } from '@mui/system/createStyled'\nimport type { SvgIconProps } from '@mui/material/SvgIcon'\n/** Minimal icon-props type used in component/preset schemas. Structurally compatible with @aglyn/shared-ui-jsx MdiIconProps. */\nexport type MdiIconProps<D extends React.ElementType = 'svg', P = object> = SvgIconProps<D, P> & {\n  path?: string\n}\nimport type {\n  ComponentId,\n  ComponentsLinealOrder,\n  NodeId,\n  PresetId,\n} from '../foundation'\nimport { ComponentCategory } from '../foundation/constants/components'\nimport type { ITimestamp } from '@aglyn/shared-util-timestamp'\nimport type React from 'react'\nimport type { ComponentClass, ComponentProps } from 'react'\nimport type { NODE_ROOT_ID } from '../canvas-manager'\nimport type { NodeInteraction } from '../app-utils/node-interactions'\n\nimport type {\n  FEATURE_FLAG,\n  FieldComponentType,\n  RICH_TEXT_COMMANDS,\n} from '../foundation'\nimport type { PluginId } from '../plugin-manager'\nimport type { ElementContentMap, Node, Props, Taxonomic } from './ast'\nimport type { AglynDocument } from '../foundation'\nimport type { HostUid } from '../foundation'\n\ndeclare module './ast' {\n  /**\n   * This map registers all node types that may be used as top-level content in\n   * the document.\n   *\n   * These types are accepted inside `root` nodes.\n   *\n   * This interface can be augmented to register custom node types.\n   *\n   * @example\n   * declare module 'hast' {\n   *   interface RootContentMap {\n   *     // Allow using raw nodes defined by `rehype-raw`.\n   *     raw: Raw;\n   *   }\n   * }\n   */\n  export interface RootContentMap {\n    canvasNode: CanvasNode\n    canvasElement: CanvasElement\n  }\n\n  /**\n   * This map registers all node types that may be used as content in an\n   * element.\n   *\n   * These types are accepted inside `element` nodes.\n   *\n   * This interface can be augmented to register custom node types.\n   *\n   * @example\n   * declare module 'hast' {\n   *   interface RootContentMap {\n   *     custom: Custom;\n   *   }\n   * }\n   */\n  export interface ElementContentMap {\n    canvasNode: CanvasNode\n    canvasElement: CanvasElement\n  }\n}\n\n/**\n * This map registers all node types that may be used as content in an canvas\n * node.\n *\n * These types are accepted inside `element` nodes.\n *\n * This interface can be augmented to register custom node types.\n *\n * @example\n * declare module 'hast' {\n *   interface RootContentMap {\n *     custom: Custom;\n *   }\n * }\n */\nexport interface CanvasNodeContentMap extends ElementContentMap {\n  canvasNode: CanvasNode\n  canvasElement: CanvasElement\n}\n\nexport type CanvasNodeContent = CanvasNodeContentMap[keyof CanvasNodeContentMap]\n\n/**\n * CanvasNode represents a the schema for building a JSX Element.\n */\nexport interface CanvasNode extends Node {\n  /**\n   * Represents this variant of a Node.\n   */\n  type: 'node'\n\n  /**\n   * List representing the children of a node.\n   */\n  children?: CanvasNodeContent[] | undefined\n\n  /**\n   * Represents the element's internal name defined by the user\n   */\n  name?: string | undefined\n\n  /**\n   * Represents the element's parent unique identifier\n   */\n  parentId?: string | undefined\n\n  /**\n   * Represents the elements' component unique identifier\n   */\n  componentId?: string | undefined\n\n  /**\n   * Represents the elements' components' plugin unique identifier\n   */\n  pluginId?: string | undefined\n\n  /**\n   * Represents information associated with the element.\n   */\n  props?: Props | undefined\n}\n\n/**\n * CanvasElement represents a living JSX Element\n */\nexport interface CanvasElement extends CanvasNode {\n  /**\n   * Represents the element's unique identifier\n   */\n  $id: string\n}\n\nexport type AbstractId = string\n\n// @TODO ⚠️ Refactor for better adoption of hast\nexport interface AbstractNodeSchema<P = JSX.AnyProps> extends CanvasNode {\n  /**\n   * The unique identifier for a node\n   */\n  $id: AbstractId\n  title?: string\n  displayName?: string\n  description?: string\n\n  children?: any\n  nodes?: any\n\n  /**\n   * The node style properties for emotion\n   */\n  sx?: JSX.SxProps\n  /**\n   * The node props/attributes passed to the component\n   */\n  props?: P\n\n  category?: any\n  icon?: any\n\n  createdAt?: ITimestamp\n  updatedAt?: ITimestamp\n  deletedAt?: ITimestamp\n}\n\n/**\n * CanvasPreset represents an encapsulated 'node' type as the root node for\n * crafting a living JSX Element\n */\nexport interface CanvasPreset extends Node, Taxonomic {\n  /**\n   * Represents this variant of a Node.\n   */\n  type: 'preset'\n\n  /**\n   * Represents the element's unique identifier\n   */\n  $id: string\n\n  /**\n   * Represents the elements' component unique identifier\n   */\n  componentId?: string | undefined\n\n  /**\n   * Represents the elements' components' plugin unique identifier\n   */\n  pluginId?: string | undefined\n\n  /**\n   * Represents information associated with the element.\n   */\n  props?: Props | undefined\n\n  /**\n   * Represents the element's internal name defined by the user\n   */\n  name?: string | undefined\n}\n\nexport type { NodeId }\n\n// @TODO ⚠️ Refactor for better adoption of hast\ntype PresetI = AglynDocument &\n  Omit<AbstractNodeSchema<any>, 'type' | 'data'> &\n  Omit<CanvasPreset, 'type' | 'data'>\n\ninterface PresetII extends PresetI {\n  type: NodeType.PRESET | string\n}\n\nexport interface PresetSchema<P = JSX.AnyProps> extends PresetII {\n  $id: PresetId\n  pluginId?: PluginId\n  displayName?: string\n  description?: string\n  category?: string | ComponentCategory\n  /**\n   * Extra words this element should be findable by in the element picker —\n   * synonyms and the name people reach for when it is not the name we chose\n   * (\"picture\" for Image, \"dropdown\" for Select).\n   *\n   * Search terms only; never rendered. A hit here ranks BELOW every hit on a\n   * name, so a tag widens what the picker finds without letting a synonym\n   * outrank the element actually called that (AGL-2486).\n   */\n  tags?: string[]\n  /** Alias of {@link tags}; both are searched. */\n  keywords?: string[]\n  icon?: MdiIconProps\n  data: NodeSchemaNested<P>\n  /**\n   * Interaction templates wired when the preset is inserted (AGL-589):\n   * the host app resolves each `presetRef` marker to a freshly minted node\n   * and persists the result. Presets that need hover choreography (a\n   * primitive dropdown panel) ship working out of the box instead of asking\n   * the user to author the interactions by hand.\n   *\n   * TEMPLATES, and named so. These are not interactions: they are\n   * unresolved, they reference nodes that do not exist yet, and they are\n   * consumed at insert time and never stored. What they resolve INTO lives\n   * on the node as {@link NodeSchema.interactions}, and a `PresetSchema` is\n   * assignable to a `NodeSchema` — so while the two shared a name, one of\n   * them had to be wrong wherever a preset was passed as a node.\n   */\n  interactionTemplates?: PresetInteractionSchema[]\n}\n\n/**\n * A visibility step inside a {@link PresetSchema} interaction template.\n * Only the basic client visibility steps are expressible — presets\n * scaffold in-page choreography, never server automations.\n */\nexport interface PresetInteractionStepSchema {\n  type: 'showElement' | 'hideElement' | 'toggleElement'\n  /** `presetRef` of the preset node this step targets. */\n  targetRef: string\n  /** Optional grace delay, validated to 0–5000ms like the builder. */\n  delayMs?: number\n  /** Self-dismissal for steps that can reveal the target. */\n  dismissOn?: Array<'escape' | 'outsideClick'>\n}\n\n/** An interaction template a preset wires on insert (AGL-589). */\nexport interface PresetInteractionSchema {\n  name: string\n  event: 'elementClick' | 'elementHoverEnter' | 'elementHoverLeave'\n  /** `presetRef` of the preset node whose selector fires the trigger. */\n  triggerRef: string\n  steps: PresetInteractionStepSchema[]\n}\n\n// @TODO ⚠️ Refactor for better adoption of hast\ntype NodeI<P> = AglynDocument & Omit<AbstractNodeSchema<P>, 'type'>\n\nexport interface NodeSchema<P = JSX.AnyProps> extends NodeI<P> {\n  type: NodeType | string\n  /**\n   * List of the children unique identifiers for the node\n   */\n  nodes?: NodeId[]\n  /**\n   * Class name to pass the DOM node, can also be defined in props\n   */\n  className?: string\n  /**\n   * Preset-authoring marker (AGL-589): names a node inside a preset's\n   * `data` tree so the preset's interaction templates can reference it\n   * (`triggerRef` / `targetRef`). Cloned onto the inserted node; inert\n   * everywhere else.\n   */\n  presetRef?: string\n  /**\n   * Per-instance style overrides on a reusable-component instance node\n   * (AGL-1306), keyed by target: `root` (see `STYLE_OVERRIDES_ROOT_KEY`)\n   * addresses the component ROOT, and any other key is a DEFINITION-internal\n   * node id addressing one leaf inside the component (AGL-1332). Each slice\n   * is an sx-shaped record merged over that node's own sx at graft time\n   * (`composeReusableComponentNodes` → `mergeNodeSx`), so one page's CTA can\n   * switch to a white background AND repaint its headline without widening\n   * the component's declared props or detaching.\n   *\n   * Keyed on the definition's id, never the grafted `cmp__{instance}__{def}`\n   * id: the graft id is derived per placement, so it would not survive a\n   * duplicate or a re-key, and the same component could not offer two\n   * instances the same authoring vocabulary. A key naming a node the\n   * definition no longer has is ignored — a component edited later degrades\n   * to its own styling instead of taking a page down.\n   *\n   * A first-class node field, NOT a prop: `AglynNode`'s constructor drops\n   * unknown top-level keys, and anything in `props` is spread onto the\n   * instance's wrapper DOM element. Lives on the instance node in the\n   * document that places it — it survives component republish and never\n   * pins the instance to an old component version, because the graft\n   * always merges it over the definition's CURRENT nodes.\n   */\n  styleOverrides?: Record<string, JSX.SxProps>\n  /**\n   * Per-instance ATTRIBUTE overrides on a reusable-component instance node\n   * (AGL-1899) — the same addressing as {@link styleOverrides}, applied to\n   * a node's props instead of its sx, so one placement can carry a\n   * different button `variant`, `size` or `href` without the component\n   * declaring a prop for it and without detaching.\n   *\n   * Merged **per named prop**: a slice replaces only the props it names and\n   * leaves the definition's others alone, so a component that later adds a\n   * prop still gives every existing instance the new default. That is\n   * deliberately shallower than the sx merge next door — an sx slice\n   * cascades because `@scheme dark` and breakpoint objects are themselves\n   * selectors, whereas a prop value is one value, and half-merging two\n   * objects that merely look alike (say a `slotProps`) would produce a\n   * third thing neither side asked for.\n   *\n   * `sx` is refused here. Styling an instance already has a mechanism one\n   * field up, and honouring both would leave two writers racing for one\n   * rendered value with no rule to say which wins.\n   *\n   * Applied BEFORE `{{prop.*}}` substitution, so an override may itself be\n   * written in tokens and still resolves, and an override on a prop the\n   * definition binds to a declared prop wins — the more specific placement\n   * beats the component's own default.\n   */\n  attrOverrides?: Record<string, Record<string, unknown>>\n  /**\n   * EDITOR-ONLY: a screen's per-page restyling of its layout's elements\n   * (AGL-3286), parked on the screen canvas ROOT while the besigner is open.\n   *\n   * Stored on the screen VERSION as `layoutStyleOverrides`, never in `nodes`:\n   * the editor injects it here on load and lifts it back out on save\n   * (`injectLayoutStyleOverrides` / `extractLayoutStyleOverrides`). Carried on\n   * the root so an edit is an undo step, marks the screen dirty and rides the\n   * working draft like any other change. Composition ignores it — the screen\n   * root is dropped when it is grafted into the layout's slot.\n   */\n  layoutStyleOverrides?: Record<string, Record<string, Record<string, unknown>>>\n  /**\n   * Interactions this element carries — the click, hover and\n   * scroll-into-view choreography authored on it in the besigner.\n   *\n   * ## Why they live on the NODE\n   *\n   * They used to be rows in `hosts/{hostId}/actions`, bound to an element by\n   * a `[data-aglyn=\"leaf:<id>\"]` selector — the same collection the Workflows\n   * page lists. An interaction is not a site-wide automation, and storing it\n   * as one had four consequences, every one of them a thing an author would\n   * expect to work:\n   *\n   * - it was not versioned with the document, so it neither published nor\n   *   rolled back with the screen it belongs to;\n   * - it did not travel with a component copied to another site, or packaged\n   *   into a template or a plugin — the element arrived inert;\n   * - deleting the element left the action behind, pointing at a selector\n   *   nothing resolves;\n   * - and a nav's hover choreography sat in the site's automation list\n   *   beside \"when an order is placed\", which is a different kind of thing.\n   *\n   * Host actions remain, and remain the right home for a genuine site event.\n   * The split is the concept: an ACTION is something the site does, an\n   * INTERACTION is something an element does.\n   *\n   * ## Shape\n   *\n   * Deliberately the same `HostAction` the automations engine already takes,\n   * so nothing about the runtime changes: the selector is stamped from this\n   * node's own id when the page is composed, and the compiled result is the\n   * shape the client engine has always consumed. `trigger.selector` is\n   * therefore ignored here — the node IS the selector.\n   */\n  interactions?: NodeInteraction[]\n  /**\n   * Hidden by the author — the eye on the element's hierarchy row.\n   *\n   * Renders `display: none` on the canvas AND on the published site. It is\n   * the plain \"I do not want this on the page\" switch: no runtime, no\n   * interaction, nothing reveals it. Showing it again is the same eye.\n   *\n   * ## Why a FIELD and not a style\n   *\n   * Because it has to override the element's own display rather than replace\n   * it. An author who toggles the eye on a Stack laid out with\n   * `display: flex` must get that flex back when they toggle it off, and\n   * writing `display: none` into `node.sx` destroys the value it overwrote —\n   * there is nothing left to restore. Composed LAST in `Leaf` instead, so it\n   * wins on the cascade and the stored style is never touched.\n   *\n   * ## Not {@link ELEMENT_HIDDEN_CLASS}\n   *\n   * `aglyn-hidden` is a different thing wearing a similar name: it means\n   * \"starts hidden, and an interaction shows it\" — a mega-menu panel, a\n   * drawer. That class is part of a runtime contract (the show/hide steps\n   * toggle it, and the canvas reveals it for designing), and it is bespoke to\n   * that job. A visibility toggle that wrote it would enrol every hidden\n   * element in a choreography it is not part of.\n   */\n  hidden?: boolean\n  /**\n   * The computed node parent (only for type completion)\n   */\n  readonly parent?: NodeSchema<any> | null\n  /**\n   * The computed node parent (only for type completion)\n   */\n  readonly children?: NodeSchema<any>[]\n  /**\n   * The computed index in parent nodes (only for type completion)\n   */\n  readonly index?: number | null\n  /**\n   * The computed label (only for type completion)\n   */\n  readonly labelShort?: string | undefined\n  /**\n   * The computed breadcrumb path (only for type completion)\n   */\n  readonly breadcrumbPath?: NodeBreadcrumbPath\n  /**\n   * The computed component schema (only for type completion)\n   */\n  readonly componentSchema?: ComponentSchema | undefined\n  /**\n   * The computed guard for of child nodes (only for type completion)\n   */\n  readonly hasNodes?: boolean\n  /**\n   * The computed property for the resolved props from component schema\n   */\n  readonly resolvedProps?: P\n}\n\nexport enum NodeType {\n  NODE = 'node',\n  TEXT = 'text',\n  NUMBER = 'number',\n  SCREEN = 'screen',\n  REF = 'ref',\n  PRESET = 'preset',\n}\n\nexport type NodeSchemaJSON<P = JSX.AnyProps> = Omit<\n  NodeSchema<P>,\n  | 'parent'\n  | 'index'\n  | 'labelShort'\n  | 'breadcrumbPath'\n  | 'componentSchema'\n  | 'hasNodes'\n>\n\nexport type NodeSchemaNested<P = JSX.AnyProps> = Omit<\n  NodeSchemaJSON<P>,\n  'nodes'\n> & { nodes?: NodeSchemaNested<any>[] }\n\nexport type NodesMap = Record<NodeId, NodeSchema<any>>\n\nexport type NodeBreadcrumbPath = [\n  root: string & typeof NODE_ROOT_ID,\n  ...nodes: [...ancestors: NodeId[], node: NodeId],\n]\n\nexport type ProcessableNodes =\n  | NodeSchemaNested<any>[]\n  | NodeSchemaNested<any>\n  | Record<NodeId, NodeSchema>\n\nexport { ComponentCategory }\n\nexport type { ComponentId }\nexport type { PresetId }\n\nexport type ComponentFactory<\n  P extends ComponentProps<C> | any = any,\n  C extends keyof JSX.IntrinsicElements | JSX.ElementConstructor<any> = any,\n> = ComponentClass<P> | JSX.ElementConstructor<P> | keyof JSX.IntrinsicElements\n// | keyof JSX.IntrinsicElements[keyof JSX.IntrinsicElements]\n\nexport type { ComponentsLinealOrder }\n\n/**\n * What the Attributes panel knows about the element a field edits, handed to\n * an attribute's `resolveProps` as its fourth argument.\n *\n * data-driven-forms gives a field its own value and the form's values, which\n * are the element's props and nothing else. A rule about the element as a\n * whole needs more than that: whether a Link Container holds anything that\n * names its link depends on the elements inside it. So the panel adds the\n * node, and a lookup for the ids listed in its `nodes`.\n *\n * Absent wherever a field is drawn outside that panel, including a unit test\n * calling the function directly, so a `resolveProps` that reads it has to\n * treat a missing context as having nothing to say.\n */\nexport interface AttributeFieldContext {\n  /** The element the Attributes panel is editing. */\n  node: NodeSchema<any>\n  /** An element of the same document by id, such as a child in `nodes`. */\n  getNode: (id: NodeId) => NodeSchema<any> | undefined\n}\n\n/**\n * An attribute's `resolveProps`: the three arguments data-driven-forms\n * passes, then the {@link AttributeFieldContext} the Attributes panel adds.\n */\nexport type AttributeResolveProps = (\n  ...args: [\n    ...Parameters<ResolvePropsFunction>,\n    context?: AttributeFieldContext,\n  ]\n) => ReturnType<ResolvePropsFunction>\n\n// @TODO ⚠️ Refactor for better adoption of hast\nexport interface AttributeSchema extends Dictionary<any> {\n  name: string\n  dataType?: DataType\n  component: string | FieldComponentType\n  validate?: Validator[]\n  condition?: ConditionDefinition | ConditionDefinition[]\n  initializeOnMount?: boolean\n  initialValue?: any\n  clearedValue?: any\n  clearOnUnmount?: boolean\n  actions?: FieldActions\n  resolveProps?: AttributeResolveProps\n  description?: string\n}\n\n// @TODO ⚠️ Refactor for better adoption of hast\nexport interface ComponentSchema<P = any> {\n  $id?: ComponentId\n  pluginId?: PluginId\n  kind?: 'element' | 'plaintext' | 'markdown'\n\n  displayName: string\n  title?: string\n  subtitle?: string\n  description?: string\n  category?: string | ComponentCategory\n\n  /**\n   * Extra words this element should be findable by in the element picker —\n   * synonyms and the name people reach for when it is not the name we chose\n   * (\"picture\" for Image, \"dropdown\" for Select).\n   *\n   * Search terms only; never rendered. A hit here ranks BELOW every hit on a\n   * name, so a tag widens what the picker finds without letting a synonym\n   * outrank the element actually called that (AGL-2486).\n   */\n  tags?: string[]\n  /** Alias of {@link tags}; both are searched. */\n  keywords?: string[]\n\n  /**\n   * Icon props for display around besigner\n   */\n  icon?: MdiIconProps\n  /**\n   * Options to be passed to styled(Component, \\{...styledOptions\\})\n   */\n  styledOptions?: MuiStyledOptions\n\n  /**\n   * Define a limitation for nodes allowed as direct descendents\n   */\n  restrictChildren?: ComponentsLinealOrder\n  /**\n   * Define a limitation for nodes allowed to be direct ancestors\n   */\n  restrictParent?: ComponentsLinealOrder\n\n  /**\n   * Filter props\n   */\n  resolveProps?: JSX.ResolveProps<NodeSchema<P>>\n\n  /**\n   * Attribute fields to modify the contextual properties\n   * New version\n   */\n  attributes?: AttributeSchema[]\n\n  /**\n   * Which groups of formatting the inline rich-text toolbar offers for this\n   * component (AGL-2557). Read only where `flags.richTextEditable` is on.\n   *\n   * Omitted means every group, which is what leaves Typography exactly as it\n   * was. Naming a subset narrows the toolbar AND the commit: a surface that\n   * offers neither lists nor links is phrasing-only, and the sanitizer holds\n   * it to that whatever an author pastes in.\n   */\n  richTextCommands?: RICH_TEXT_COMMANDS[]\n\n  /**\n   * Feature flags\n   */\n  flags?: {\n    /**\n     * Disable the use of emotion styled\n     */\n    emotion?: FEATURE_FLAG\n    /**\n     * Can the nodes of this component type be cloned?\n     */\n    cloning?: FEATURE_FLAG\n    /**\n     * Allow dragging nodes of this component type\n     */\n    dragging?: FEATURE_FLAG\n    /**\n     * Allow dropping nodes inside nodes of this component type\n     */\n    dropping?: FEATURE_FLAG\n    /**\n     * Allow editing element attributes of this component type\n     */\n    editing?: FEATURE_FLAG\n    /**\n     * Allow removing nodes of this component type\n     */\n    removing?: FEATURE_FLAG\n    /**\n     * Describe nodes of this component type to be self-closing\n     */\n    selfClosing?: FEATURE_FLAG\n    /**\n     * Component renders its `children` prop as text content the editor may\n     * edit directly (Attributes \"Text\" field, inline canvas editing).\n     */\n    textEditable?: FEATURE_FLAG\n    /**\n     * Component also accepts basic rich text (AGL-54): the inline editor\n     * upgrades to a formatting surface and commits sanitized HTML into the\n     * `html` prop (with `children` kept as the plain-text fallback).\n     */\n    richTextEditable?: FEATURE_FLAG\n    /**\n     * Component reads its children POSITIONALLY (AGL-1237), so the renderer\n     * hands it one React child per node child instead of the single `<Branch>`\n     * element it normally passes.\n     *\n     * MUI's Accordion does `const [summary, ...rest] = Children.toArray(children)`,\n     * and `toArray` does not traverse into an element — so with the default\n     * wrapping the summary swallowed the whole subtree and the Collapse got\n     * nothing. Every accordion on every published site expanded to reveal an\n     * empty panel while its content rendered unconditionally inside the\n     * summary's heading.\n     *\n     * Opt in only for components with this contract; the wrapper is what keeps\n     * the Branch/Stem/Leaf seam swappable for everything else.\n     */\n    positionalChildren?: FEATURE_FLAG\n  }\n}\n\nexport type SchemasByCategory = Record<\n  ComponentCategory | string,\n  (ComponentSchema<any> | PresetSchema<any>)[]\n>\n\nexport interface ScreenSchema {\n  nodes: NodeSchemaNested\n  createdAt?: ITimestamp\n  updatedAt?: ITimestamp\n  hostId?: HostUid\n}\n"],"names":["ComponentCategory","NodeType"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAuBD,SAASA,iBAAiB,QAAQ,wCAAoC;AAictE,OAAO,IAAA,AAAKC,kCAAAA;;;;;;;WAAAA;MAOX;AA6BD,SAASD,iBAAiB,GAAE"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/types/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 type {\n  ConditionDefinition,\n  DataType,\n  Validator,\n} from '@data-driven-forms/react-form-renderer'\nimport type {\n  FieldActions,\n  ResolvePropsFunction,\n} from '@data-driven-forms/react-form-renderer/common-types'\nimport type { MuiStyledOptions } from '@mui/system/createStyled'\nimport type { SvgIconProps } from '@mui/material/SvgIcon'\n/** Minimal icon-props type used in component/preset schemas. Structurally compatible with @aglyn/shared-ui-jsx MdiIconProps. */\nexport type MdiIconProps<D extends React.ElementType = 'svg', P = object> = SvgIconProps<D, P> & {\n  path?: string\n}\nimport type {\n  ComponentId,\n  ComponentsLinealOrder,\n  NodeId,\n  PresetId,\n} from '../foundation'\nimport { ComponentCategory } from '../foundation/constants/components'\nimport type { ITimestamp } from '@aglyn/shared-util-timestamp'\nimport type React from 'react'\nimport type { ComponentClass, ComponentProps } from 'react'\nimport type { NODE_ROOT_ID } from '../canvas-manager'\nimport type { NodeInteraction } from '../app-utils/node-interactions'\n\nimport type {\n  FEATURE_FLAG,\n  FieldComponentType,\n  RICH_TEXT_COMMANDS,\n} from '../foundation'\nimport type { PluginId } from '../plugin-manager'\nimport type { ElementContentMap, Node, Props, Taxonomic } from './ast'\nimport type { AglynDocument } from '../foundation'\nimport type { HostUid } from '../foundation'\n\ndeclare module './ast' {\n  /**\n   * This map registers all node types that may be used as top-level content in\n   * the document.\n   *\n   * These types are accepted inside `root` nodes.\n   *\n   * This interface can be augmented to register custom node types.\n   *\n   * @example\n   * declare module 'hast' {\n   *   interface RootContentMap {\n   *     // Allow using raw nodes defined by `rehype-raw`.\n   *     raw: Raw;\n   *   }\n   * }\n   */\n  export interface RootContentMap {\n    canvasNode: CanvasNode\n    canvasElement: CanvasElement\n  }\n\n  /**\n   * This map registers all node types that may be used as content in an\n   * element.\n   *\n   * These types are accepted inside `element` nodes.\n   *\n   * This interface can be augmented to register custom node types.\n   *\n   * @example\n   * declare module 'hast' {\n   *   interface RootContentMap {\n   *     custom: Custom;\n   *   }\n   * }\n   */\n  export interface ElementContentMap {\n    canvasNode: CanvasNode\n    canvasElement: CanvasElement\n  }\n}\n\n/**\n * This map registers all node types that may be used as content in an canvas\n * node.\n *\n * These types are accepted inside `element` nodes.\n *\n * This interface can be augmented to register custom node types.\n *\n * @example\n * declare module 'hast' {\n *   interface RootContentMap {\n *     custom: Custom;\n *   }\n * }\n */\nexport interface CanvasNodeContentMap extends ElementContentMap {\n  canvasNode: CanvasNode\n  canvasElement: CanvasElement\n}\n\nexport type CanvasNodeContent = CanvasNodeContentMap[keyof CanvasNodeContentMap]\n\n/**\n * CanvasNode represents a the schema for building a JSX Element.\n */\nexport interface CanvasNode extends Node {\n  /**\n   * Represents this variant of a Node.\n   */\n  type: 'node'\n\n  /**\n   * List representing the children of a node.\n   */\n  children?: CanvasNodeContent[] | undefined\n\n  /**\n   * Represents the element's internal name defined by the user\n   */\n  name?: string | undefined\n\n  /**\n   * Represents the element's parent unique identifier\n   */\n  parentId?: string | undefined\n\n  /**\n   * Represents the elements' component unique identifier\n   */\n  componentId?: string | undefined\n\n  /**\n   * Represents the elements' components' plugin unique identifier\n   */\n  pluginId?: string | undefined\n\n  /**\n   * Represents information associated with the element.\n   */\n  props?: Props | undefined\n}\n\n/**\n * CanvasElement represents a living JSX Element\n */\nexport interface CanvasElement extends CanvasNode {\n  /**\n   * Represents the element's unique identifier\n   */\n  $id: string\n}\n\nexport type AbstractId = string\n\n// @TODO ⚠️ Refactor for better adoption of hast\nexport interface AbstractNodeSchema<P = JSX.AnyProps> extends CanvasNode {\n  /**\n   * The unique identifier for a node\n   */\n  $id: AbstractId\n  title?: string\n  displayName?: string\n  description?: string\n\n  children?: any\n  nodes?: any\n\n  /**\n   * The node style properties for emotion\n   */\n  sx?: JSX.SxProps\n  /**\n   * The node props/attributes passed to the component\n   */\n  props?: P\n\n  category?: any\n  icon?: any\n\n  createdAt?: ITimestamp\n  updatedAt?: ITimestamp\n  deletedAt?: ITimestamp\n}\n\n/**\n * CanvasPreset represents an encapsulated 'node' type as the root node for\n * crafting a living JSX Element\n */\nexport interface CanvasPreset extends Node, Taxonomic {\n  /**\n   * Represents this variant of a Node.\n   */\n  type: 'preset'\n\n  /**\n   * Represents the element's unique identifier\n   */\n  $id: string\n\n  /**\n   * Represents the elements' component unique identifier\n   */\n  componentId?: string | undefined\n\n  /**\n   * Represents the elements' components' plugin unique identifier\n   */\n  pluginId?: string | undefined\n\n  /**\n   * Represents information associated with the element.\n   */\n  props?: Props | undefined\n\n  /**\n   * Represents the element's internal name defined by the user\n   */\n  name?: string | undefined\n}\n\nexport type { NodeId }\n\n// @TODO ⚠️ Refactor for better adoption of hast\ntype PresetI = AglynDocument &\n  Omit<AbstractNodeSchema<any>, 'type' | 'data'> &\n  Omit<CanvasPreset, 'type' | 'data'>\n\ninterface PresetII extends PresetI {\n  type: NodeType.PRESET | string\n}\n\nexport interface PresetSchema<P = JSX.AnyProps> extends PresetII {\n  $id: PresetId\n  pluginId?: PluginId\n  displayName?: string\n  description?: string\n  category?: string | ComponentCategory\n  /**\n   * Extra words this element should be findable by in the element picker —\n   * synonyms and the name people reach for when it is not the name we chose\n   * (\"picture\" for Image, \"dropdown\" for Select).\n   *\n   * Search terms only; never rendered. A hit here ranks BELOW every hit on a\n   * name, so a tag widens what the picker finds without letting a synonym\n   * outrank the element actually called that (AGL-2486).\n   */\n  tags?: string[]\n  /** Alias of {@link tags}; both are searched. */\n  keywords?: string[]\n  icon?: MdiIconProps\n  data: NodeSchemaNested<P>\n  /**\n   * Interaction templates wired when the preset is inserted (AGL-589):\n   * the host app resolves each `presetRef` marker to a freshly minted node\n   * and persists the result. Presets that need hover choreography (a\n   * primitive dropdown panel) ship working out of the box instead of asking\n   * the user to author the interactions by hand.\n   *\n   * TEMPLATES, and named so. These are not interactions: they are\n   * unresolved, they reference nodes that do not exist yet, and they are\n   * consumed at insert time and never stored. What they resolve INTO lives\n   * on the node as {@link NodeSchema.interactions}, and a `PresetSchema` is\n   * assignable to a `NodeSchema` — so while the two shared a name, one of\n   * them had to be wrong wherever a preset was passed as a node.\n   */\n  interactionTemplates?: PresetInteractionSchema[]\n}\n\n/**\n * A visibility step inside a {@link PresetSchema} interaction template.\n * Only the basic client visibility steps are expressible — presets\n * scaffold in-page choreography, never server automations.\n */\nexport interface PresetInteractionStepSchema {\n  type: 'showElement' | 'hideElement' | 'toggleElement'\n  /** `presetRef` of the preset node this step targets. */\n  targetRef: string\n  /** Optional grace delay, validated to 0–5000ms like the builder. */\n  delayMs?: number\n  /** Self-dismissal for steps that can reveal the target. */\n  dismissOn?: Array<'escape' | 'outsideClick'>\n}\n\n/** An interaction template a preset wires on insert (AGL-589). */\nexport interface PresetInteractionSchema {\n  name: string\n  event: 'elementClick' | 'elementHoverEnter' | 'elementHoverLeave'\n  /** `presetRef` of the preset node whose selector fires the trigger. */\n  triggerRef: string\n  steps: PresetInteractionStepSchema[]\n}\n\n// @TODO ⚠️ Refactor for better adoption of hast\ntype NodeI<P> = AglynDocument & Omit<AbstractNodeSchema<P>, 'type'>\n\nexport interface NodeSchema<P = JSX.AnyProps> extends NodeI<P> {\n  type: NodeType | string\n  /**\n   * List of the children unique identifiers for the node\n   */\n  nodes?: NodeId[]\n  /**\n   * Class name to pass the DOM node, can also be defined in props\n   */\n  className?: string\n  /**\n   * Preset-authoring marker (AGL-589): names a node inside a preset's\n   * `data` tree so the preset's interaction templates can reference it\n   * (`triggerRef` / `targetRef`). Cloned onto the inserted node; inert\n   * everywhere else.\n   */\n  presetRef?: string\n  /**\n   * Per-instance style overrides on a reusable-component instance node\n   * (AGL-1306), keyed by target: `root` (see `STYLE_OVERRIDES_ROOT_KEY`)\n   * addresses the component ROOT, and any other key is a DEFINITION-internal\n   * node id addressing one leaf inside the component (AGL-1332). Each slice\n   * is an sx-shaped record merged over that node's own sx at graft time\n   * (`composeReusableComponentNodes` → `mergeNodeSx`), so one page's CTA can\n   * switch to a white background AND repaint its headline without widening\n   * the component's declared props or detaching.\n   *\n   * Keyed on the definition's id, never the grafted `cmp__{instance}__{def}`\n   * id: the graft id is derived per placement, so it would not survive a\n   * duplicate or a re-key, and the same component could not offer two\n   * instances the same authoring vocabulary. A key naming a node the\n   * definition no longer has is ignored — a component edited later degrades\n   * to its own styling instead of taking a page down.\n   *\n   * A first-class node field, NOT a prop: `AglynNode`'s constructor drops\n   * unknown top-level keys, and anything in `props` is spread onto the\n   * instance's wrapper DOM element. Lives on the instance node in the\n   * document that places it — it survives component republish and never\n   * pins the instance to an old component version, because the graft\n   * always merges it over the definition's CURRENT nodes.\n   */\n  styleOverrides?: Record<string, JSX.SxProps>\n  /**\n   * Per-instance ATTRIBUTE overrides on a reusable-component instance node\n   * (AGL-1899) — the same addressing as {@link styleOverrides}, applied to\n   * a node's props instead of its sx, so one placement can carry a\n   * different button `variant`, `size` or `href` without the component\n   * declaring a prop for it and without detaching.\n   *\n   * Merged **per named prop**: a slice replaces only the props it names and\n   * leaves the definition's others alone, so a component that later adds a\n   * prop still gives every existing instance the new default. That is\n   * deliberately shallower than the sx merge next door — an sx slice\n   * cascades because `@scheme dark` and breakpoint objects are themselves\n   * selectors, whereas a prop value is one value, and half-merging two\n   * objects that merely look alike (say a `slotProps`) would produce a\n   * third thing neither side asked for.\n   *\n   * `sx` is refused here. Styling an instance already has a mechanism one\n   * field up, and honouring both would leave two writers racing for one\n   * rendered value with no rule to say which wins.\n   *\n   * Applied BEFORE `{{prop.*}}` substitution, so an override may itself be\n   * written in tokens and still resolves, and an override on a prop the\n   * definition binds to a declared prop wins — the more specific placement\n   * beats the component's own default.\n   */\n  attrOverrides?: Record<string, Record<string, unknown>>\n  /**\n   * EDITOR-ONLY: a screen's per-page restyling of its layout's elements\n   * (AGL-3286), parked on the screen canvas ROOT while the besigner is open.\n   *\n   * Stored on the screen VERSION as `layoutStyleOverrides`, never in `nodes`:\n   * the editor injects it here on load and lifts it back out on save\n   * (`injectLayoutStyleOverrides` / `extractLayoutStyleOverrides`). Carried on\n   * the root so an edit is an undo step, marks the screen dirty and rides the\n   * working draft like any other change. Composition ignores it — the screen\n   * root is dropped when it is grafted into the layout's slot.\n   */\n  layoutStyleOverrides?: Record<string, Record<string, Record<string, unknown>>>\n  /**\n   * Interactions this element carries — the click, hover and\n   * scroll-into-view choreography authored on it in the besigner.\n   *\n   * ## Why they live on the NODE\n   *\n   * They used to be rows in `hosts/{hostId}/actions`, bound to an element by\n   * a `[data-aglyn=\"leaf:<id>\"]` selector — the same collection the Workflows\n   * page lists. An interaction is not a site-wide automation, and storing it\n   * as one had four consequences, every one of them a thing an author would\n   * expect to work:\n   *\n   * - it was not versioned with the document, so it neither published nor\n   *   rolled back with the screen it belongs to;\n   * - it did not travel with a component copied to another site, or packaged\n   *   into a template or a plugin — the element arrived inert;\n   * - deleting the element left the action behind, pointing at a selector\n   *   nothing resolves;\n   * - and a nav's hover choreography sat in the site's automation list\n   *   beside \"when an order is placed\", which is a different kind of thing.\n   *\n   * Host actions remain, and remain the right home for a genuine site event.\n   * The split is the concept: an ACTION is something the site does, an\n   * INTERACTION is something an element does.\n   *\n   * ## Shape\n   *\n   * Deliberately the same `SiteInteraction` a site-wide interaction is, so\n   * nothing about the runtime changes: the selector is stamped from this\n   * node's own id when the page is composed, and the compiled result is the\n   * shape the client engine has always consumed. `trigger.selector` is\n   * therefore ignored here — the node IS the selector.\n   */\n  interactions?: NodeInteraction[]\n  /**\n   * Hidden by the author — the eye on the element's hierarchy row.\n   *\n   * Renders `display: none` on the canvas AND on the published site. It is\n   * the plain \"I do not want this on the page\" switch: no runtime, no\n   * interaction, nothing reveals it. Showing it again is the same eye.\n   *\n   * ## Why a FIELD and not a style\n   *\n   * Because it has to override the element's own display rather than replace\n   * it. An author who toggles the eye on a Stack laid out with\n   * `display: flex` must get that flex back when they toggle it off, and\n   * writing `display: none` into `node.sx` destroys the value it overwrote —\n   * there is nothing left to restore. Composed LAST in `Leaf` instead, so it\n   * wins on the cascade and the stored style is never touched.\n   *\n   * ## Not {@link ELEMENT_HIDDEN_CLASS}\n   *\n   * `aglyn-hidden` is a different thing wearing a similar name: it means\n   * \"starts hidden, and an interaction shows it\" — a mega-menu panel, a\n   * drawer. That class is part of a runtime contract (the show/hide steps\n   * toggle it, and the canvas reveals it for designing), and it is bespoke to\n   * that job. A visibility toggle that wrote it would enrol every hidden\n   * element in a choreography it is not part of.\n   */\n  hidden?: boolean\n  /**\n   * The computed node parent (only for type completion)\n   */\n  readonly parent?: NodeSchema<any> | null\n  /**\n   * The computed node parent (only for type completion)\n   */\n  readonly children?: NodeSchema<any>[]\n  /**\n   * The computed index in parent nodes (only for type completion)\n   */\n  readonly index?: number | null\n  /**\n   * The computed label (only for type completion)\n   */\n  readonly labelShort?: string | undefined\n  /**\n   * The computed breadcrumb path (only for type completion)\n   */\n  readonly breadcrumbPath?: NodeBreadcrumbPath\n  /**\n   * The computed component schema (only for type completion)\n   */\n  readonly componentSchema?: ComponentSchema | undefined\n  /**\n   * The computed guard for of child nodes (only for type completion)\n   */\n  readonly hasNodes?: boolean\n  /**\n   * The computed property for the resolved props from component schema\n   */\n  readonly resolvedProps?: P\n}\n\nexport enum NodeType {\n  NODE = 'node',\n  TEXT = 'text',\n  NUMBER = 'number',\n  SCREEN = 'screen',\n  REF = 'ref',\n  PRESET = 'preset',\n}\n\nexport type NodeSchemaJSON<P = JSX.AnyProps> = Omit<\n  NodeSchema<P>,\n  | 'parent'\n  | 'index'\n  | 'labelShort'\n  | 'breadcrumbPath'\n  | 'componentSchema'\n  | 'hasNodes'\n>\n\nexport type NodeSchemaNested<P = JSX.AnyProps> = Omit<\n  NodeSchemaJSON<P>,\n  'nodes'\n> & { nodes?: NodeSchemaNested<any>[] }\n\nexport type NodesMap = Record<NodeId, NodeSchema<any>>\n\nexport type NodeBreadcrumbPath = [\n  root: string & typeof NODE_ROOT_ID,\n  ...nodes: [...ancestors: NodeId[], node: NodeId],\n]\n\nexport type ProcessableNodes =\n  | NodeSchemaNested<any>[]\n  | NodeSchemaNested<any>\n  | Record<NodeId, NodeSchema>\n\nexport { ComponentCategory }\n\nexport type { ComponentId }\nexport type { PresetId }\n\nexport type ComponentFactory<\n  P extends ComponentProps<C> | any = any,\n  C extends keyof JSX.IntrinsicElements | JSX.ElementConstructor<any> = any,\n> = ComponentClass<P> | JSX.ElementConstructor<P> | keyof JSX.IntrinsicElements\n// | keyof JSX.IntrinsicElements[keyof JSX.IntrinsicElements]\n\nexport type { ComponentsLinealOrder }\n\n/**\n * What the Attributes panel knows about the element a field edits, handed to\n * an attribute's `resolveProps` as its fourth argument.\n *\n * data-driven-forms gives a field its own value and the form's values, which\n * are the element's props and nothing else. A rule about the element as a\n * whole needs more than that: whether a Link Container holds anything that\n * names its link depends on the elements inside it. So the panel adds the\n * node, and a lookup for the ids listed in its `nodes`.\n *\n * Absent wherever a field is drawn outside that panel, including a unit test\n * calling the function directly, so a `resolveProps` that reads it has to\n * treat a missing context as having nothing to say.\n */\nexport interface AttributeFieldContext {\n  /** The element the Attributes panel is editing. */\n  node: NodeSchema<any>\n  /** An element of the same document by id, such as a child in `nodes`. */\n  getNode: (id: NodeId) => NodeSchema<any> | undefined\n}\n\n/**\n * An attribute's `resolveProps`: the three arguments data-driven-forms\n * passes, then the {@link AttributeFieldContext} the Attributes panel adds.\n */\nexport type AttributeResolveProps = (\n  ...args: [\n    ...Parameters<ResolvePropsFunction>,\n    context?: AttributeFieldContext,\n  ]\n) => ReturnType<ResolvePropsFunction>\n\n// @TODO ⚠️ Refactor for better adoption of hast\nexport interface AttributeSchema extends Dictionary<any> {\n  name: string\n  dataType?: DataType\n  component: string | FieldComponentType\n  validate?: Validator[]\n  condition?: ConditionDefinition | ConditionDefinition[]\n  initializeOnMount?: boolean\n  initialValue?: any\n  clearedValue?: any\n  clearOnUnmount?: boolean\n  actions?: FieldActions\n  resolveProps?: AttributeResolveProps\n  description?: string\n}\n\n// @TODO ⚠️ Refactor for better adoption of hast\nexport interface ComponentSchema<P = any> {\n  $id?: ComponentId\n  pluginId?: PluginId\n  kind?: 'element' | 'plaintext' | 'markdown'\n\n  displayName: string\n  title?: string\n  subtitle?: string\n  description?: string\n  category?: string | ComponentCategory\n\n  /**\n   * Extra words this element should be findable by in the element picker —\n   * synonyms and the name people reach for when it is not the name we chose\n   * (\"picture\" for Image, \"dropdown\" for Select).\n   *\n   * Search terms only; never rendered. A hit here ranks BELOW every hit on a\n   * name, so a tag widens what the picker finds without letting a synonym\n   * outrank the element actually called that (AGL-2486).\n   */\n  tags?: string[]\n  /** Alias of {@link tags}; both are searched. */\n  keywords?: string[]\n\n  /**\n   * Icon props for display around besigner\n   */\n  icon?: MdiIconProps\n  /**\n   * Options to be passed to styled(Component, \\{...styledOptions\\})\n   */\n  styledOptions?: MuiStyledOptions\n\n  /**\n   * Define a limitation for nodes allowed as direct descendents\n   */\n  restrictChildren?: ComponentsLinealOrder\n  /**\n   * Define a limitation for nodes allowed to be direct ancestors\n   */\n  restrictParent?: ComponentsLinealOrder\n\n  /**\n   * Filter props\n   */\n  resolveProps?: JSX.ResolveProps<NodeSchema<P>>\n\n  /**\n   * Attribute fields to modify the contextual properties\n   * New version\n   */\n  attributes?: AttributeSchema[]\n\n  /**\n   * Which groups of formatting the inline rich-text toolbar offers for this\n   * component (AGL-2557). Read only where `flags.richTextEditable` is on.\n   *\n   * Omitted means every group, which is what leaves Typography exactly as it\n   * was. Naming a subset narrows the toolbar AND the commit: a surface that\n   * offers neither lists nor links is phrasing-only, and the sanitizer holds\n   * it to that whatever an author pastes in.\n   */\n  richTextCommands?: RICH_TEXT_COMMANDS[]\n\n  /**\n   * Feature flags\n   */\n  flags?: {\n    /**\n     * Disable the use of emotion styled\n     */\n    emotion?: FEATURE_FLAG\n    /**\n     * Can the nodes of this component type be cloned?\n     */\n    cloning?: FEATURE_FLAG\n    /**\n     * Allow dragging nodes of this component type\n     */\n    dragging?: FEATURE_FLAG\n    /**\n     * Allow dropping nodes inside nodes of this component type\n     */\n    dropping?: FEATURE_FLAG\n    /**\n     * Allow editing element attributes of this component type\n     */\n    editing?: FEATURE_FLAG\n    /**\n     * Allow removing nodes of this component type\n     */\n    removing?: FEATURE_FLAG\n    /**\n     * Describe nodes of this component type to be self-closing\n     */\n    selfClosing?: FEATURE_FLAG\n    /**\n     * Component renders its `children` prop as text content the editor may\n     * edit directly (Attributes \"Text\" field, inline canvas editing).\n     */\n    textEditable?: FEATURE_FLAG\n    /**\n     * Component also accepts basic rich text (AGL-54): the inline editor\n     * upgrades to a formatting surface and commits sanitized HTML into the\n     * `html` prop (with `children` kept as the plain-text fallback).\n     */\n    richTextEditable?: FEATURE_FLAG\n    /**\n     * Component reads its children POSITIONALLY (AGL-1237), so the renderer\n     * hands it one React child per node child instead of the single `<Branch>`\n     * element it normally passes.\n     *\n     * MUI's Accordion does `const [summary, ...rest] = Children.toArray(children)`,\n     * and `toArray` does not traverse into an element — so with the default\n     * wrapping the summary swallowed the whole subtree and the Collapse got\n     * nothing. Every accordion on every published site expanded to reveal an\n     * empty panel while its content rendered unconditionally inside the\n     * summary's heading.\n     *\n     * Opt in only for components with this contract; the wrapper is what keeps\n     * the Branch/Stem/Leaf seam swappable for everything else.\n     */\n    positionalChildren?: FEATURE_FLAG\n  }\n}\n\nexport type SchemasByCategory = Record<\n  ComponentCategory | string,\n  (ComponentSchema<any> | PresetSchema<any>)[]\n>\n\nexport interface ScreenSchema {\n  nodes: NodeSchemaNested\n  createdAt?: ITimestamp\n  updatedAt?: ITimestamp\n  hostId?: HostUid\n}\n"],"names":["ComponentCategory","NodeType"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAuBD,SAASA,iBAAiB,QAAQ,wCAAoC;AAictE,OAAO,IAAA,AAAKC,kCAAAA;;;;;;;WAAAA;MAOX;AA6BD,SAASD,iBAAiB,GAAE"}

package/src/lib/app-utils/campaign-attribution.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/campaign-attribution.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 * Where an account came from (AGL-1731) — the campaign contract between the\n * marketing site's links and the console's signup.\n *\n * Until this existed a paid click, an organic visit and a partner link\n * arrived indistinguishable: `sign_up` carried `method` and nothing else, so\n * no report could say which spend produced a customer. That is tolerable\n * while nothing is being spent and not tolerable the day advertising starts,\n * because the measurement has to exist BEFORE the traffic — a signup that\n * lands unattributed is unattributed forever.\n *\n * ## Why an allowlist, and why exactly three\n *\n * `utm_source`, `utm_medium` and `utm_campaign` are the three axes an ad\n * report is read on: which channel, what kind of placement, which push. They\n * are also the three the marketing site can be told to emit without further\n * decisions.\n *\n * `utm_term` and `utm_content` are deliberately OUT, matching the refusal the\n * tenant's own first-party collector already made for its visitors\n * (`apps/tenant/app/api/analytics/collect/route.ts`): keyword- and\n * variant-level labels multiply cardinality without answering a question\n * anyone asks of a signup, and a keyword string is the most likely of the\n * five to carry something a person typed. `gclid` and bare `ref` are out for\n * that same cardinality reason. Not for a privacy one: the property runs ads\n * personalization ON in every region, and Google's own auto-tagging already\n * carries the click identifier into it, so re-collecting `gclid` here would\n * duplicate a field the platform owns rather than withhold anything.\n *\n * The allowlist is the privacy mechanism, not a convenience. A parser that\n * copied \"the campaign-ish parameters\" would be one marketing link away from\n * storing `?email=` against a person, and the standing rule is that personal\n * data never travels in a URL parameter in the first place.\n *\n * ## Two exits, and only one of them is already guarded\n *\n * A parsed campaign leaves this process twice: onto the GA4 `sign_up` hit,\n * and into `users/{uid}` so revenue can be attributed to it months later.\n * Only the first passes `sanitizeEventParams`. The Firestore write does not,\n * so the scrub — email shape refused, length capped, blanks dropped — lives\n * HERE, on the way in, and both exits inherit it.\n *\n * ## Why the wire form is what gets stored\n *\n * Same contract as the AGL-1535 plan intent it rides beside: the stored value\n * is the query string, re-parsed by this parser on the way out. `users/{uid}`\n * is owner-writable, so a stored field is a client-FORGEABLE field. Re-parsing\n * means a hand-edited document can claim no more than a hand-edited URL could,\n * which is a marketing label and nothing that touches entitlement.\n */\n\n/**\n * The URL parameter names, in report order. Exported because the marketing\n * site's links, the stored wire form and this parser all have to spell them\n * identically — two spellings would read as two dimensions in GA4 and split\n * every report in half.\n */\nexport const CAMPAIGN_QUERY_KEYS = [\n  'utm_source',\n  'utm_medium',\n  'utm_campaign',\n] as const\n\n/** A campaign, with every field optional — a partial one is still worth having. */\nexport interface CampaignAttribution {\n  /** `utm_source` — the channel: `google`, `hn`, a partner's name. */\n  source?: string\n  /** `utm_medium` — the kind of placement: `cpc`, `email`, `referral`. */\n  medium?: string\n  /** `utm_campaign` — which push: `sept-launch`. */\n  campaign?: string\n}\n\n/** Longest value stored or sent, matching `sanitizeEventParams`'s own cap. */\nconst MAX_VALUE_LENGTH = 100\n\n/** The same shape test the event sanitizer uses, applied to the stored exit too. */\nconst EMAIL_SHAPED = /[^\\s@]+@[^\\s@]+\\.[^\\s@]+/\n\n/** Which `CampaignAttribution` field each URL key fills. */\nconst FIELD_FOR_KEY: Record<\n  (typeof CAMPAIGN_QUERY_KEYS)[number],\n  keyof CampaignAttribution\n> = {\n  utm_source: 'source',\n  utm_medium: 'medium',\n  utm_campaign: 'campaign',\n}\n\n/** What a Server Component holds before it has a `URLSearchParams`. */\nexport type CampaignParamSource =\n  | URLSearchParams\n  | Record<string, string | string[] | undefined>\n  | null\n  | undefined\n\nfunction rawValue(params: CampaignParamSource, key: string): string | null {\n  if (!params) return null\n  if (typeof (params as URLSearchParams).get === 'function') {\n    return (params as URLSearchParams).get(key)\n  }\n  const value = (params as Record<string, string | string[] | undefined>)[key]\n  // A repeated parameter arrives as an array. The first one wins rather than\n  // being joined: `utm_medium=cpc&utm_medium=organic` is a malformed link, and\n  // inventing `cpc,organic` would put a value in the reports that no campaign\n  // ever set.\n  if (Array.isArray(value)) return value.length ? value[0] : null\n  return typeof value === 'string' ? value : null\n}\n\n/**\n * Reduce one raw parameter to something storable, or null to drop it.\n *\n * Dropping the single value rather than the whole campaign is deliberate: a\n * mail-merge link that puts an address in `utm_source` still names a real\n * `utm_campaign`, and keeping the half that is safe beats losing the\n * attribution to protect the half that is not.\n */\nfunction scrubValue(value: string | null): string | null {\n  if (typeof value !== 'string') return null\n  const trimmed = value.trim()\n  if (!trimmed) return null\n  if (EMAIL_SHAPED.test(trimmed)) return null\n  return trimmed.slice(0, MAX_VALUE_LENGTH)\n}\n\n/**\n * Read the campaign off a signup URL, or null when it names none.\n *\n * Null rather than `{}` so a caller can branch on \"was there a campaign at\n * all\". An empty object written to an account would read as \"arrived from\n * nowhere, confirmed\" instead of \"never asked\", and those are different facts.\n */\nexport function parseCampaignAttribution(\n  params: CampaignParamSource,\n): CampaignAttribution | null {\n  if (!params) return null\n  const attribution: CampaignAttribution = {}\n  for (const key of CAMPAIGN_QUERY_KEYS) {\n    const value = scrubValue(rawValue(params, key))\n    if (value) attribution[FIELD_FOR_KEY[key]] = value\n  }\n  return Object.keys(attribution).length ? attribution : null\n}\n\n/**\n * The canonical query string for a campaign — the ONLY place the stored form\n * is written, so it cannot drift from what the parser reads back.\n */\nexport function campaignAttributionQuery(\n  attribution: CampaignAttribution | null | undefined,\n): string {\n  if (!attribution) return ''\n  const params = new URLSearchParams()\n  for (const key of CAMPAIGN_QUERY_KEYS) {\n    const value = attribution[FIELD_FOR_KEY[key]]\n    if (value) params.set(key, value)\n  }\n  return params.toString()\n}\n\n/**\n * The campaign as GA4 event parameters, ready to spread into `sign_up`.\n *\n * Renamed off the `utm_` spellings on purpose. These are OUR event parameters,\n * registered as custom dimensions on the property (see `docs/ANALYTICS.md`);\n * the `utm_` names belong to GA's own automatic campaign collection, and\n * shipping a custom parameter under a name the platform also owns is how a\n * dimension ends up meaning two things.\n *\n * Returns an empty object — never keys with `undefined` values — so that\n * spreading it into an organic signup's params adds nothing at all. A\n * `campaign_source: undefined` on every unattributed signup would survive the\n * sanitizer as an absence but read, to whoever writes the report, as a\n * dimension that is populated sometimes and broken the rest of the time.\n */\nexport function campaignEventParams(\n  attribution: CampaignAttribution | null | undefined,\n): {\n  campaign_source?: string\n  campaign_medium?: string\n  campaign_name?: string\n} {\n  if (!attribution) return {}\n  return {\n    ...(attribution.source ? { campaign_source: attribution.source } : {}),\n    ...(attribution.medium ? { campaign_medium: attribution.medium } : {}),\n    ...(attribution.campaign ? { campaign_name: attribution.campaign } : {}),\n  }\n}\n"],"names":["CAMPAIGN_QUERY_KEYS","MAX_VALUE_LENGTH","EMAIL_SHAPED","FIELD_FOR_KEY","utm_source","utm_medium","utm_campaign","rawValue","params","key","get","value","Array","isArray","length","scrubValue","trimmed","trim","test","slice","parseCampaignAttribution","attribution","Object","keys","campaignAttributionQuery","URLSearchParams","set","toString","campaignEventParams","source","campaign_source","medium","campaign_medium","campaign","campaign_name"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiDC,GAED;;;;;CAKC,GACD,OAAO,MAAMA,sBAAsB;IACjC;IACA;IACA;CACD,CAAS;AAYV,4EAA4E,GAC5E,MAAMC,mBAAmB;AAEzB,kFAAkF,GAClF,MAAMC,eAAe;AAErB,0DAA0D,GAC1D,MAAMC,gBAGF;IACFC,YAAY;IACZC,YAAY;IACZC,cAAc;AAChB;AASA,SAASC,SAASC,MAA2B,EAAEC,GAAW;IACxD,IAAI,CAACD,QAAQ,OAAO;IACpB,IAAI,OAAO,AAACA,OAA2BE,GAAG,KAAK,YAAY;QACzD,OAAO,AAACF,OAA2BE,GAAG,CAACD;IACzC;IACA,MAAME,QAAQ,AAACH,MAAwD,CAACC,IAAI;IAC5E,2EAA2E;IAC3E,6EAA6E;IAC7E,4EAA4E;IAC5E,YAAY;IACZ,IAAIG,MAAMC,OAAO,CAACF,QAAQ,OAAOA,MAAMG,MAAM,GAAGH,KAAK,CAAC,EAAE,GAAG;IAC3D,OAAO,OAAOA,UAAU,WAAWA,QAAQ;AAC7C;AAEA;;;;;;;CAOC,GACD,SAASI,WAAWJ,KAAoB;IACtC,IAAI,OAAOA,UAAU,UAAU,OAAO;IACtC,MAAMK,UAAUL,MAAMM,IAAI;IAC1B,IAAI,CAACD,SAAS,OAAO;IACrB,IAAId,aAAagB,IAAI,CAACF,UAAU,OAAO;IACvC,OAAOA,QAAQG,KAAK,CAAC,GAAGlB;AAC1B;AAEA;;;;;;CAMC,GACD,OAAO,SAASmB,yBACdZ,MAA2B;IAE3B,IAAI,CAACA,QAAQ,OAAO;IACpB,MAAMa,cAAmC,CAAC;IAC1C,KAAK,MAAMZ,OAAOT,oBAAqB;QACrC,MAAMW,QAAQI,WAAWR,SAASC,QAAQC;QAC1C,IAAIE,OAAOU,WAAW,CAAClB,aAAa,CAACM,IAAI,CAAC,GAAGE;IAC/C;IACA,OAAOW,OAAOC,IAAI,CAACF,aAAaP,MAAM,GAAGO,cAAc;AACzD;AAEA;;;CAGC,GACD,OAAO,SAASG,yBACdH,WAAmD;IAEnD,IAAI,CAACA,aAAa,OAAO;IACzB,MAAMb,SAAS,IAAIiB;IACnB,KAAK,MAAMhB,OAAOT,oBAAqB;QACrC,MAAMW,QAAQU,WAAW,CAAClB,aAAa,CAACM,IAAI,CAAC;QAC7C,IAAIE,OAAOH,OAAOkB,GAAG,CAACjB,KAAKE;IAC7B;IACA,OAAOH,OAAOmB,QAAQ;AACxB;AAEA;;;;;;;;;;;;;;CAcC,GACD,OAAO,SAASC,oBACdP,WAAmD;IAMnD,IAAI,CAACA,aAAa,OAAO,CAAC;IAC1B,OAAO,aACDA,YAAYQ,MAAM,GAAG;QAAEC,iBAAiBT,YAAYQ,MAAM;IAAC,IAAI,CAAC,GAChER,YAAYU,MAAM,GAAG;QAAEC,iBAAiBX,YAAYU,MAAM;IAAC,IAAI,CAAC,GAChEV,YAAYY,QAAQ,GAAG;QAAEC,eAAeb,YAAYY,QAAQ;IAAC,IAAI,CAAC;AAE1E"}

package/src/lib/app-utils/campaign-forwarding.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/campaign-forwarding.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 * Carry the campaign across the domain hop (AGL-1731).\n *\n * `campaign-attribution.ts` is the READER half of this contract and it works.\n * This is the half that was missing, and without it the reader was fed\n * nothing: `aglyn.com` is a tenant published site and `app.aglyn.com` is the\n * console, a real cross-origin hop, and no code anywhere put a `utm_*`\n * parameter on a console-bound link. So `users/{uid}.signupCampaign` was\n * written for exactly one population — visitors whose CTA href had a campaign\n * typed into it by hand.\n *\n * A hand-typed one is worse than none. It is STATIC: `utm_source=google`\n * authored onto the pricing button attributes every clicker to Google whether\n * they arrived from Google, from Hacker News or from a bookmark. Confidently\n * wrong attribution reaches the same spend decisions as absent attribution and\n * is much harder to notice, because the report looks populated.\n *\n * What is needed instead is PER-VISITOR forwarding: the landing page copies\n * the campaign off its own inbound URL onto the console-bound href, at click\n * time, for that one visitor.\n *\n * ## Why a delegated listener and not `AppLink`\n *\n * The same reason `analytics-link-clicks.ts` gives, and it is the reason that\n * decides this file's shape. The CTAs on `aglyn.com` are authored besigner\n * content, not repo files; rich-text and Custom HTML anchors are written with\n * `dangerouslySetInnerHTML` and are plain DOM anchors with no React handler at\n * all. A prop on `AppLink` would miss them, and reaching them from `AppLink`\n * would mean `useSearchParams` in a component the console renders on every\n * page — a dynamic-rendering hazard on statically generated surfaces, paid on\n * every route to fix a link on one of them. A capture-phase listener on\n * `document` sees every anchor, costs one listener, and renders nothing.\n *\n * ## The two tiers, and why the storage tier is the SECOND one\n *\n * A visitor rarely signs up from the page the ad landed on. They land on\n * `/?utm_source=google&...`, read `/pricing`, then click. By then the campaign\n * is off the address bar, so reading the live URL at click time alone would\n * capture only the minority who convert without navigating.\n *\n * - **Tier 1 — the live URL.** Read `window.location.search` at click time.\n *   This touches NO storage: the parameters are already in the page the\n *   visitor asked for. Nothing is written to their device, so there is nothing\n *   here to consent to, and it works for every visitor including one who has\n *   declined analytics.\n * - **Tier 2 — the first touch of the visit**, in `sessionStorage`, which is\n *   what survives the walk from the landing page to the pricing page.\n *\n * Tier 2 WINS when both exist, because first touch is the question being\n * asked. Last touch — re-deriving the campaign from whatever URL happens to be\n * current at signup — answers a different question and would disagree with\n * GA4's own session attribution.\n *\n * ## Why tier 2 is gated on analytics consent, and tier 1 is not\n *\n * Tier 2 writes to the visitor's device for an analytics purpose, so it is\n * `analytics_storage` in the consent-mode sense and it waits for the same\n * grant the GA tag waits for (AGL-1498). The gate is not re-implemented here\n * and no consent record is read here: the caller already computes\n * `analyticsAllowed` for the tag and hands the same boolean down, so there is\n * one gate and it cannot drift from itself.\n *\n * It is deliberately NOT gated on advertising storage. Nothing here reads or\n * writes an advertising identifier, sets a cookie, or leaves anything that\n * outlives the tab, and AGL-1649 has advertising denied with no route for a\n * host to grant it — gating on a permission that cannot currently be given\n * would be a feature that is dead by construction rather than one that is off.\n *\n * **Consent unresolved is not consent denied, and both are falsy.** With\n * `strictNullChecks` off repo-wide that distinction is the sort that\n * evaporates, so it is carried as an explicit tri-state: until the caller has\n * actually resolved the visitor's state, tier 2 neither reads nor writes.\n * Failing closed here costs an attribution; failing open would write to a\n * device before the visitor answered.\n *\n * ## What is never done\n *\n * A value is only ever forwarded if this visitor literally arrived carrying\n * it. There is no default, no inference from the referrer, and no\n * `utm_source=direct` — a signup with no campaign must reach the console with\n * no campaign, so that \"arrived from nowhere\" and \"never asked\" stay the\n * distinct facts `campaign-attribution.ts` keeps them.\n *\n * Only links to OUR OWN console origin are touched, and the origin is supplied\n * by the caller rather than written here — a self-host install points\n * `NEXT_PUBLIC_CONSOLE_URL` somewhere else entirely. Decorating any other host\n * would post our campaign labels to a third party, which is a data leak dressed\n * up as attribution.\n *\n * ## One accepted consequence\n *\n * The tenant runtime serves `aglyn.com` AND every customer's published site,\n * so a customer site that links to our signup forwards ITS OWN inbound\n * campaign — an agency partner's `utm_source=their-newsletter` would land in our\n * acquisition report describing their spend, not ours. It is not gated on\n * \"is this the operator's marketing host\" deliberately: that gate needs a\n * second configured origin to compare against, and a deployment that forgot to\n * set it would forward NOTHING while looking perfectly healthy. A silent zero\n * is the exact failure AGL-1731 is about, and it is worse than a few\n * mislabelled rows that GA's own Hostname dimension can already separate.\n */\n\nimport {\n  CAMPAIGN_QUERY_KEYS,\n  campaignAttributionQuery,\n  parseCampaignAttribution,\n  type CampaignAttribution,\n} from './campaign-attribution'\n\n/**\n * Where the first touch of this visit is held. `sessionStorage`, so it dies\n * with the tab: a campaign is a fact about one visit, and a value that\n * outlived the visit would start attributing next week's organic return to\n * this week's ad.\n */\nexport const CAMPAIGN_VISIT_STORAGE_KEY = 'aglyn:campaign'\n\n/**\n * What a read of the first-touch store produced.\n *\n * Three states rather than \"a campaign or null\", and the third is the whole\n * point. `sessionStorage` throws outright in some privacy modes, and a\n * `catch` that returned null would report \"this visitor named no campaign\" —\n * indistinguishable from an organic arrival, which is how an unreadable source\n * becomes a measured zero. `unreadable` is a different answer and the caller\n * treats it differently: it falls through to the live URL instead of\n * concluding anything.\n */\nexport type VisitCampaignRead =\n  | { status: 'campaign'; campaign: CampaignAttribution }\n  | { status: 'none' }\n  | { status: 'unreadable' }\n\n/**\n * Whether the visitor has granted analytics storage.\n *\n * `null` means NOT YET RESOLVED, and is not the same as `false`. The consent\n * state is settled client-side after hydration, so there is a window in every\n * pageview where the answer is genuinely unknown, and treating it as a denial\n * would be as wrong as treating it as a grant. Tier 2 does nothing in it.\n */\nlet storageConsent: boolean | null = null\n\n/** The one listener pair on `document`, or null. Held, not flagged — the same\n * reason `analytics-link-clicks.ts` holds its own: a boolean lets a caller\n * install over a listener that is still attached, and re-entrant decoration is\n * harder to see than a double-counted event. */\nlet installedHandler: ((event: Event) => void) | null = null\n\nfunction sessionStore(): Storage | null {\n  if (typeof window === 'undefined') return null\n  // Touching the property itself can throw, not just its methods.\n  try {\n    return window.sessionStorage ?? null\n  } catch {\n    return null\n  }\n}\n\n/**\n * The campaign this visit began with, as far as the store can say.\n *\n * Re-parsed through the same allowlist that wrote it rather than trusted:\n * `sessionStorage` is writable by anything running on the page, so the stored\n * string can claim no more than an inbound URL could — three allowlisted keys,\n * trimmed, email shapes refused, capped.\n */\nexport function readVisitCampaign(): VisitCampaignRead {\n  if (storageConsent !== true) return { status: 'none' }\n  const store = sessionStore()\n  if (!store) return { status: 'unreadable' }\n  let raw: string | null\n  try {\n    raw = store.getItem(CAMPAIGN_VISIT_STORAGE_KEY)\n  } catch {\n    return { status: 'unreadable' }\n  }\n  if (!raw) return { status: 'none' }\n  const campaign = parseCampaignAttribution(new URLSearchParams(raw))\n  return campaign ? { status: 'campaign', campaign } : { status: 'none' }\n}\n\n/**\n * Remember the campaign on the current URL as this visit's first touch.\n *\n * First touch means FIRST: an existing entry is never replaced. A second\n * campaign arriving later in the same visit is a link the visitor followed\n * after we already knew where they came from, and letting it overwrite would\n * quietly turn this into last-touch.\n *\n * Returns what is now remembered so a caller can assert on it.\n */\nexport function rememberVisitCampaign(search?: string): CampaignAttribution | null {\n  const existing = readVisitCampaign()\n  if (existing.status === 'campaign') return existing.campaign\n  if (storageConsent !== true) return null\n  const store = sessionStore()\n  if (!store) return null\n  const source =\n    typeof search === 'string'\n      ? search\n      : typeof window === 'undefined'\n        ? ''\n        : window.location.search\n  const campaign = parseCampaignAttribution(new URLSearchParams(source))\n  if (!campaign) return null\n  try {\n    store.setItem(CAMPAIGN_VISIT_STORAGE_KEY, campaignAttributionQuery(campaign))\n  } catch {\n    // A store that refuses the write costs the walk from the landing page to\n    // the pricing page, never the click itself — tier 1 still carries a\n    // visitor who converts without navigating.\n    return null\n  }\n  return campaign\n}\n\n/**\n * Tell this module what the visitor's analytics consent state is.\n *\n * Called by whoever already computed it for the tag, on every render, so a\n * grant seeds the first touch the moment it is given and a WITHDRAWAL takes\n * effect immediately: the stored value is dropped, not merely ignored. A\n * visitor who changes their mind mid-visit should not leave the thing they\n * withdrew consent for sitting on their device.\n */\nexport function setCampaignForwardingConsent(allowed: boolean | null): void {\n  storageConsent = allowed === true ? true : allowed === false ? false : null\n  if (storageConsent === true) {\n    rememberVisitCampaign()\n    return\n  }\n  if (storageConsent === false) {\n    const store = sessionStore()\n    if (!store) return\n    try {\n      store.removeItem(CAMPAIGN_VISIT_STORAGE_KEY)\n    } catch {\n      // Nothing else to try, and a failed cleanup must not break the page.\n    }\n  }\n}\n\n/**\n * The campaign to forward, first touch preferred.\n *\n * The `unreadable` case falls through to the live URL rather than to nothing,\n * which is the point of carrying that state at all: a broken store degrades\n * this to tier 1 rather than to silence.\n */\nexport function campaignToForward(search?: string): CampaignAttribution | null {\n  const stored = readVisitCampaign()\n  if (stored.status === 'campaign') return stored.campaign\n  const live =\n    typeof search === 'string'\n      ? search\n      : typeof window === 'undefined'\n        ? ''\n        : window.location.search\n  return parseCampaignAttribution(new URLSearchParams(live))\n}\n\nfunction normalizeOrigin(value: string | null | undefined): string {\n  if (!value) return ''\n  try {\n    return new URL(value).origin\n  } catch {\n    return ''\n  }\n}\n\n/**\n * The href a console-bound link should carry for this visitor, or null to\n * leave it exactly as authored.\n *\n * Null — rather than \"the href unchanged\" — so that a caller cannot write back\n * a value it did not mean to change, and so a test can tell \"decided not to\n * touch this\" from \"touched it and produced the same string\".\n *\n * The three keys are replaced WHOLESALE, never merged key by key. A visitor\n * who arrived with only `utm_source=hn` clicking a button authored with all\n * three must not produce `source=hn` married to the author's `campaign=`: that\n * row describes an event that never happened. Everything else on the href —\n * `plan`, `interval`, the AGL-1535 intent — is preserved untouched.\n */\nexport function decorateCampaignHref(\n  href: string,\n  baseHref: string,\n  consoleOrigin: string,\n  campaign: CampaignAttribution | null,\n): string | null {\n  if (!campaign) return null\n  const origin = normalizeOrigin(consoleOrigin)\n  if (!origin) return null\n  let url: URL\n  try {\n    url = new URL(href, baseHref)\n  } catch {\n    return null\n  }\n  if (url.origin !== origin) return null\n  for (const key of CAMPAIGN_QUERY_KEYS) url.searchParams.delete(key)\n  const query = new URLSearchParams(campaignAttributionQuery(campaign))\n  query.forEach((value, key) => url.searchParams.set(key, value))\n  const next = url.toString()\n  return next === href ? null : next\n}\n\n/**\n * Start forwarding the campaign onto console-bound links on this page.\n *\n * Idempotent and safe to call during render, the same contract as\n * `installLinkClickTracking` and for the same AGL-1550 reason: an effect only\n * runs if React commits, and a page that renders without committing would\n * otherwise ship links with no campaign on them.\n *\n * Both `pointerdown` and `click` are listened for, in capture phase.\n * `pointerdown` is what covers a middle-click, a modifier-click into a new\n * tab, and \"Copy link address\" from the context menu — all of which read the\n * href without ever firing `click`. `click` is what covers keyboard\n * activation, which fires no pointer event at all. Decoration is idempotent,\n * so a plain left click doing both is not a problem.\n *\n * Returns an uninstall function for tests and for a caller that owns the page\n * lifecycle.\n */\nexport function installCampaignForwarding(options: {\n  consoleOrigin: string\n}): () => void {\n  if (typeof document === 'undefined' || typeof window === 'undefined') {\n    return () => undefined\n  }\n  if (installedHandler) return () => undefined\n  const origin = normalizeOrigin(options?.consoleOrigin)\n  if (!origin) return () => undefined\n\n  const onActivate = (event: Event) => {\n    try {\n      const target = event.target as Element | null\n      if (!target || typeof target.closest !== 'function') return\n      const anchor = target.closest('a[href]')\n      if (!anchor) return\n      const decorated = decorateCampaignHref(\n        anchor.getAttribute('href') || '',\n        window.location.href,\n        origin,\n        campaignToForward(),\n      )\n      if (decorated) anchor.setAttribute('href', decorated)\n    } catch {\n      // Attribution never breaks a navigation. A link that throws here would\n      // be a link that does not work, which costs more than the campaign does.\n    }\n  }\n\n  installedHandler = onActivate\n  document.addEventListener('pointerdown', onActivate, true)\n  document.addEventListener('click', onActivate, true)\n  return resetCampaignForwarding\n}\n\n/** Test seam — removes both listeners, forgets them, and forgets consent. */\nexport function resetCampaignForwarding(): void {\n  if (installedHandler && typeof document !== 'undefined') {\n    document.removeEventListener('pointerdown', installedHandler, true)\n    document.removeEventListener('click', installedHandler, true)\n  }\n  installedHandler = null\n  storageConsent = null\n}\n"],"names":["CAMPAIGN_QUERY_KEYS","campaignAttributionQuery","parseCampaignAttribution","CAMPAIGN_VISIT_STORAGE_KEY","storageConsent","installedHandler","sessionStore","window","sessionStorage","readVisitCampaign","status","store","raw","getItem","campaign","URLSearchParams","rememberVisitCampaign","search","existing","source","location","setItem","setCampaignForwardingConsent","allowed","removeItem","campaignToForward","stored","live","normalizeOrigin","value","URL","origin","decorateCampaignHref","href","baseHref","consoleOrigin","url","key","searchParams","delete","query","forEach","set","next","toString","installCampaignForwarding","options","document","undefined","onActivate","event","target","closest","anchor","decorated","getAttribute","setAttribute","addEventListener","resetCampaignForwarding","removeEventListener"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoGC,GAED,SACEA,mBAAmB,EACnBC,wBAAwB,EACxBC,wBAAwB,QAEnB,4BAAwB;AAE/B;;;;;CAKC,GACD,OAAO,MAAMC,6BAA6B,iBAAgB;AAkB1D;;;;;;;CAOC,GACD,IAAIC,iBAAiC;AAErC;;;8CAG8C,GAC9C,IAAIC,mBAAoD;AAExD,SAASC;IACP,IAAI,OAAOC,WAAW,aAAa,OAAO;IAC1C,gEAAgE;IAChE,IAAI;YACKA;QAAP,QAAOA,yBAAAA,OAAOC,cAAc,YAArBD,yBAAyB;IAClC,EAAE,eAAM;QACN,OAAO;IACT;AACF;AAEA;;;;;;;CAOC,GACD,OAAO,SAASE;IACd,IAAIL,mBAAmB,MAAM,OAAO;QAAEM,QAAQ;IAAO;IACrD,MAAMC,QAAQL;IACd,IAAI,CAACK,OAAO,OAAO;QAAED,QAAQ;IAAa;IAC1C,IAAIE;IACJ,IAAI;QACFA,MAAMD,MAAME,OAAO,CAACV;IACtB,EAAE,eAAM;QACN,OAAO;YAAEO,QAAQ;QAAa;IAChC;IACA,IAAI,CAACE,KAAK,OAAO;QAAEF,QAAQ;IAAO;IAClC,MAAMI,WAAWZ,yBAAyB,IAAIa,gBAAgBH;IAC9D,OAAOE,WAAW;QAAEJ,QAAQ;QAAYI;IAAS,IAAI;QAAEJ,QAAQ;IAAO;AACxE;AAEA;;;;;;;;;CASC,GACD,OAAO,SAASM,sBAAsBC,MAAe;IACnD,MAAMC,WAAWT;IACjB,IAAIS,SAASR,MAAM,KAAK,YAAY,OAAOQ,SAASJ,QAAQ;IAC5D,IAAIV,mBAAmB,MAAM,OAAO;IACpC,MAAMO,QAAQL;IACd,IAAI,CAACK,OAAO,OAAO;IACnB,MAAMQ,SACJ,OAAOF,WAAW,WACdA,SACA,OAAOV,WAAW,cAChB,KACAA,OAAOa,QAAQ,CAACH,MAAM;IAC9B,MAAMH,WAAWZ,yBAAyB,IAAIa,gBAAgBI;IAC9D,IAAI,CAACL,UAAU,OAAO;IACtB,IAAI;QACFH,MAAMU,OAAO,CAAClB,4BAA4BF,yBAAyBa;IACrE,EAAE,eAAM;QACN,yEAAyE;QACzE,oEAAoE;QACpE,2CAA2C;QAC3C,OAAO;IACT;IACA,OAAOA;AACT;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASQ,6BAA6BC,OAAuB;IAClEnB,iBAAiBmB,YAAY,OAAO,OAAOA,YAAY,QAAQ,QAAQ;IACvE,IAAInB,mBAAmB,MAAM;QAC3BY;QACA;IACF;IACA,IAAIZ,mBAAmB,OAAO;QAC5B,MAAMO,QAAQL;QACd,IAAI,CAACK,OAAO;QACZ,IAAI;YACFA,MAAMa,UAAU,CAACrB;QACnB,EAAE,eAAM;QACN,qEAAqE;QACvE;IACF;AACF;AAEA;;;;;;CAMC,GACD,OAAO,SAASsB,kBAAkBR,MAAe;IAC/C,MAAMS,SAASjB;IACf,IAAIiB,OAAOhB,MAAM,KAAK,YAAY,OAAOgB,OAAOZ,QAAQ;IACxD,MAAMa,OACJ,OAAOV,WAAW,WACdA,SACA,OAAOV,WAAW,cAChB,KACAA,OAAOa,QAAQ,CAACH,MAAM;IAC9B,OAAOf,yBAAyB,IAAIa,gBAAgBY;AACtD;AAEA,SAASC,gBAAgBC,KAAgC;IACvD,IAAI,CAACA,OAAO,OAAO;IACnB,IAAI;QACF,OAAO,IAAIC,IAAID,OAAOE,MAAM;IAC9B,EAAE,eAAM;QACN,OAAO;IACT;AACF;AAEA;;;;;;;;;;;;;CAaC,GACD,OAAO,SAASC,qBACdC,IAAY,EACZC,QAAgB,EAChBC,aAAqB,EACrBrB,QAAoC;IAEpC,IAAI,CAACA,UAAU,OAAO;IACtB,MAAMiB,SAASH,gBAAgBO;IAC/B,IAAI,CAACJ,QAAQ,OAAO;IACpB,IAAIK;IACJ,IAAI;QACFA,MAAM,IAAIN,IAAIG,MAAMC;IACtB,EAAE,eAAM;QACN,OAAO;IACT;IACA,IAAIE,IAAIL,MAAM,KAAKA,QAAQ,OAAO;IAClC,KAAK,MAAMM,OAAOrC,oBAAqBoC,IAAIE,YAAY,CAACC,MAAM,CAACF;IAC/D,MAAMG,QAAQ,IAAIzB,gBAAgBd,yBAAyBa;IAC3D0B,MAAMC,OAAO,CAAC,CAACZ,OAAOQ,MAAQD,IAAIE,YAAY,CAACI,GAAG,CAACL,KAAKR;IACxD,MAAMc,OAAOP,IAAIQ,QAAQ;IACzB,OAAOD,SAASV,OAAO,OAAOU;AAChC;AAEA;;;;;;;;;;;;;;;;;CAiBC,GACD,OAAO,SAASE,0BAA0BC,OAEzC;IACC,IAAI,OAAOC,aAAa,eAAe,OAAOxC,WAAW,aAAa;QACpE,OAAO,IAAMyC;IACf;IACA,IAAI3C,kBAAkB,OAAO,IAAM2C;IACnC,MAAMjB,SAASH,gBAAgBkB,2BAAAA,QAASX,aAAa;IACrD,IAAI,CAACJ,QAAQ,OAAO,IAAMiB;IAE1B,MAAMC,aAAa,CAACC;QAClB,IAAI;YACF,MAAMC,SAASD,MAAMC,MAAM;YAC3B,IAAI,CAACA,UAAU,OAAOA,OAAOC,OAAO,KAAK,YAAY;YACrD,MAAMC,SAASF,OAAOC,OAAO,CAAC;YAC9B,IAAI,CAACC,QAAQ;YACb,MAAMC,YAAYtB,qBAChBqB,OAAOE,YAAY,CAAC,WAAW,IAC/BhD,OAAOa,QAAQ,CAACa,IAAI,EACpBF,QACAN;YAEF,IAAI6B,WAAWD,OAAOG,YAAY,CAAC,QAAQF;QAC7C,EAAE,eAAM;QACN,uEAAuE;QACvE,yEAAyE;QAC3E;IACF;IAEAjD,mBAAmB4C;IACnBF,SAASU,gBAAgB,CAAC,eAAeR,YAAY;IACrDF,SAASU,gBAAgB,CAAC,SAASR,YAAY;IAC/C,OAAOS;AACT;AAEA,2EAA2E,GAC3E,OAAO,SAASA;IACd,IAAIrD,oBAAoB,OAAO0C,aAAa,aAAa;QACvDA,SAASY,mBAAmB,CAAC,eAAetD,kBAAkB;QAC9D0C,SAASY,mBAAmB,CAAC,SAAStD,kBAAkB;IAC1D;IACAA,mBAAmB;IACnBD,iBAAiB;AACnB"}

package/src/lib/app-utils/contact-holder.d.ts

@@ -1,68 +0,0 @@
-/**
- * @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 ConsentGroup } from './consent-groups';
-/**
- * The holder of nothing: the group a contact is flattened through when no
- * site has captured it and no facet exists — a row written by a path that
- * predates attribution, read at the org level (AGL-2630).
- *
- * An empty `groupId` reads an empty facet (`readContactFacet` answers the
- * empty facet for a key the map lacks) and REFUSES a write
- * (`contactFacetPath` throws on an empty holder), which is the right pair:
- * the row still shows its shared identity, and nothing edits a facet
- * nobody holds. Exported so a surface can test for it rather than for an
- * empty string.
- */
-export declare const NO_HOLDER_GROUP: ConsentGroup;
-/**
- * The group a LEAD is read and acted on through (AGL-3278).
- *
- * The same question {@link contactPrimaryGroup} answers, with a shorter
- * answer: a lead is one flat document — no facets, one profile, one
- * status — so there is nothing to choose between and the holder is simply
- * the site that captured the person first. What it is FOR is the same: at
- * the organization level the record page has no viewing site, and it needs
- * one to read the consent basis against, to file an activity under, to
- * offer a booking on and to convert as.
- *
- * A lead no site has captured — a row imported before attribution — reads
- * through {@link NO_HOLDER_GROUP}, whose empty `hostId` is how a surface
- * asks "is there a site here at all" without testing for an empty string.
- */
-export declare function leadPrimaryGroup(lead: Record<string, unknown> | null | undefined, org: Record<string, unknown> | null | undefined): ConsentGroup;
-/**
- * The group a CROSS-HOLDER reader flattens one contact through (AGL-2630).
- *
- * Under a site there is one answer for every row — the site's own group,
- * `consentGroupForHost` — and the reader never asks this. At the
- * organization level there is no viewing site, and a contact captured by
- * three sites has up to three facets; the org-wide member reading them all
- * needs ONE to show the row's profile, owner and stage under, and to write
- * an edit back to. This picks the person's PRIMARY holder: the first
- * capturing site, in capture order, whose group actually holds a facet;
- * then any facet at all, resolved back to its declared group or to the
- * site whose id it is keyed by; then the first capturing site even with no
- * facet yet (the facet is written on the first edit). A row nobody captured
- * and nobody wrote a facet for reads through {@link NO_HOLDER_GROUP}.
- *
- * Capture order rather than sorted order, deliberately: `capturedByHostIds`
- * is maintained by `arrayUnion`, so its first entry is the site that met
- * the person first, and that site's profile is the one a person reading
- * across brands would expect to see. `contactCaptureHostIds` sorts the same
- * array for RENDERING, where a stable order matters more than a first.
- */
-export declare function contactPrimaryGroup(row: Record<string, unknown> | null | undefined, org: Record<string, unknown> | null | undefined): ConsentGroup;

package/src/lib/app-utils/contact-holder.js

@@ -1,129 +0,0 @@
-/**
- * @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.
- */ /**
- * WHICH HOLDER A CROSS-SITE READER SEES A CONTACT THROUGH (AGL-2630).
- *
- * A contact document carries one facet per holder, and every field but the
- * shared identity lives in one of them. A surface standing on a site reads
- * that site's group; a surface standing at the organization — the org-level
- * Contacts list, and the whole-collection export that writes the same file
- * — has no site to read as and needs one answer per row.
- *
- * In the library rather than in the CRM plugin because both of those
- * readers need it and one of them is an app: an app may not import a
- * feature plugin (AGL-2662).
- */ import { CONTACT_FACETS_FIELD } from "./contacts.js";
-import { CAPTURED_BY_HOST_FIELD } from "./marketing-consent.js";
-import { consentGroupForHost, consentGroupsAwaitConfirmation, readConsentGroups, soloConsentGroup } from "./consent-groups.js";
-/**
- * The holder of nothing: the group a contact is flattened through when no
- * site has captured it and no facet exists — a row written by a path that
- * predates attribution, read at the org level (AGL-2630).
- *
- * An empty `groupId` reads an empty facet (`readContactFacet` answers the
- * empty facet for a key the map lacks) and REFUSES a write
- * (`contactFacetPath` throws on an empty holder), which is the right pair:
- * the row still shows its shared identity, and nothing edits a facet
- * nobody holds. Exported so a surface can test for it rather than for an
- * empty string.
- */ export const NO_HOLDER_GROUP = Object.freeze({
-    hostId: '',
-    groupId: '',
-    name: null,
-    hostIds: [],
-    declared: false,
-    awaitsConfirmation: false
-});
-/**
- * The sites that captured this person, in CAPTURE order — the order
- * `arrayUnion` left, so the first entry is the site that met them first.
- *
- * `contactCaptureHostIds` sorts the same array for RENDERING, where a
- * stable order matters more than a first. Both readers below want the
- * first, so neither may use the sorted one.
- */ function captureOrder(record) {
-    const raw = (record != null ? record : {})[CAPTURED_BY_HOST_FIELD];
-    if (!Array.isArray(raw)) return [];
-    return raw.map((id)=>String(id != null ? id : '').trim()).filter(Boolean);
-}
-/**
- * The group a LEAD is read and acted on through (AGL-3278).
- *
- * The same question {@link contactPrimaryGroup} answers, with a shorter
- * answer: a lead is one flat document — no facets, one profile, one
- * status — so there is nothing to choose between and the holder is simply
- * the site that captured the person first. What it is FOR is the same: at
- * the organization level the record page has no viewing site, and it needs
- * one to read the consent basis against, to file an activity under, to
- * offer a booking on and to convert as.
- *
- * A lead no site has captured — a row imported before attribution — reads
- * through {@link NO_HOLDER_GROUP}, whose empty `hostId` is how a surface
- * asks "is there a site here at all" without testing for an empty string.
- */ export function leadPrimaryGroup(lead, org) {
-    const captured = captureOrder(lead);
-    return captured.length ? consentGroupForHost(org, captured[0]) : NO_HOLDER_GROUP;
-}
-/**
- * The group a CROSS-HOLDER reader flattens one contact through (AGL-2630).
- *
- * Under a site there is one answer for every row — the site's own group,
- * `consentGroupForHost` — and the reader never asks this. At the
- * organization level there is no viewing site, and a contact captured by
- * three sites has up to three facets; the org-wide member reading them all
- * needs ONE to show the row's profile, owner and stage under, and to write
- * an edit back to. This picks the person's PRIMARY holder: the first
- * capturing site, in capture order, whose group actually holds a facet;
- * then any facet at all, resolved back to its declared group or to the
- * site whose id it is keyed by; then the first capturing site even with no
- * facet yet (the facet is written on the first edit). A row nobody captured
- * and nobody wrote a facet for reads through {@link NO_HOLDER_GROUP}.
- *
- * Capture order rather than sorted order, deliberately: `capturedByHostIds`
- * is maintained by `arrayUnion`, so its first entry is the site that met
- * the person first, and that site's profile is the one a person reading
- * across brands would expect to see. `contactCaptureHostIds` sorts the same
- * array for RENDERING, where a stable order matters more than a first.
- */ export function contactPrimaryGroup(row, org) {
-    const record = row != null ? row : {};
-    const facets = record[CONTACT_FACETS_FIELD];
-    const facetKeys = facets && typeof facets === 'object' && !Array.isArray(facets) ? Object.keys(facets) : [];
-    const captured = captureOrder(record);
-    for (const hostId of captured){
-        const group = consentGroupForHost(org, hostId);
-        if (facetKeys.includes(group.groupId)) return group;
-    }
-    for (const key of facetKeys){
-        const declared = readConsentGroups(org)[key];
-        if (declared) {
-            return {
-                hostId: declared.hostIds[0],
-                groupId: key,
-                name: declared.name,
-                hostIds: [
-                    ...declared.hostIds
-                ],
-                declared: true,
-                awaitsConfirmation: consentGroupsAwaitConfirmation(org)
-            };
-        }
-        return soloConsentGroup(key);
-    }
-    if (captured.length) return consentGroupForHost(org, captured[0]);
-    return NO_HOLDER_GROUP;
-}
-
-//# sourceMappingURL=contact-holder.js.map

package/src/lib/app-utils/contact-holder.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/contact-holder.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 * WHICH HOLDER A CROSS-SITE READER SEES A CONTACT THROUGH (AGL-2630).\n *\n * A contact document carries one facet per holder, and every field but the\n * shared identity lives in one of them. A surface standing on a site reads\n * that site's group; a surface standing at the organization — the org-level\n * Contacts list, and the whole-collection export that writes the same file\n * — has no site to read as and needs one answer per row.\n *\n * In the library rather than in the CRM plugin because both of those\n * readers need it and one of them is an app: an app may not import a\n * feature plugin (AGL-2662).\n */\n\nimport { CONTACT_FACETS_FIELD } from './contacts'\nimport { CAPTURED_BY_HOST_FIELD } from './marketing-consent'\nimport {\n  type ConsentGroup,\n  consentGroupForHost,\n  consentGroupsAwaitConfirmation,\n  readConsentGroups,\n  soloConsentGroup,\n} from './consent-groups'\n\n/**\n * The holder of nothing: the group a contact is flattened through when no\n * site has captured it and no facet exists — a row written by a path that\n * predates attribution, read at the org level (AGL-2630).\n *\n * An empty `groupId` reads an empty facet (`readContactFacet` answers the\n * empty facet for a key the map lacks) and REFUSES a write\n * (`contactFacetPath` throws on an empty holder), which is the right pair:\n * the row still shows its shared identity, and nothing edits a facet\n * nobody holds. Exported so a surface can test for it rather than for an\n * empty string.\n */\nexport const NO_HOLDER_GROUP: ConsentGroup = Object.freeze({\n  hostId: '',\n  groupId: '',\n  name: null,\n  hostIds: [],\n  declared: false,\n  awaitsConfirmation: false,\n}) as ConsentGroup\n\n/**\n * The sites that captured this person, in CAPTURE order — the order\n * `arrayUnion` left, so the first entry is the site that met them first.\n *\n * `contactCaptureHostIds` sorts the same array for RENDERING, where a\n * stable order matters more than a first. Both readers below want the\n * first, so neither may use the sorted one.\n */\nfunction captureOrder(\n  record: Record<string, unknown> | null | undefined,\n): string[] {\n  const raw = (record ?? {})[CAPTURED_BY_HOST_FIELD]\n  if (!Array.isArray(raw)) return []\n  return raw.map((id) => String(id ?? '').trim()).filter(Boolean)\n}\n\n/**\n * The group a LEAD is read and acted on through (AGL-3278).\n *\n * The same question {@link contactPrimaryGroup} answers, with a shorter\n * answer: a lead is one flat document — no facets, one profile, one\n * status — so there is nothing to choose between and the holder is simply\n * the site that captured the person first. What it is FOR is the same: at\n * the organization level the record page has no viewing site, and it needs\n * one to read the consent basis against, to file an activity under, to\n * offer a booking on and to convert as.\n *\n * A lead no site has captured — a row imported before attribution — reads\n * through {@link NO_HOLDER_GROUP}, whose empty `hostId` is how a surface\n * asks \"is there a site here at all\" without testing for an empty string.\n */\nexport function leadPrimaryGroup(\n  lead: Record<string, unknown> | null | undefined,\n  org: Record<string, unknown> | null | undefined,\n): ConsentGroup {\n  const captured = captureOrder(lead)\n  return captured.length ? consentGroupForHost(org, captured[0]) : NO_HOLDER_GROUP\n}\n\n/**\n * The group a CROSS-HOLDER reader flattens one contact through (AGL-2630).\n *\n * Under a site there is one answer for every row — the site's own group,\n * `consentGroupForHost` — and the reader never asks this. At the\n * organization level there is no viewing site, and a contact captured by\n * three sites has up to three facets; the org-wide member reading them all\n * needs ONE to show the row's profile, owner and stage under, and to write\n * an edit back to. This picks the person's PRIMARY holder: the first\n * capturing site, in capture order, whose group actually holds a facet;\n * then any facet at all, resolved back to its declared group or to the\n * site whose id it is keyed by; then the first capturing site even with no\n * facet yet (the facet is written on the first edit). A row nobody captured\n * and nobody wrote a facet for reads through {@link NO_HOLDER_GROUP}.\n *\n * Capture order rather than sorted order, deliberately: `capturedByHostIds`\n * is maintained by `arrayUnion`, so its first entry is the site that met\n * the person first, and that site's profile is the one a person reading\n * across brands would expect to see. `contactCaptureHostIds` sorts the same\n * array for RENDERING, where a stable order matters more than a first.\n */\nexport function contactPrimaryGroup(\n  row: Record<string, unknown> | null | undefined,\n  org: Record<string, unknown> | null | undefined,\n): ConsentGroup {\n  const record = row ?? {}\n  const facets = record[CONTACT_FACETS_FIELD]\n  const facetKeys =\n    facets && typeof facets === 'object' && !Array.isArray(facets)\n      ? Object.keys(facets as Record<string, unknown>)\n      : []\n  const captured = captureOrder(record)\n  for (const hostId of captured) {\n    const group = consentGroupForHost(org, hostId)\n    if (facetKeys.includes(group.groupId)) return group\n  }\n  for (const key of facetKeys) {\n    const declared = readConsentGroups(org)[key]\n    if (declared) {\n      return {\n        hostId: declared.hostIds[0],\n        groupId: key,\n        name: declared.name,\n        hostIds: [...declared.hostIds],\n        declared: true,\n        awaitsConfirmation: consentGroupsAwaitConfirmation(org),\n      }\n    }\n    return soloConsentGroup(key)\n  }\n  if (captured.length) return consentGroupForHost(org, captured[0])\n  return NO_HOLDER_GROUP\n}"],"names":["CONTACT_FACETS_FIELD","CAPTURED_BY_HOST_FIELD","consentGroupForHost","consentGroupsAwaitConfirmation","readConsentGroups","soloConsentGroup","NO_HOLDER_GROUP","Object","freeze","hostId","groupId","name","hostIds","declared","awaitsConfirmation","captureOrder","record","raw","Array","isArray","map","id","String","trim","filter","Boolean","leadPrimaryGroup","lead","org","captured","length","contactPrimaryGroup","row","facets","facetKeys","keys","group","includes","key"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;CAYC,GAED,SAASA,oBAAoB,QAAQ,gBAAY;AACjD,SAASC,sBAAsB,QAAQ,yBAAqB;AAC5D,SAEEC,mBAAmB,EACnBC,8BAA8B,EAC9BC,iBAAiB,EACjBC,gBAAgB,QACX,sBAAkB;AAEzB;;;;;;;;;;;CAWC,GACD,OAAO,MAAMC,kBAAgCC,OAAOC,MAAM,CAAC;IACzDC,QAAQ;IACRC,SAAS;IACTC,MAAM;IACNC,SAAS,EAAE;IACXC,UAAU;IACVC,oBAAoB;AACtB,GAAkB;AAElB;;;;;;;CAOC,GACD,SAASC,aACPC,MAAkD;IAElD,MAAMC,MAAM,CAACD,iBAAAA,SAAU,CAAC,EAAE,CAACf,uBAAuB;IAClD,IAAI,CAACiB,MAAMC,OAAO,CAACF,MAAM,OAAO,EAAE;IAClC,OAAOA,IAAIG,GAAG,CAAC,CAACC,KAAOC,OAAOD,aAAAA,KAAM,IAAIE,IAAI,IAAIC,MAAM,CAACC;AACzD;AAEA;;;;;;;;;;;;;;CAcC,GACD,OAAO,SAASC,iBACdC,IAAgD,EAChDC,GAA+C;IAE/C,MAAMC,WAAWd,aAAaY;IAC9B,OAAOE,SAASC,MAAM,GAAG5B,oBAAoB0B,KAAKC,QAAQ,CAAC,EAAE,IAAIvB;AACnE;AAEA;;;;;;;;;;;;;;;;;;;;CAoBC,GACD,OAAO,SAASyB,oBACdC,GAA+C,EAC/CJ,GAA+C;IAE/C,MAAMZ,SAASgB,cAAAA,MAAO,CAAC;IACvB,MAAMC,SAASjB,MAAM,CAAChB,qBAAqB;IAC3C,MAAMkC,YACJD,UAAU,OAAOA,WAAW,YAAY,CAACf,MAAMC,OAAO,CAACc,UACnD1B,OAAO4B,IAAI,CAACF,UACZ,EAAE;IACR,MAAMJ,WAAWd,aAAaC;IAC9B,KAAK,MAAMP,UAAUoB,SAAU;QAC7B,MAAMO,QAAQlC,oBAAoB0B,KAAKnB;QACvC,IAAIyB,UAAUG,QAAQ,CAACD,MAAM1B,OAAO,GAAG,OAAO0B;IAChD;IACA,KAAK,MAAME,OAAOJ,UAAW;QAC3B,MAAMrB,WAAWT,kBAAkBwB,IAAI,CAACU,IAAI;QAC5C,IAAIzB,UAAU;YACZ,OAAO;gBACLJ,QAAQI,SAASD,OAAO,CAAC,EAAE;gBAC3BF,SAAS4B;gBACT3B,MAAME,SAASF,IAAI;gBACnBC,SAAS;uBAAIC,SAASD,OAAO;iBAAC;gBAC9BC,UAAU;gBACVC,oBAAoBX,+BAA+ByB;YACrD;QACF;QACA,OAAOvB,iBAAiBiC;IAC1B;IACA,IAAIT,SAASC,MAAM,EAAE,OAAO5B,oBAAoB0B,KAAKC,QAAQ,CAAC,EAAE;IAChE,OAAOvB;AACT"}

package/src/lib/app-utils/contact-merge.d.ts

@@ -1,136 +0,0 @@
-/**
- * @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.
- */
-/**
- * MERGING TWO CONTACT DOCUMENTS INTO ONE (AGL-2625) — the pure half.
- *
- * Contacts are keyed by email, so exact duplicates cannot exist; one human
- * with `jane@acme.com` and `jane@gmail.com` is two documents, with tags,
- * deals, tasks and a timeline split between them. A merge folds the second
- * into the first: the SURVIVOR keeps its address as the identity, the MERGED
- * record's address becomes an alternate on it, and every field is combined
- * by one rule the dialog can show before the write happens.
- *
- * ## The rule
- *
- *  - A scalar — a name, a phone, a title, a stage, an owner — is the
- *    survivor's where the survivor has one, and fills from the merged record
- *    where the survivor is empty. Nothing the survivor holds is overwritten.
- *  - A list — tags, campaign filings, the timeline, the sites that captured
- *    the person, the forms, the companies — is the UNION, deduplicated and
- *    bounded where the write paths bound it.
- *  - A figure that counts something — orders, lifetime value, refunds — is
- *    the SUM: two records of one person's purchases are one person's
- *    purchases. A "first" is the earlier, a "last" is the later.
- *  - Notes are appended, survivor first: a note is a list of sentences, and
- *    dropping the merged record's would be the one silent loss in a merge
- *    that is otherwise lossless.
- *  - A recorded REFUSAL of marketing mail on either record stands on the
- *    survivor. The merge asserts the two are one person, and that person
- *    said no.
- *
- * Applied per holder: each group's facet on the merged record is folded
- * into the same group's facet on the survivor, and a group only the merged
- * record had comes across whole. No holder's records reach another holder's
- * facet, which is the guarantee the facet shape exists for.
- *
- * ## Why this is a plan and not a write
- *
- * The console shows the two records side by side and says which value wins
- * before anything is committed; the server performs the write. Both read
- * this function, so the preview cannot show one outcome and the write land
- * another. The plan is plain values — no sentinels — so it can be rendered,
- * and it is shaped for a merge-`set`, which deep-merges the facet map one
- * holder at a time and replaces an array whole: exactly the two behaviors
- * the rule above needs.
- */
-import { type ContactInteraction } from './contacts';
-export interface ContactMergePlan {
-    /**
-     * What the survivor becomes, as a merge-`set` payload: every derived
-     * field with its full value, and only the groups the merged record held
-     * under `facets`. Plain values throughout — the writer adds its own
-     * `updatedAt`.
-     */
-    survivor: Record<string, unknown>;
-    /** Every address the survivor answers to afterwards, primary first. */
-    emails: string[];
-    /** The merged record's addresses — what its leads and index entries are keyed by. */
-    mergedEmails: string[];
-    /**
-     * The companies that lose a contact: those BOTH records were filed under,
-     * which counted two people and now count one. A company only one record
-     * named keeps its count — the survivor still names it.
-     */
-    companyCounts: Array<{
-        companyId: string;
-        delta: -1;
-    }>;
-    /** The union of both records' scope tokens — who may read the survivor. */
-    visibleTo: string[];
-}
-type Doc = Record<string, unknown>;
-/**
- * Both timelines as one: deduplicated by event, newest first, and capped
- * the way every capture caps it — so a merge of two full timelines keeps
- * the fifty most recent visits rather than growing the document past what
- * a capture may write.
- */
-export declare function mergeInteractions(survivor: readonly ContactInteraction[] | undefined, merged: readonly ContactInteraction[] | undefined): ContactInteraction[];
-/**
- * One holder's facet after the merge.
- *
- * `survivor` is that holder's facet on the surviving record — possibly
- * absent, when only the merged record was held by this group — and `merged`
- * the same holder's facet on the record being folded in.
- */
-export declare function mergeContactFacet(survivor: Doc | undefined, merged: Doc | undefined): Doc;
-/**
- * The plan for folding `merged` into `survivor`.
- *
- * Both are the stored documents as read. The survivor's `email` is the
- * identity that stands; the merged record's becomes an alternate.
- */
-export declare function planContactMerge(survivor: Doc, merged: Doc): ContactMergePlan;
-/** Where a previewed value comes from. */
-export type ContactMergeSource = 'survivor' | 'merged' | 'both' | 'none';
-/** One line of the side-by-side the dialog shows. */
-export interface ContactMergePreviewRow {
-    key: string;
-    label: string;
-    /** The surviving record's value, as text. */
-    survivor: string;
-    /** The merged record's value, as text. */
-    merged: string;
-    /** What the survivor carries afterwards. */
-    result: string;
-    from: ContactMergeSource;
-}
-export interface ContactMergePreviewOptions {
-    /** The owner's display name for a uid; the uid itself when absent. */
-    memberName?: (uid: string) => string;
-}
-/**
- * The merge as the viewing group would see it, field by field.
- *
- * Reads through ONE group's facet, the way the record page does, so a
- * holder previewing a merge sees its own values and never another holder's.
- * Every row carries the survivor's value, the merged record's, and the
- * result the plan would write, so the dialog is a rendering and not a second
- * opinion.
- */
-export declare function contactMergePreview(survivor: Doc, merged: Doc, groupId: string, options?: ContactMergePreviewOptions): ContactMergePreviewRow[];
-export {};