@lssm/lib.overlay-engine 0.1.2 → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import { AddHelpTextModification, HideFieldModification, MakeRequiredModification, OVERLAY_SCOPE_ORDER, OverlayAppliesTo, OverlayFieldModificationBase, OverlayInput, OverlayModification, OverlayScopeContext, OverlayScopeKey, OverlaySignatureAlgorithm, OverlaySignatureBlock, OverlaySpec, OverlayTargetRef, RenameLabelModification, ReorderFieldsModification, SetDefaultModification, SignedOverlaySpec, defineOverlay } from "./spec.js";
+import { OverlayAuditEvent, OverlayLayoutConfig, OverlayMatchContext, OverlayRenderable, OverlayRenderableField } from "./types.js";
+import { OverlayValidationIssue, OverlayValidationResult, OverlayValidator, assertOverlayValid, defaultOverlayValidator, validateOverlaySpec } from "./validator.js";
+import { OverlayLookup, OverlayRegistry, OverlayRegistryOptions } from "./registry.js";
+import { ApplyOverlayOptions, applyOverlayModifications } from "./merger.js";
+import { OverlayApplyParams, OverlayEngine, OverlayEngineOptions, OverlayRuntimeResult } from "./runtime.js";
+import { SignOverlayOptions, canonicalizeOverlay, signOverlay, stripSignature, verifyOverlaySignature } from "./signer.js";
+export { AddHelpTextModification, ApplyOverlayOptions, HideFieldModification, MakeRequiredModification, OVERLAY_SCOPE_ORDER, OverlayAppliesTo, OverlayApplyParams, OverlayAuditEvent, OverlayEngine, OverlayEngineOptions, OverlayFieldModificationBase, OverlayInput, OverlayLayoutConfig, OverlayLookup, OverlayMatchContext, OverlayModification, OverlayRegistry, OverlayRegistryOptions, OverlayRenderable, OverlayRenderableField, OverlayRuntimeResult, OverlayScopeContext, OverlayScopeKey, OverlaySignatureAlgorithm, OverlaySignatureBlock, OverlaySpec, OverlayTargetRef, OverlayValidationIssue, OverlayValidationResult, OverlayValidator, RenameLabelModification, ReorderFieldsModification, SetDefaultModification, SignOverlayOptions, SignedOverlaySpec, applyOverlayModifications, assertOverlayValid, canonicalizeOverlay, defaultOverlayValidator, defineOverlay, signOverlay, stripSignature, validateOverlaySpec, verifyOverlaySignature };

package/dist/index.js

@@ -0,0 +1 @@
+import{OVERLAY_SCOPE_ORDER as e,defineOverlay as t}from"./spec.js";import{assertOverlayValid as n,defaultOverlayValidator as r,validateOverlaySpec as i}from"./validator.js";import{OverlayRegistry as a}from"./registry.js";import{applyOverlayModifications as o}from"./merger.js";import{OverlayEngine as s}from"./runtime.js";import{canonicalizeOverlay as c,signOverlay as l,stripSignature as u,verifyOverlaySignature as d}from"./signer.js";export{e as OVERLAY_SCOPE_ORDER,s as OverlayEngine,a as OverlayRegistry,o as applyOverlayModifications,n as assertOverlayValid,c as canonicalizeOverlay,r as defaultOverlayValidator,t as defineOverlay,l as signOverlay,u as stripSignature,i as validateOverlaySpec,d as verifyOverlaySignature};

package/dist/merger.d.ts

@@ -0,0 +1,11 @@
+import { SignedOverlaySpec } from "./spec.js";
+import { OverlayRenderable } from "./types.js";
+
+//#region src/merger.d.ts
+interface ApplyOverlayOptions {
+  strict?: boolean;
+}
+declare function applyOverlayModifications<T extends OverlayRenderable>(target: T, overlays: SignedOverlaySpec[], options?: ApplyOverlayOptions): T;
+//#endregion
+export { ApplyOverlayOptions, applyOverlayModifications };
+//# sourceMappingURL=merger.d.ts.map

package/dist/merger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merger.d.ts","names":[],"sources":["../src/merger.ts"],"sourcesContent":[],"mappings":";;;;UAGiB,mBAAA;;AAAjB;AAUgB,iBAAA,yBAAyB,CAAA,UAAW,iBAAX,CAAA,CAAA,MAAA,EAC/B,CAD+B,EAAA,QAAA,EAE7B,iBAF6B,EAAA,EAAA,OAAA,CAAA,EAG9B,mBAH8B,CAAA,EAItC,CAJsC"}

package/dist/merger.js

@@ -0,0 +1,2 @@
+function e(e,r,i={}){if(!r.length)return e;let a=e.fields.map(e=>({key:e.key,field:{...e},hidden:e.visible===!1})),o=new Map(a.map(e=>[e.key,e])),s=e.fields.map(e=>e.key),c=(e,t)=>{if(i.strict)throw Error(`Overlay "${t}" referenced unknown field "${e}".`)};r.forEach(e=>{e.modifications.forEach(r=>{switch(r.type){case`hideField`:{let t=o.get(r.field);if(!t)return c(r.field,e.overlayId);t.hidden=!0,t.field.visible=!1;break}case`renameLabel`:{let t=o.get(r.field);if(!t)return c(r.field,e.overlayId);t.field.label=r.newLabel;break}case`setDefault`:{let t=o.get(r.field);if(!t)return c(r.field,e.overlayId);t.field.defaultValue=r.value;break}case`addHelpText`:{let t=o.get(r.field);if(!t)return c(r.field,e.overlayId);t.field.helpText=r.text;break}case`makeRequired`:{let t=o.get(r.field);if(!t)return c(r.field,e.overlayId);t.field.required=r.required??!0;break}case`reorderFields`:{let{filtered:a,missing:l}=t(r.fields,o);l.length&&i.strict&&l.forEach(t=>c(t,e.overlayId)),s=n(s,a);break}default:break}})});let l=[],u=new Set;return s.forEach(e=>{let t=o.get(e);!t||t.hidden||(u.add(e),l.push(t.field))}),a.forEach(e=>{e.hidden||u.has(e.key)||l.push(e.field)}),l.forEach((e,t)=>{e.order=t,e.visible=!0}),{...e,fields:l}}function t(e,t){let n=[],r=[],i=new Set;return e.forEach(e=>{if(e?.trim()){if(!t.has(e)){r.push(e);return}i.has(e)||(i.add(e),n.push(e))}}),{filtered:n,missing:r}}function n(e,t){if(!t.length)return e;let n=new Set(t),r=e.filter(e=>!n.has(e));return[...t,...r]}export{e as applyOverlayModifications};
+//# sourceMappingURL=merger.js.map

package/dist/merger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merger.js","names":["visibleFields: OverlayRenderableField[]","filtered: string[]","missing: string[]"],"sources":["../src/merger.ts"],"sourcesContent":["import type { SignedOverlaySpec } from './spec';\nimport type { OverlayRenderable, OverlayRenderableField } from './types';\n\nexport interface ApplyOverlayOptions {\n  strict?: boolean;\n}\n\ninterface FieldState<TField extends OverlayRenderableField> {\n  key: string;\n  field: TField;\n  hidden: boolean;\n}\n\nexport function applyOverlayModifications<T extends OverlayRenderable>(\n  target: T,\n  overlays: SignedOverlaySpec[],\n  options: ApplyOverlayOptions = {}\n): T {\n  if (!overlays.length) {\n    return target;\n  }\n\n  const states = target.fields.map<FieldState<any>>((field) => ({\n    key: field.key,\n    field: { ...field },\n    hidden: field.visible === false,\n  }));\n\n  const fieldMap = new Map(states.map((state) => [state.key, state]));\n  let orderSequence = target.fields.map((field) => field.key);\n\n  const handleMissing = (field: string, overlayId: string) => {\n    if (options.strict) {\n      throw new Error(\n        `Overlay \"${overlayId}\" referenced unknown field \"${field}\".`\n      );\n    }\n  };\n\n  overlays.forEach((overlay) => {\n    overlay.modifications.forEach((modification) => {\n      switch (modification.type) {\n        case 'hideField': {\n          const state = fieldMap.get(modification.field);\n          if (!state)\n            return handleMissing(modification.field, overlay.overlayId);\n          state.hidden = true;\n          state.field.visible = false;\n          break;\n        }\n        case 'renameLabel': {\n          const state = fieldMap.get(modification.field);\n          if (!state)\n            return handleMissing(modification.field, overlay.overlayId);\n          state.field.label = modification.newLabel;\n          break;\n        }\n        case 'setDefault': {\n          const state = fieldMap.get(modification.field);\n          if (!state)\n            return handleMissing(modification.field, overlay.overlayId);\n          state.field.defaultValue = modification.value;\n          break;\n        }\n        case 'addHelpText': {\n          const state = fieldMap.get(modification.field);\n          if (!state)\n            return handleMissing(modification.field, overlay.overlayId);\n          state.field.helpText = modification.text;\n          break;\n        }\n        case 'makeRequired': {\n          const state = fieldMap.get(modification.field);\n          if (!state)\n            return handleMissing(modification.field, overlay.overlayId);\n          state.field.required = modification.required ?? true;\n          break;\n        }\n        case 'reorderFields': {\n          const { filtered, missing } = normalizeOrderList(\n            modification.fields,\n            fieldMap\n          );\n          if (missing.length && options.strict) {\n            missing.forEach((field) => handleMissing(field, overlay.overlayId));\n          }\n          orderSequence = applyReorder(orderSequence, filtered);\n          break;\n        }\n        default:\n          break;\n      }\n    });\n  });\n\n  const visibleFields: OverlayRenderableField[] = [];\n  const seen = new Set<string>();\n  orderSequence.forEach((key) => {\n    const state = fieldMap.get(key);\n    if (!state || state.hidden) {\n      return;\n    }\n    seen.add(key);\n    visibleFields.push(state.field);\n  });\n\n  // Handle any fields introduced dynamically that were not part of the original sequence.\n  states.forEach((state) => {\n    if (state.hidden || seen.has(state.key)) {\n      return;\n    }\n    visibleFields.push(state.field);\n  });\n\n  visibleFields.forEach((field, index) => {\n    field.order = index;\n    field.visible = true;\n  });\n\n  return {\n    ...(target as T),\n    fields: visibleFields as T['fields'],\n  };\n}\n\nfunction normalizeOrderList(\n  fields: string[],\n  fieldMap: Map<string, FieldState<any>>\n): { filtered: string[]; missing: string[] } {\n  const filtered: string[] = [];\n  const missing: string[] = [];\n  const seen = new Set<string>();\n\n  fields.forEach((field) => {\n    if (!field?.trim()) {\n      return;\n    }\n    if (!fieldMap.has(field)) {\n      missing.push(field);\n      return;\n    }\n    if (seen.has(field)) {\n      return;\n    }\n    seen.add(field);\n    filtered.push(field);\n  });\n\n  return { filtered, missing };\n}\n\nfunction applyReorder(sequence: string[], orderedFields: string[]): string[] {\n  if (!orderedFields.length) {\n    return sequence;\n  }\n  const orderedSet = new Set(orderedFields);\n  const remainder = sequence.filter((key) => !orderedSet.has(key));\n  return [...orderedFields, ...remainder];\n}\n"],"mappings":"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"}

package/dist/react.d.ts

@@ -0,0 +1,10 @@
+import { OverlayRenderable } from "./types.js";
+import { OverlayApplyParams, OverlayEngine, OverlayRuntimeResult } from "./runtime.js";
+import { DependencyList } from "react";
+
+//#region src/react.d.ts
+declare function useOverlay<T extends OverlayRenderable>(engine: OverlayEngine | undefined, params: OverlayApplyParams<T>, deps?: DependencyList): OverlayRuntimeResult<T>;
+declare function useOverlayFields<T extends OverlayRenderable>(engine: OverlayEngine | undefined, params: OverlayApplyParams<T>, deps?: DependencyList): T['fields'];
+//#endregion
+export { useOverlay, useOverlayFields };
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","names":[],"sources":["../src/react.ts"],"sourcesContent":[],"mappings":";;;;;iBAKgB,qBAAqB,2BAC3B,mCACA,mBAAmB,WACrB,iBACL,qBAAqB;AAJR,iBAgBA,gBAhBU,CAAA,UAgBiB,iBAhBjB,CAAA,CAAA,MAAA,EAiBhB,aAjBgB,GAAA,SAAA,EAAA,MAAA,EAkBhB,kBAlBgB,CAkBG,CAlBH,CAAA,EAAA,IAAA,CAAA,EAmBlB,cAnBkB,CAAA,EAoBvB,CApBuB,CAAA,QAAA,CAAA"}

package/dist/react.js

@@ -0,0 +1,2 @@
+import{useMemo as e}from"react";function t(t,n,r=[]){return e(()=>t?t.apply(n):{target:n.target,overlaysApplied:[]},[t,n,...r])}function n(e,n,r=[]){return t(e,n,r).target.fields}export{t as useOverlay,n as useOverlayFields};
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","names":[],"sources":["../src/react.ts"],"sourcesContent":["import { useMemo, type DependencyList } from 'react';\nimport type { OverlayRenderable } from './types';\nimport type { OverlayApplyParams, OverlayRuntimeResult } from './runtime';\nimport { OverlayEngine } from './runtime';\n\nexport function useOverlay<T extends OverlayRenderable>(\n  engine: OverlayEngine | undefined,\n  params: OverlayApplyParams<T>,\n  deps: DependencyList = []\n): OverlayRuntimeResult<T> {\n  return useMemo(() => {\n    if (!engine) {\n      return {\n        target: params.target,\n        overlaysApplied: [],\n      };\n    }\n    return engine.apply(params);\n  }, [engine, params, ...deps]);\n}\n\nexport function useOverlayFields<T extends OverlayRenderable>(\n  engine: OverlayEngine | undefined,\n  params: OverlayApplyParams<T>,\n  deps: DependencyList = []\n): T['fields'] {\n  const result = useOverlay(engine, params, deps);\n  return result.target.fields;\n}\n"],"mappings":"gCAKA,SAAgB,EACd,EACA,EACA,EAAuB,EAAE,CACA,CACzB,OAAO,MACA,EAME,EAAO,MAAM,EAAO,CALlB,CACL,OAAQ,EAAO,OACf,gBAAiB,EAAE,CACpB,CAGF,CAAC,EAAQ,EAAQ,GAAG,EAAK,CAAC,CAG/B,SAAgB,EACd,EACA,EACA,EAAuB,EAAE,CACZ,CAEb,OADe,EAAW,EAAQ,EAAQ,EAAK,CACjC,OAAO"}

package/dist/registry.d.ts

@@ -0,0 +1,28 @@
+import { OverlayInput, OverlayScopeContext, OverlayTargetRef, SignedOverlaySpec } from "./spec.js";
+import { OverlayValidator } from "./validator.js";
+
+//#region src/registry.d.ts
+interface OverlayRegistryOptions {
+  validator?: OverlayValidator;
+  allowUnsigned?: boolean;
+}
+interface OverlayLookup extends OverlayScopeContext, OverlayTargetRef {}
+declare class OverlayRegistry {
+  private readonly options;
+  private readonly overlays;
+  constructor(options?: OverlayRegistryOptions);
+  register(overlay: OverlayInput, options?: {
+    skipValidation?: boolean;
+  }): SignedOverlaySpec;
+  unregister(overlayId: string, version?: string): void;
+  list(): SignedOverlaySpec[];
+  get(overlayId: string, version: string): SignedOverlaySpec | undefined;
+  forContext(query: OverlayLookup): SignedOverlaySpec[];
+  clear(): void;
+  size(): number;
+  private ensureSigned;
+  private getKey;
+}
+//#endregion
+export { OverlayLookup, OverlayRegistry, OverlayRegistryOptions };
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","names":[],"sources":["../src/registry.ts"],"sourcesContent":[],"mappings":";;;;UAUiB,sBAAA;cACH;EADG,aAAA,CAAA,EAAA,OAAA;AAKjB;AAwBa,UAxBI,aAAA,SAAsB,mBAwBX,EAxBgC,gBAwBhC,CAAA;AAMf,cANA,eAAA,CAMA;EAER,iBAAA,OAAA;EAsCK,iBAAA,QAAA;EAIiC,WAAA,CAAA,OAAA,CAAA,EA/CH,sBA+CG;EAIvB,QAAA,CAAA,OAAA,EAhDP,YAgDO,EAAA,OAAiC,CAAjC,EAAA;IAAgB,cAAA,CAAA,EAAA,OAAA;EAAiB,CAAA,CAAA,EA9ChD,iBA8CgD;;UAR3C;2CAIiC;oBAIvB,gBAAgB"}

package/dist/registry.js

@@ -0,0 +1,2 @@
+import{defaultOverlayValidator as e}from"./validator.js";const t=[`capability`,`workflow`,`dataView`,`presentation`,`operation`],n={tenantId:8,role:4,userId:16,device:2,tags:1};var r=class{overlays=new Map;constructor(e={}){this.options=e}register(t,n){if(!n?.skipValidation){let n=(this.options.validator??e)(t);if(!n.valid){let e=n.issues.map(e=>`${e.code}: ${e.message}`).join(`; `);throw Error(`Overlay "${t.overlayId}" failed validation: ${e}`)}}let r=this.ensureSigned(t),i=this.getKey(r.overlayId,r.version),o={overlay:r,specificity:a(r.appliesTo),registeredAt:Date.now()};return this.overlays.set(i,o),r}unregister(e,t){if(t){this.overlays.delete(this.getKey(e,t));return}for(let t of Array.from(this.overlays.keys()))t.startsWith(`${e}@`)&&this.overlays.delete(t)}list(){return Array.from(this.overlays.values()).map(e=>e.overlay)}get(e,t){return this.overlays.get(this.getKey(e,t))?.overlay}forContext(e){return Array.from(this.overlays.values()).filter(t=>o(t.overlay.appliesTo,e)).sort((e,t)=>e.specificity===t.specificity?e.registeredAt-t.registeredAt:e.specificity-t.specificity).map(e=>e.overlay)}clear(){this.overlays.clear()}size(){return this.overlays.size}ensureSigned(e){if(i(e)){if(!e.signature?.signature&&!this.options.allowUnsigned)throw Error(`Overlay "${e.overlayId}" is missing a signature.`);return e}if(!this.options.allowUnsigned)throw Error(`Overlay "${e.overlayId}" must be signed before registration.`);return e}getKey(e,t){return`${e}@${t}`}};function i(e){return!!e.signature}function a(e){let t=0;return Object.keys(n).forEach(r=>{(r===`tags`?Array.isArray(e.tags)&&e.tags.length>0:e[r])&&(t+=n[r])}),t}function o(e,n){for(let r of t){let t=e[r];if(t&&t!==n[r])return!1}if(e.tenantId&&e.tenantId!==n.tenantId||e.role&&e.role!==n.role||e.userId&&e.userId!==n.userId||e.device&&e.device!==n.device)return!1;if(e.tags?.length){if(!n.tags?.length)return!1;let t=new Set(n.tags);if(!e.tags.every(e=>t.has(e)))return!1}return!0}export{r as OverlayRegistry};
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","names":["TARGET_KEYS: (keyof OverlayTargetRef)[]","SCOPE_WEIGHTS: Record<keyof OverlayScopeContext, number>","options: OverlayRegistryOptions","stored: StoredOverlay"],"sources":["../src/registry.ts"],"sourcesContent":["import type {\n  OverlayInput,\n  OverlayAppliesTo,\n  OverlayScopeContext,\n  OverlayTargetRef,\n  SignedOverlaySpec,\n} from './spec';\nimport type { OverlayValidator } from './validator';\nimport { defaultOverlayValidator } from './validator';\n\nexport interface OverlayRegistryOptions {\n  validator?: OverlayValidator;\n  allowUnsigned?: boolean;\n}\n\nexport interface OverlayLookup extends OverlayScopeContext, OverlayTargetRef {}\n\ninterface StoredOverlay {\n  overlay: SignedOverlaySpec;\n  specificity: number;\n  registeredAt: number;\n}\n\nconst TARGET_KEYS: (keyof OverlayTargetRef)[] = [\n  'capability',\n  'workflow',\n  'dataView',\n  'presentation',\n  'operation',\n];\n\nconst SCOPE_WEIGHTS: Record<keyof OverlayScopeContext, number> = {\n  tenantId: 8,\n  role: 4,\n  userId: 16,\n  device: 2,\n  tags: 1,\n};\n\nexport class OverlayRegistry {\n  private readonly overlays = new Map<string, StoredOverlay>();\n\n  constructor(private readonly options: OverlayRegistryOptions = {}) {}\n\n  register(\n    overlay: OverlayInput,\n    options?: { skipValidation?: boolean }\n  ): SignedOverlaySpec {\n    if (!options?.skipValidation) {\n      const validator = this.options.validator ?? defaultOverlayValidator;\n      const result = validator(overlay as SignedOverlaySpec);\n      if (!result.valid) {\n        const reason = result.issues\n          .map((issue) => `${issue.code}: ${issue.message}`)\n          .join('; ');\n        throw new Error(\n          `Overlay \"${overlay.overlayId}\" failed validation: ${reason}`\n        );\n      }\n    }\n\n    const normalized = this.ensureSigned(overlay);\n    const key = this.getKey(normalized.overlayId, normalized.version);\n    const stored: StoredOverlay = {\n      overlay: normalized,\n      specificity: computeSpecificity(normalized.appliesTo),\n      registeredAt: Date.now(),\n    };\n    this.overlays.set(key, stored);\n    return normalized;\n  }\n\n  unregister(overlayId: string, version?: string) {\n    if (version) {\n      this.overlays.delete(this.getKey(overlayId, version));\n      return;\n    }\n\n    for (const key of Array.from(this.overlays.keys())) {\n      if (key.startsWith(`${overlayId}@`)) {\n        this.overlays.delete(key);\n      }\n    }\n  }\n\n  list(): SignedOverlaySpec[] {\n    return Array.from(this.overlays.values()).map((entry) => entry.overlay);\n  }\n\n  get(overlayId: string, version: string): SignedOverlaySpec | undefined {\n    return this.overlays.get(this.getKey(overlayId, version))?.overlay;\n  }\n\n  forContext(query: OverlayLookup): SignedOverlaySpec[] {\n    return Array.from(this.overlays.values())\n      .filter((entry) => matches(entry.overlay.appliesTo, query))\n      .sort((a, b) => {\n        if (a.specificity !== b.specificity) {\n          return a.specificity - b.specificity;\n        }\n        return a.registeredAt - b.registeredAt;\n      })\n      .map((entry) => entry.overlay);\n  }\n\n  clear() {\n    this.overlays.clear();\n  }\n\n  size(): number {\n    return this.overlays.size;\n  }\n\n  private ensureSigned(input: OverlayInput): SignedOverlaySpec {\n    if (isSignedOverlay(input)) {\n      if (!input.signature?.signature && !this.options.allowUnsigned) {\n        throw new Error(`Overlay \"${input.overlayId}\" is missing a signature.`);\n      }\n      return input;\n    }\n\n    if (!this.options.allowUnsigned) {\n      throw new Error(\n        `Overlay \"${input.overlayId}\" must be signed before registration.`\n      );\n    }\n\n    return input as SignedOverlaySpec;\n  }\n\n  private getKey(overlayId: string, version: string) {\n    return `${overlayId}@${version}`;\n  }\n}\n\nfunction isSignedOverlay(spec: OverlayInput): spec is SignedOverlaySpec {\n  return Boolean((spec as SignedOverlaySpec).signature);\n}\n\nfunction computeSpecificity(appliesTo: OverlayAppliesTo): number {\n  let score = 0;\n  (Object.keys(SCOPE_WEIGHTS) as (keyof OverlayScopeContext)[]).forEach(\n    (key) => {\n      const hasValue =\n        key === 'tags'\n          ? Array.isArray(appliesTo.tags) && appliesTo.tags.length > 0\n          : Boolean(appliesTo[key]);\n      if (hasValue) {\n        score += SCOPE_WEIGHTS[key];\n      }\n    }\n  );\n  return score;\n}\n\nfunction matches(appliesTo: OverlayAppliesTo, ctx: OverlayLookup): boolean {\n  for (const key of TARGET_KEYS) {\n    const expected = appliesTo[key];\n    if (expected && expected !== ctx[key]) {\n      return false;\n    }\n  }\n\n  if (appliesTo.tenantId && appliesTo.tenantId !== ctx.tenantId) {\n    return false;\n  }\n  if (appliesTo.role && appliesTo.role !== ctx.role) {\n    return false;\n  }\n  if (appliesTo.userId && appliesTo.userId !== ctx.userId) {\n    return false;\n  }\n  if (appliesTo.device && appliesTo.device !== ctx.device) {\n    return false;\n  }\n  if (appliesTo.tags?.length) {\n    if (!ctx.tags?.length) {\n      return false;\n    }\n    const ctxTags = new Set(ctx.tags);\n    const satisfies = appliesTo.tags.every((tag) => ctxTags.has(tag));\n    if (!satisfies) {\n      return false;\n    }\n  }\n\n  return true;\n}\n"],"mappings":"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"}

package/dist/runtime.d.ts

@@ -0,0 +1,28 @@
+import { SignedOverlaySpec } from "./spec.js";
+import { OverlayAuditEvent, OverlayRenderable } from "./types.js";
+import { OverlayLookup, OverlayRegistry } from "./registry.js";
+import { ApplyOverlayOptions } from "./merger.js";
+
+//#region src/runtime.d.ts
+interface OverlayEngineOptions {
+  registry: OverlayRegistry;
+  audit?: (event: OverlayAuditEvent) => void;
+}
+interface OverlayApplyParams<T extends OverlayRenderable> extends OverlayLookup {
+  target: T;
+  overlays?: SignedOverlaySpec[];
+  strict?: ApplyOverlayOptions['strict'];
+}
+interface OverlayRuntimeResult<T extends OverlayRenderable> {
+  target: T;
+  overlaysApplied: SignedOverlaySpec[];
+}
+declare class OverlayEngine {
+  private readonly registry;
+  private readonly audit?;
+  constructor(options: OverlayEngineOptions);
+  apply<T extends OverlayRenderable>(params: OverlayApplyParams<T>): OverlayRuntimeResult<T>;
+}
+//#endregion
+export { OverlayApplyParams, OverlayEngine, OverlayEngineOptions, OverlayRuntimeResult };
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","names":[],"sources":["../src/runtime.ts"],"sourcesContent":[],"mappings":";;;;;;UAKiB,oBAAA;YACL;EADK,KAAA,CAAA,EAAA,CAAA,KAAA,EAEC,iBAFmB,EACzB,GAAA,IAAA;AAIZ;AAA8C,UAA7B,kBAA6B,CAAA,UAAA,iBAAA,CAAA,SACpC,aADoC,CAAA;EAEpC,MAAA,EAAA,CAAA;EACG,QAAA,CAAA,EAAA,iBAAA,EAAA;EACF,MAAA,CAAA,EAAA,mBAAA,CAAA,QAAA,CAAA;;AAHY,UAMN,oBANM,CAAA,UAMyB,iBANzB,CAAA,CAAA;EAMN,MAAA,EACP,CADO;EAA+B,eAAA,EAE7B,iBAF6B,EAAA;;AAE7B,cAGN,aAAA,CAHM;EAAiB,iBAAA,QAAA;EAGvB,iBAAa,KAAA;EAIH,WAAA,CAAA,OAAA,EAAA,oBAAA;EAKL,KAAA,CAAA,UAAA,iBAAA,CAAA,CAAA,MAAA,EACN,kBADM,CACa,CADb,CAAA,CAAA,EAEb,oBAFa,CAEQ,CAFR,CAAA"}

package/dist/runtime.js

@@ -0,0 +1,2 @@
+import{applyOverlayModifications as e}from"./merger.js";var t=class{registry;audit;constructor(e){this.registry=e.registry,this.audit=e.audit}apply(t){let r=t.overlays??this.registry.forContext({capability:t.capability,workflow:t.workflow,dataView:t.dataView,presentation:t.presentation,operation:t.operation,tenantId:t.tenantId,role:t.role,userId:t.userId,device:t.device,tags:t.tags}),i=e(t.target,r,{strict:t.strict}),a=n(t);return r.forEach(e=>{this.audit?.({overlay:{overlayId:e.overlayId,version:e.version},context:a,timestamp:new Date().toISOString()})}),{target:i,overlaysApplied:r}}};function n(e){return{tenantId:e.tenantId,role:e.role,userId:e.userId,device:e.device,tags:e.tags}}export{t as OverlayEngine};
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","names":[],"sources":["../src/runtime.ts"],"sourcesContent":["import { applyOverlayModifications, type ApplyOverlayOptions } from './merger';\nimport { OverlayRegistry, type OverlayLookup } from './registry';\nimport type { SignedOverlaySpec } from './spec';\nimport type { OverlayRenderable, OverlayAuditEvent } from './types';\n\nexport interface OverlayEngineOptions {\n  registry: OverlayRegistry;\n  audit?: (event: OverlayAuditEvent) => void;\n}\n\nexport interface OverlayApplyParams<T extends OverlayRenderable>\n  extends OverlayLookup {\n  target: T;\n  overlays?: SignedOverlaySpec[];\n  strict?: ApplyOverlayOptions['strict'];\n}\n\nexport interface OverlayRuntimeResult<T extends OverlayRenderable> {\n  target: T;\n  overlaysApplied: SignedOverlaySpec[];\n}\n\nexport class OverlayEngine {\n  private readonly registry: OverlayRegistry;\n  private readonly audit?: (event: OverlayAuditEvent) => void;\n\n  constructor(options: OverlayEngineOptions) {\n    this.registry = options.registry;\n    this.audit = options.audit;\n  }\n\n  apply<T extends OverlayRenderable>(\n    params: OverlayApplyParams<T>\n  ): OverlayRuntimeResult<T> {\n    const overlays =\n      params.overlays ??\n      this.registry.forContext({\n        capability: params.capability,\n        workflow: params.workflow,\n        dataView: params.dataView,\n        presentation: params.presentation,\n        operation: params.operation,\n        tenantId: params.tenantId,\n        role: params.role,\n        userId: params.userId,\n        device: params.device,\n        tags: params.tags,\n      });\n\n    const merged = applyOverlayModifications(params.target, overlays, {\n      strict: params.strict,\n    });\n\n    const context = extractContext(params);\n    overlays.forEach((overlay) => {\n      this.audit?.({\n        overlay: {\n          overlayId: overlay.overlayId,\n          version: overlay.version,\n        },\n        context,\n        timestamp: new Date().toISOString(),\n      });\n    });\n\n    return {\n      target: merged,\n      overlaysApplied: overlays,\n    };\n  }\n}\n\nfunction extractContext(params: OverlayLookup): OverlayAuditEvent['context'] {\n  return {\n    tenantId: params.tenantId,\n    role: params.role,\n    userId: params.userId,\n    device: params.device,\n    tags: params.tags,\n  };\n}\n"],"mappings":"wDAsBA,IAAa,EAAb,KAA2B,CACzB,SACA,MAEA,YAAY,EAA+B,CACzC,KAAK,SAAW,EAAQ,SACxB,KAAK,MAAQ,EAAQ,MAGvB,MACE,EACyB,CACzB,IAAM,EACJ,EAAO,UACP,KAAK,SAAS,WAAW,CACvB,WAAY,EAAO,WACnB,SAAU,EAAO,SACjB,SAAU,EAAO,SACjB,aAAc,EAAO,aACrB,UAAW,EAAO,UAClB,SAAU,EAAO,SACjB,KAAM,EAAO,KACb,OAAQ,EAAO,OACf,OAAQ,EAAO,OACf,KAAM,EAAO,KACd,CAAC,CAEE,EAAS,EAA0B,EAAO,OAAQ,EAAU,CAChE,OAAQ,EAAO,OAChB,CAAC,CAEI,EAAU,EAAe,EAAO,CAYtC,OAXA,EAAS,QAAS,GAAY,CAC5B,KAAK,QAAQ,CACX,QAAS,CACP,UAAW,EAAQ,UACnB,QAAS,EAAQ,QAClB,CACD,UACA,UAAW,IAAI,MAAM,CAAC,aAAa,CACpC,CAAC,EACF,CAEK,CACL,OAAQ,EACR,gBAAiB,EAClB,GAIL,SAAS,EAAe,EAAqD,CAC3E,MAAO,CACL,SAAU,EAAO,SACjB,KAAM,EAAO,KACb,OAAQ,EAAO,OACf,OAAQ,EAAO,OACf,KAAM,EAAO,KACd"}

package/dist/signer.d.ts

@@ -0,0 +1,19 @@
+import { OverlaySignatureAlgorithm, OverlaySpec, SignedOverlaySpec } from "./spec.js";
+import { KeyLike } from "crypto";
+
+//#region src/signer.d.ts
+interface SignOverlayOptions {
+  algorithm?: OverlaySignatureAlgorithm;
+  keyId?: string;
+  issuedAt?: Date | string;
+  expiresAt?: Date | string;
+  metadata?: Record<string, unknown>;
+  publicKey?: string;
+}
+declare function signOverlay(spec: OverlaySpec, privateKey: KeyLike | string | Buffer, options?: SignOverlayOptions): SignedOverlaySpec;
+declare function verifyOverlaySignature(overlay: SignedOverlaySpec): boolean;
+declare function canonicalizeOverlay(spec: OverlaySpec | SignedOverlaySpec): string;
+declare function stripSignature<T extends OverlaySpec | SignedOverlaySpec>(spec: T): OverlaySpec;
+//#endregion
+export { SignOverlayOptions, canonicalizeOverlay, signOverlay, stripSignature, verifyOverlaySignature };
+//# sourceMappingURL=signer.d.ts.map

package/dist/signer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signer.d.ts","names":[],"sources":["../src/signer.ts"],"sourcesContent":[],"mappings":";;;;UAeiB,kBAAA;cACH;EADG,KAAA,CAAA,EAAA,MAAA;EACH,QAAA,CAAA,EAED,IAFC,GAAA,MAAA;EAED,SAAA,CAAA,EACC,IADD,GAAA,MAAA;EACC,QAAA,CAAA,EACD,MADC,CAAA,MAAA,EAAA,OAAA,CAAA;EACD,SAAA,CAAA,EAAA,MAAA;;AAIG,iBAAA,WAAA,CAAW,IAAA,EACnB,WADmB,EAAA,UAAA,EAEb,OAFa,GAAA,MAAA,GAEM,MAFN,EAAA,OAAA,CAAA,EAGhB,kBAHgB,CAAA,EAIxB,iBAJwB;AACnB,iBA4CQ,sBAAA,CA5CR,OAAA,EA4CwC,iBA5CxC,CAAA,EAAA,OAAA;AACM,iBA2EE,mBAAA,CA3EF,IAAA,EA4EN,WA5EM,GA4EQ,iBA5ER,CAAA,EAAA,MAAA;AAAmB,iBAkFjB,cAlFiB,CAAA,UAkFQ,WAlFR,GAkFsB,iBAlFtB,CAAA,CAAA,IAAA,EAmFzB,CAnFyB,CAAA,EAoF9B,WApF8B"}

package/dist/signer.js

@@ -0,0 +1,2 @@
+import e from"fast-json-stable-stringify";import{constants as t,createPrivateKey as n,createPublicKey as r,sign as i,verify as a}from"crypto";function o(e,a,o={}){let s=o.algorithm??`ed25519`,l=typeof a==`string`||Buffer.isBuffer(a)?n(a):a,d=Buffer.from(c(e),`utf8`),f;if(s===`ed25519`)f=i(null,d,l);else if(s===`rsa-pss-sha256`)f=i(`sha256`,d,{key:l,padding:t.RSA_PKCS1_PSS_PADDING,saltLength:32});else throw Error(`Unsupported overlay signature algorithm: ${s}`);let p=o.publicKey??r(l).export({format:`pem`,type:`spki`}).toString();return{...e,signature:{algorithm:s,signature:f.toString(`base64`),publicKey:p,keyId:o.keyId,issuedAt:u(o.issuedAt)??new Date().toISOString(),expiresAt:u(o.expiresAt),metadata:o.metadata}}}function s(e){if(!e.signature?.signature)throw Error(`Overlay "${e.overlayId}" is missing signature metadata.`);let n=Buffer.from(c(e),`utf8`),i=Buffer.from(e.signature.signature,`base64`),o=r(e.signature.publicKey);if(e.signature.algorithm===`ed25519`)return a(null,n,o,i);if(e.signature.algorithm===`rsa-pss-sha256`)return a(`sha256`,n,{key:o,padding:t.RSA_PKCS1_PSS_PADDING,saltLength:32},i);throw Error(`Unsupported overlay signature algorithm: ${e.signature.algorithm}`)}function c(t){let{signature:n,...r}=t;return e(r)}function l(e){let{signature:t,...n}=e;return{...n}}function u(e){if(e)return typeof e==`string`?new Date(e).toISOString():e.toISOString()}export{c as canonicalizeOverlay,o as signOverlay,l as stripSignature,s as verifyOverlaySignature};
+//# sourceMappingURL=signer.js.map

package/dist/signer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signer.js","names":["rawSignature: Buffer"],"sources":["../src/signer.ts"],"sourcesContent":["import stringify from 'fast-json-stable-stringify';\nimport {\n  constants,\n  createPrivateKey,\n  createPublicKey,\n  type KeyLike,\n  sign,\n  verify,\n} from 'crypto';\nimport type {\n  OverlaySignatureAlgorithm,\n  OverlaySpec,\n  SignedOverlaySpec,\n} from './spec';\n\nexport interface SignOverlayOptions {\n  algorithm?: OverlaySignatureAlgorithm;\n  keyId?: string;\n  issuedAt?: Date | string;\n  expiresAt?: Date | string;\n  metadata?: Record<string, unknown>;\n  publicKey?: string;\n}\n\nexport function signOverlay(\n  spec: OverlaySpec,\n  privateKey: KeyLike | string | Buffer,\n  options: SignOverlayOptions = {}\n): SignedOverlaySpec {\n  const algorithm = options.algorithm ?? 'ed25519';\n  const keyObject =\n    typeof privateKey === 'string' || Buffer.isBuffer(privateKey)\n      ? createPrivateKey(privateKey)\n      : privateKey;\n  const payload = Buffer.from(canonicalizeOverlay(spec), 'utf8');\n\n  let rawSignature: Buffer;\n  if (algorithm === 'ed25519') {\n    rawSignature = sign(null, payload, keyObject);\n  } else if (algorithm === 'rsa-pss-sha256') {\n    rawSignature = sign('sha256', payload, {\n      key: keyObject,\n      padding: constants.RSA_PKCS1_PSS_PADDING,\n      saltLength: 32,\n    });\n  } else {\n    throw new Error(`Unsupported overlay signature algorithm: ${algorithm}`);\n  }\n\n  const publicKey =\n    options.publicKey ??\n    createPublicKey(keyObject)\n      .export({ format: 'pem', type: 'spki' })\n      .toString();\n\n  return {\n    ...spec,\n    signature: {\n      algorithm,\n      signature: rawSignature.toString('base64'),\n      publicKey,\n      keyId: options.keyId,\n      issuedAt: toIso(options.issuedAt) ?? new Date().toISOString(),\n      expiresAt: toIso(options.expiresAt),\n      metadata: options.metadata,\n    },\n  };\n}\n\nexport function verifyOverlaySignature(overlay: SignedOverlaySpec): boolean {\n  if (!overlay.signature?.signature) {\n    throw new Error(\n      `Overlay \"${overlay.overlayId}\" is missing signature metadata.`\n    );\n  }\n  const payload = Buffer.from(canonicalizeOverlay(overlay), 'utf8');\n  const signature = Buffer.from(overlay.signature.signature, 'base64');\n  const publicKey = createPublicKey(overlay.signature.publicKey);\n\n  if (overlay.signature.algorithm === 'ed25519') {\n    return verify(null, payload, publicKey, signature);\n  }\n\n  if (overlay.signature.algorithm === 'rsa-pss-sha256') {\n    return verify(\n      'sha256',\n      payload,\n      {\n        key: publicKey,\n        padding: constants.RSA_PKCS1_PSS_PADDING,\n        saltLength: 32,\n      },\n      signature\n    );\n  }\n\n  throw new Error(\n    `Unsupported overlay signature algorithm: ${overlay.signature.algorithm}`\n  );\n}\n\nexport function canonicalizeOverlay(\n  spec: OverlaySpec | SignedOverlaySpec\n): string {\n  const { signature, ...rest } = spec as SignedOverlaySpec;\n  return stringify(rest);\n}\n\nexport function stripSignature<T extends OverlaySpec | SignedOverlaySpec>(\n  spec: T\n): OverlaySpec {\n  const { signature, ...rest } = spec as SignedOverlaySpec;\n  return { ...rest };\n}\n\nfunction toIso(value?: Date | string): string | undefined {\n  if (!value) {\n    return undefined;\n  }\n  if (typeof value === 'string') {\n    return new Date(value).toISOString();\n  }\n  return value.toISOString();\n}\n"],"mappings":"8IAwBA,SAAgB,EACd,EACA,EACA,EAA8B,EAAE,CACb,CACnB,IAAM,EAAY,EAAQ,WAAa,UACjC,EACJ,OAAO,GAAe,UAAY,OAAO,SAAS,EAAW,CACzD,EAAiB,EAAW,CAC5B,EACA,EAAU,OAAO,KAAK,EAAoB,EAAK,CAAE,OAAO,CAE1DA,EACJ,GAAI,IAAc,UAChB,EAAe,EAAK,KAAM,EAAS,EAAU,SACpC,IAAc,iBACvB,EAAe,EAAK,SAAU,EAAS,CACrC,IAAK,EACL,QAAS,EAAU,sBACnB,WAAY,GACb,CAAC,MAEF,MAAU,MAAM,4CAA4C,IAAY,CAG1E,IAAM,EACJ,EAAQ,WACR,EAAgB,EAAU,CACvB,OAAO,CAAE,OAAQ,MAAO,KAAM,OAAQ,CAAC,CACvC,UAAU,CAEf,MAAO,CACL,GAAG,EACH,UAAW,CACT,YACA,UAAW,EAAa,SAAS,SAAS,CAC1C,YACA,MAAO,EAAQ,MACf,SAAU,EAAM,EAAQ,SAAS,EAAI,IAAI,MAAM,CAAC,aAAa,CAC7D,UAAW,EAAM,EAAQ,UAAU,CACnC,SAAU,EAAQ,SACnB,CACF,CAGH,SAAgB,EAAuB,EAAqC,CAC1E,GAAI,CAAC,EAAQ,WAAW,UACtB,MAAU,MACR,YAAY,EAAQ,UAAU,kCAC/B,CAEH,IAAM,EAAU,OAAO,KAAK,EAAoB,EAAQ,CAAE,OAAO,CAC3D,EAAY,OAAO,KAAK,EAAQ,UAAU,UAAW,SAAS,CAC9D,EAAY,EAAgB,EAAQ,UAAU,UAAU,CAE9D,GAAI,EAAQ,UAAU,YAAc,UAClC,OAAO,EAAO,KAAM,EAAS,EAAW,EAAU,CAGpD,GAAI,EAAQ,UAAU,YAAc,iBAClC,OAAO,EACL,SACA,EACA,CACE,IAAK,EACL,QAAS,EAAU,sBACnB,WAAY,GACb,CACD,EACD,CAGH,MAAU,MACR,4CAA4C,EAAQ,UAAU,YAC/D,CAGH,SAAgB,EACd,EACQ,CACR,GAAM,CAAE,YAAW,GAAG,GAAS,EAC/B,OAAO,EAAU,EAAK,CAGxB,SAAgB,EACd,EACa,CACb,GAAM,CAAE,YAAW,GAAG,GAAS,EAC/B,MAAO,CAAE,GAAG,EAAM,CAGpB,SAAS,EAAM,EAA2C,CACnD,KAML,OAHI,OAAO,GAAU,SACZ,IAAI,KAAK,EAAM,CAAC,aAAa,CAE/B,EAAM,aAAa"}

package/dist/spec.d.ts

@@ -0,0 +1,83 @@
+import { AnyContractSpec } from "@lssm/lib.contracts";
+
+//#region src/spec.d.ts
+type OverlayScopeKey = 'tenantId' | 'role' | 'userId' | 'device' | 'tags';
+interface OverlayScopeContext {
+  tenantId?: string;
+  role?: string;
+  userId?: string;
+  device?: string;
+  tags?: string[];
+}
+interface OverlayTargetRef {
+  capability?: string;
+  workflow?: string;
+  dataView?: string;
+  presentation?: string;
+  operation?: AnyContractSpec['meta']['name'];
+}
+interface OverlayAppliesTo extends OverlayScopeContext, OverlayTargetRef {
+  /**
+   * Optional label to describe why this overlay exists (displayed in tooling).
+   */
+  label?: string;
+}
+type OverlayModification = HideFieldModification | RenameLabelModification | ReorderFieldsModification | SetDefaultModification | AddHelpTextModification | MakeRequiredModification;
+interface OverlayFieldModificationBase {
+  field: string;
+  description?: string;
+}
+interface HideFieldModification extends OverlayFieldModificationBase {
+  type: 'hideField';
+  reason?: string;
+}
+interface RenameLabelModification extends OverlayFieldModificationBase {
+  type: 'renameLabel';
+  newLabel: string;
+}
+interface ReorderFieldsModification {
+  type: 'reorderFields';
+  fields: string[];
+  description?: string;
+}
+interface SetDefaultModification extends OverlayFieldModificationBase {
+  type: 'setDefault';
+  value: unknown;
+}
+interface AddHelpTextModification extends OverlayFieldModificationBase {
+  type: 'addHelpText';
+  text: string;
+}
+interface MakeRequiredModification extends OverlayFieldModificationBase {
+  type: 'makeRequired';
+  required?: boolean;
+}
+interface OverlaySpec {
+  overlayId: string;
+  version: string;
+  description?: string;
+  appliesTo: OverlayAppliesTo;
+  modifications: OverlayModification[];
+  metadata?: Record<string, unknown>;
+  createdBy?: string;
+  createdAt?: string;
+}
+type OverlaySignatureAlgorithm = 'ed25519' | 'rsa-pss-sha256';
+interface OverlaySignatureBlock {
+  algorithm: OverlaySignatureAlgorithm;
+  signature: string;
+  publicKey: string;
+  keyId?: string;
+  issuedAt?: string;
+  expiresAt?: string;
+  metadata?: Record<string, unknown>;
+}
+type SignedOverlaySpec = OverlaySpec & {
+  signature: OverlaySignatureBlock;
+};
+type OverlayInput = OverlaySpec | SignedOverlaySpec;
+declare const OVERLAY_SCOPE_ORDER: OverlayScopeKey[];
+declare function defineOverlay<T extends OverlaySpec>(spec: T): T;
+//#endregion
+export { AddHelpTextModification, HideFieldModification, MakeRequiredModification, OVERLAY_SCOPE_ORDER, OverlayAppliesTo, OverlayFieldModificationBase, OverlayInput, OverlayModification, OverlayScopeContext, OverlayScopeKey, OverlaySignatureAlgorithm, OverlaySignatureBlock, OverlaySpec, OverlayTargetRef, RenameLabelModification, ReorderFieldsModification, SetDefaultModification, SignedOverlaySpec, defineOverlay };
+//# sourceMappingURL=spec.d.ts.map

package/dist/spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.d.ts","names":[],"sources":["../src/spec.ts"],"sourcesContent":[],"mappings":";;;KAEY,eAAA;UAOK,mBAAA;EAPL,QAAA,CAAA,EAAA,MAAA;EAOK,IAAA,CAAA,EAAA,MAAA;EAQA,MAAA,CAAA,EAAA,MAAA;EAQA,MAAA,CAAA,EAAA,MAAA;EASL,IAAA,CAAA,EAAA,MAAA,EAAA;;AAER,UAnBa,gBAAA,CAmBb;EACA,UAAA,CAAA,EAAA,MAAA;EACA,QAAA,CAAA,EAAA,MAAA;EACA,QAAA,CAAA,EAAA,MAAA;EACA,YAAA,CAAA,EAAA,MAAA;EAAwB,SAAA,CAAA,EAlBd,eAkBc,CAAA,MAAA,CAAA,CAAA,MAAA,CAAA;AAE5B;AAKiB,UAtBA,gBAAA,SACP,mBAqBqC,EApB3C,gBAoBuE,CAAA;EAK1D;AAKjB;AAMA;EAKiB,KAAA,CAAA,EAAA,MAAA;AAKjB;AAKiB,KA5CL,mBAAA,GACR,qBA2CwB,GA1CxB,uBA0CwB,GAzCxB,yBAyCwB,GAxCxB,sBAwCwB,GAvCxB,uBAuCwB,GAtCxB,wBAsCwB;AAIf,UAxCI,4BAAA,CAwCJ;EACI,KAAA,EAAA,MAAA;EACJ,WAAA,CAAA,EAAA,MAAA;;AAKD,UA1CK,qBAAA,SAA8B,4BA0CV,CAAA;EAEpB,IAAA,EAAA,WAAA;EAUL,MAAA,CAAA,EAAA,MAAA;AAIZ;AAEa,UAvDI,uBAAA,SAAgC,4BAuDA,CAAA;EAQjC,IAAA,EAAA,aAAa;EAAW,QAAA,EAAA,MAAA;;AAAuB,UA1D9C,yBAAA,CA0D8C;EAAC,IAAA,EAAA,eAAA;;;;UApD/C,sBAAA,SAA+B;;;;UAK/B,uBAAA,SAAgC;;;;UAKhC,wBAAA,SAAiC;;;;UAKjC,WAAA;;;;aAIJ;iBACI;aACJ;;;;KAKD,yBAAA;UAEK,qBAAA;aACJ;;;;;;aAMA;;KAGD,iBAAA,GAAoB;aACnB;;KAGD,YAAA,GAAe,cAAc;cAE5B,qBAAqB;iBAQlB,wBAAwB,mBAAmB,IAAI"}

package/dist/spec.js

@@ -0,0 +1,2 @@
+const e=[`tenantId`,`role`,`userId`,`device`,`tags`];function t(e){return e}export{e as OVERLAY_SCOPE_ORDER,t as defineOverlay};
+//# sourceMappingURL=spec.js.map

package/dist/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","names":["OVERLAY_SCOPE_ORDER: OverlayScopeKey[]"],"sources":["../src/spec.ts"],"sourcesContent":["import type { AnyContractSpec } from '@lssm/lib.contracts';\n\nexport type OverlayScopeKey =\n  | 'tenantId'\n  | 'role'\n  | 'userId'\n  | 'device'\n  | 'tags';\n\nexport interface OverlayScopeContext {\n  tenantId?: string;\n  role?: string;\n  userId?: string;\n  device?: string;\n  tags?: string[];\n}\n\nexport interface OverlayTargetRef {\n  capability?: string;\n  workflow?: string;\n  dataView?: string;\n  presentation?: string;\n  operation?: AnyContractSpec['meta']['name'];\n}\n\nexport interface OverlayAppliesTo\n  extends OverlayScopeContext,\n    OverlayTargetRef {\n  /**\n   * Optional label to describe why this overlay exists (displayed in tooling).\n   */\n  label?: string;\n}\n\nexport type OverlayModification =\n  | HideFieldModification\n  | RenameLabelModification\n  | ReorderFieldsModification\n  | SetDefaultModification\n  | AddHelpTextModification\n  | MakeRequiredModification;\n\nexport interface OverlayFieldModificationBase {\n  field: string;\n  description?: string;\n}\n\nexport interface HideFieldModification extends OverlayFieldModificationBase {\n  type: 'hideField';\n  reason?: string;\n}\n\nexport interface RenameLabelModification extends OverlayFieldModificationBase {\n  type: 'renameLabel';\n  newLabel: string;\n}\n\nexport interface ReorderFieldsModification {\n  type: 'reorderFields';\n  fields: string[];\n  description?: string;\n}\n\nexport interface SetDefaultModification extends OverlayFieldModificationBase {\n  type: 'setDefault';\n  value: unknown;\n}\n\nexport interface AddHelpTextModification extends OverlayFieldModificationBase {\n  type: 'addHelpText';\n  text: string;\n}\n\nexport interface MakeRequiredModification extends OverlayFieldModificationBase {\n  type: 'makeRequired';\n  required?: boolean;\n}\n\nexport interface OverlaySpec {\n  overlayId: string;\n  version: string;\n  description?: string;\n  appliesTo: OverlayAppliesTo;\n  modifications: OverlayModification[];\n  metadata?: Record<string, unknown>;\n  createdBy?: string;\n  createdAt?: string;\n}\n\nexport type OverlaySignatureAlgorithm = 'ed25519' | 'rsa-pss-sha256';\n\nexport interface OverlaySignatureBlock {\n  algorithm: OverlaySignatureAlgorithm;\n  signature: string;\n  publicKey: string;\n  keyId?: string;\n  issuedAt?: string;\n  expiresAt?: string;\n  metadata?: Record<string, unknown>;\n}\n\nexport type SignedOverlaySpec = OverlaySpec & {\n  signature: OverlaySignatureBlock;\n};\n\nexport type OverlayInput = OverlaySpec | SignedOverlaySpec;\n\nexport const OVERLAY_SCOPE_ORDER: OverlayScopeKey[] = [\n  'tenantId',\n  'role',\n  'userId',\n  'device',\n  'tags',\n];\n\nexport function defineOverlay<T extends OverlaySpec>(spec: T): T {\n  return spec;\n}\n"],"mappings":"AA2GA,MAAaA,EAAyC,CACpD,WACA,OACA,SACA,SACA,OACD,CAED,SAAgB,EAAqC,EAAY,CAC/D,OAAO"}

package/dist/types.d.ts

@@ -0,0 +1,33 @@
+import { OverlayScopeContext, OverlayTargetRef, SignedOverlaySpec } from "./spec.js";
+
+//#region src/types.d.ts
+interface OverlayRenderableField {
+  key: string;
+  label?: string;
+  visible?: boolean;
+  required?: boolean;
+  helpText?: string;
+  defaultValue?: unknown;
+  metadata?: Record<string, unknown>;
+  order?: number;
+}
+interface OverlayLayoutConfig {
+  kind?: 'form' | 'list' | 'table' | 'grid';
+  columns?: number;
+  density?: 'comfortable' | 'compact';
+  [key: string]: unknown;
+}
+interface OverlayRenderable<TField extends OverlayRenderableField = OverlayRenderableField> {
+  fields: TField[];
+  layout?: OverlayLayoutConfig;
+  metadata?: Record<string, unknown>;
+}
+interface OverlayMatchContext extends OverlayScopeContext, OverlayTargetRef {}
+interface OverlayAuditEvent {
+  overlay: Pick<SignedOverlaySpec, 'overlayId' | 'version'>;
+  context: OverlayScopeContext;
+  timestamp: string;
+}
+//#endregion
+export { OverlayAuditEvent, OverlayLayoutConfig, OverlayMatchContext, OverlayRenderable, OverlayRenderableField };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"sourcesContent":[],"mappings":";;;UAMiB,sBAAA;;EAAA,KAAA,CAAA,EAAA,MAAA;EAWA,OAAA,CAAA,EAAA,OAAA;EAOA,QAAA,CAAA,EAAA,OAAA;EACA,QAAA,CAAA,EAAA,MAAA;EAAyB,YAAA,CAAA,EAAA,OAAA;EAEhC,QAAA,CAAA,EAdG,MAcH,CAAA,MAAA,EAAA,OAAA,CAAA;EACC,KAAA,CAAA,EAAA,MAAA;;AACQ,UAZF,mBAAA,CAYE;EAGF,IAAA,CAAA,EAAA,MAAA,GAAA,MACf,GAAA,OAAA,GAAQ,MAAA;EAGO,OAAA,CAAA,EAAA,MAAA;EACD,OAAA,CAAA,EAAA,aAAA,GAAA,SAAA;EAAL,CAAA,GAAA,EAAA,MAAA,CAAA,EAAA,OAAA;;AACmB,UAdb,iBAca,CAAA,eAbb,sBAaa,GAbY,sBAaZ,CAAA,CAAA;UAXpB;WACC;aACE;;UAGI,mBAAA,SACP,qBACN;UAEa,iBAAA;WACN,KAAK;WACL"}

package/dist/validator.d.ts

@@ -0,0 +1,19 @@
+import { OverlaySpec } from "./spec.js";
+
+//#region src/validator.d.ts
+interface OverlayValidationIssue {
+  code: string;
+  message: string;
+  path?: string[];
+}
+interface OverlayValidationResult {
+  valid: boolean;
+  issues: OverlayValidationIssue[];
+}
+type OverlayValidator = (spec: OverlaySpec) => OverlayValidationResult;
+declare const defaultOverlayValidator: OverlayValidator;
+declare function validateOverlaySpec(spec: OverlaySpec): OverlayValidationResult;
+declare function assertOverlayValid(spec: OverlaySpec, validator?: OverlayValidator): void;
+//#endregion
+export { OverlayValidationIssue, OverlayValidationResult, OverlayValidator, assertOverlayValid, defaultOverlayValidator, validateOverlaySpec };
+//# sourceMappingURL=validator.d.ts.map

package/dist/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","names":[],"sources":["../src/validator.ts"],"sourcesContent":[],"mappings":";;;UAEiB,sBAAA;;EAAA,OAAA,EAAA,MAAA;EAMA,IAAA,CAAA,EAAA,MAAA,EAAA;AAKjB;AAUa,UAfI,uBAAA,CAgBU;EAEX,KAAA,EAAA,OAAA;EA+IA,MAAA,EA/JN,sBA+JwB,EAAA;;KA5JtB,gBAAA,UAA0B,gBAAgB;cAUzC,yBAAyB;iBAGtB,mBAAA,OACR,cACL;iBA6Ia,kBAAA,OACR,yBACK"}

package/dist/validator.js

@@ -0,0 +1,2 @@
+const e=[`capability`,`workflow`,`dataView`,`presentation`,`operation`],t=e=>n(e);function n(t){let n=[];return t.overlayId?.trim()||n.push({code:`overlay.id`,message:`overlayId is required`,path:[`overlayId`]}),t.version?.trim()||n.push({code:`overlay.version`,message:`version is required`,path:[`version`]}),e.some(e=>{let n=t.appliesTo?.[e];return typeof n==`string`&&n.trim().length>0})||n.push({code:`overlay.target`,message:`Overlay must specify at least one target (capability, workflow, dataView, presentation, or operation).`,path:[`appliesTo`]}),t.modifications?.length?t.modifications.forEach((e,t)=>{r(e,[`modifications`,String(t)],n)}):n.push({code:`overlay.modifications.empty`,message:`Overlay must include at least one modification.`,path:[`modifications`]}),{valid:n.length===0,issues:n}}function r(e,t,n){let r=(e,r,i)=>{n.push({code:e,message:r,path:i?[...t,...i]:t})};switch(i(e)&&(e.field?.trim()||r(`overlay.mod.field`,`field is required for this modification`,[`field`])),e.type){case`renameLabel`:e.newLabel?.trim()||r(`overlay.mod.renameLabel.newLabel`,`newLabel is required`,[`newLabel`]);break;case`reorderFields`:{e.fields?.length||r(`overlay.mod.reorderFields.fields`,`fields list cannot be empty`,[`fields`]);let t=new Set;for(let n of e.fields??[]){if(!n?.trim()){r(`overlay.mod.reorderFields.fields.blank`,`fields entries must be non-empty`);break}if(t.has(n)){r(`overlay.mod.reorderFields.fields.duplicate`,`field "${n}" was listed multiple times`);break}t.add(n)}break}case`setDefault`:e.value===void 0&&r(`overlay.mod.setDefault.value`,`value is required`,[`value`]);break;case`addHelpText`:e.text?.trim()||r(`overlay.mod.addHelpText.text`,`text is required`,[`text`]);break;case`makeRequired`:case`hideField`:break;default:{let t=e;throw Error(`Unsupported overlay modification ${t?.type??`unknown`}`)}}}function i(e){return`field`in e}function a(e,n=t){let r=n(e);if(!r.valid){let t=r.issues.map(e=>`${e.code}: ${e.message}`).join(`; `);throw Error(`Invalid OverlaySpec "${e.overlayId}": ${t}`)}}export{a as assertOverlayValid,t as defaultOverlayValidator,n as validateOverlaySpec};
+//# sourceMappingURL=validator.js.map

package/dist/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","names":["defaultOverlayValidator: OverlayValidator","issues: OverlayValidationIssue[]","exhaustive: never"],"sources":["../src/validator.ts"],"sourcesContent":["import type { OverlayModification, OverlaySpec } from './spec';\n\nexport interface OverlayValidationIssue {\n  code: string;\n  message: string;\n  path?: string[];\n}\n\nexport interface OverlayValidationResult {\n  valid: boolean;\n  issues: OverlayValidationIssue[];\n}\n\nexport type OverlayValidator = (spec: OverlaySpec) => OverlayValidationResult;\n\nconst TARGET_KEYS = [\n  'capability',\n  'workflow',\n  'dataView',\n  'presentation',\n  'operation',\n] as const;\n\nexport const defaultOverlayValidator: OverlayValidator = (spec) =>\n  validateOverlaySpec(spec);\n\nexport function validateOverlaySpec(\n  spec: OverlaySpec\n): OverlayValidationResult {\n  const issues: OverlayValidationIssue[] = [];\n\n  if (!spec.overlayId?.trim()) {\n    issues.push({\n      code: 'overlay.id',\n      message: 'overlayId is required',\n      path: ['overlayId'],\n    });\n  }\n\n  if (!spec.version?.trim()) {\n    issues.push({\n      code: 'overlay.version',\n      message: 'version is required',\n      path: ['version'],\n    });\n  }\n\n  const hasTarget = TARGET_KEYS.some((key) => {\n    const value = spec.appliesTo?.[key as keyof typeof spec.appliesTo];\n    return typeof value === 'string' && value.trim().length > 0;\n  });\n\n  if (!hasTarget) {\n    issues.push({\n      code: 'overlay.target',\n      message:\n        'Overlay must specify at least one target (capability, workflow, dataView, presentation, or operation).',\n      path: ['appliesTo'],\n    });\n  }\n\n  if (!spec.modifications?.length) {\n    issues.push({\n      code: 'overlay.modifications.empty',\n      message: 'Overlay must include at least one modification.',\n      path: ['modifications'],\n    });\n  } else {\n    spec.modifications.forEach((mod, idx) => {\n      const path = ['modifications', String(idx)];\n      validateModification(mod, path, issues);\n    });\n  }\n\n  return {\n    valid: issues.length === 0,\n    issues,\n  };\n}\n\nfunction validateModification(\n  modification: OverlayModification,\n  path: string[],\n  issues: OverlayValidationIssue[]\n) {\n  const push = (code: string, message: string, extraPath?: string[]) => {\n    issues.push({\n      code,\n      message,\n      path: extraPath ? [...path, ...extraPath] : path,\n    });\n  };\n\n  if (isFieldModification(modification)) {\n    if (!modification.field?.trim()) {\n      push('overlay.mod.field', 'field is required for this modification', [\n        'field',\n      ]);\n    }\n  }\n\n  switch (modification.type) {\n    case 'renameLabel': {\n      if (!modification.newLabel?.trim()) {\n        push('overlay.mod.renameLabel.newLabel', 'newLabel is required', [\n          'newLabel',\n        ]);\n      }\n      break;\n    }\n    case 'reorderFields': {\n      if (!modification.fields?.length) {\n        push(\n          'overlay.mod.reorderFields.fields',\n          'fields list cannot be empty',\n          ['fields']\n        );\n      }\n      const seen = new Set<string>();\n      for (const field of modification.fields ?? []) {\n        if (!field?.trim()) {\n          push(\n            'overlay.mod.reorderFields.fields.blank',\n            'fields entries must be non-empty'\n          );\n          break;\n        }\n        if (seen.has(field)) {\n          push(\n            'overlay.mod.reorderFields.fields.duplicate',\n            `field \"${field}\" was listed multiple times`\n          );\n          break;\n        }\n        seen.add(field);\n      }\n      break;\n    }\n    case 'setDefault': {\n      if (modification.value === undefined) {\n        push('overlay.mod.setDefault.value', 'value is required', ['value']);\n      }\n      break;\n    }\n    case 'addHelpText': {\n      if (!modification.text?.trim()) {\n        push('overlay.mod.addHelpText.text', 'text is required', ['text']);\n      }\n      break;\n    }\n    case 'makeRequired':\n    case 'hideField':\n      // no extra validation\n      break;\n    default: {\n      const exhaustive: never = modification;\n      throw new Error(\n        `Unsupported overlay modification ${(exhaustive as any)?.type ?? 'unknown'}`\n      );\n    }\n  }\n}\n\nfunction isFieldModification(\n  mod: OverlayModification\n): mod is Extract<OverlayModification, { field: string }> {\n  return 'field' in mod;\n}\n\nexport function assertOverlayValid(\n  spec: OverlaySpec,\n  validator: OverlayValidator = defaultOverlayValidator\n) {\n  const result = validator(spec);\n  if (!result.valid) {\n    const message = result.issues\n      .map((issue) => `${issue.code}: ${issue.message}`)\n      .join('; ');\n    throw new Error(`Invalid OverlaySpec \"${spec.overlayId}\": ${message}`);\n  }\n}\n"],"mappings":"AAeA,MAAM,EAAc,CAClB,aACA,WACA,WACA,eACA,YACD,CAEYA,EAA6C,GACxD,EAAoB,EAAK,CAE3B,SAAgB,EACd,EACyB,CACzB,IAAMC,EAAmC,EAAE,CA6C3C,OA3CK,EAAK,WAAW,MAAM,EACzB,EAAO,KAAK,CACV,KAAM,aACN,QAAS,wBACT,KAAM,CAAC,YAAY,CACpB,CAAC,CAGC,EAAK,SAAS,MAAM,EACvB,EAAO,KAAK,CACV,KAAM,kBACN,QAAS,sBACT,KAAM,CAAC,UAAU,CAClB,CAAC,CAGc,EAAY,KAAM,GAAQ,CAC1C,IAAM,EAAQ,EAAK,YAAY,GAC/B,OAAO,OAAO,GAAU,UAAY,EAAM,MAAM,CAAC,OAAS,GAC1D,EAGA,EAAO,KAAK,CACV,KAAM,iBACN,QACE,yGACF,KAAM,CAAC,YAAY,CACpB,CAAC,CAGC,EAAK,eAAe,OAOvB,EAAK,cAAc,SAAS,EAAK,IAAQ,CAEvC,EAAqB,EADR,CAAC,gBAAiB,OAAO,EAAI,CAAC,CACX,EAAO,EACvC,CATF,EAAO,KAAK,CACV,KAAM,8BACN,QAAS,kDACT,KAAM,CAAC,gBAAgB,CACxB,CAAC,CAQG,CACL,MAAO,EAAO,SAAW,EACzB,SACD,CAGH,SAAS,EACP,EACA,EACA,EACA,CACA,IAAM,GAAQ,EAAc,EAAiB,IAAyB,CACpE,EAAO,KAAK,CACV,OACA,UACA,KAAM,EAAY,CAAC,GAAG,EAAM,GAAG,EAAU,CAAG,EAC7C,CAAC,EAWJ,OARI,EAAoB,EAAa,GAC9B,EAAa,OAAO,MAAM,EAC7B,EAAK,oBAAqB,0CAA2C,CACnE,QACD,CAAC,EAIE,EAAa,KAArB,CACE,IAAK,cACE,EAAa,UAAU,MAAM,EAChC,EAAK,mCAAoC,uBAAwB,CAC/D,WACD,CAAC,CAEJ,MAEF,IAAK,gBAAiB,CACf,EAAa,QAAQ,QACxB,EACE,mCACA,8BACA,CAAC,SAAS,CACX,CAEH,IAAM,EAAO,IAAI,IACjB,IAAK,IAAM,KAAS,EAAa,QAAU,EAAE,CAAE,CAC7C,GAAI,CAAC,GAAO,MAAM,CAAE,CAClB,EACE,yCACA,mCACD,CACD,MAEF,GAAI,EAAK,IAAI,EAAM,CAAE,CACnB,EACE,6CACA,UAAU,EAAM,6BACjB,CACD,MAEF,EAAK,IAAI,EAAM,CAEjB,MAEF,IAAK,aACC,EAAa,QAAU,IAAA,IACzB,EAAK,+BAAgC,oBAAqB,CAAC,QAAQ,CAAC,CAEtE,MAEF,IAAK,cACE,EAAa,MAAM,MAAM,EAC5B,EAAK,+BAAgC,mBAAoB,CAAC,OAAO,CAAC,CAEpE,MAEF,IAAK,eACL,IAAK,YAEH,MACF,QAAS,CACP,IAAMC,EAAoB,EAC1B,MAAU,MACR,oCAAqC,GAAoB,MAAQ,YAClE,GAKP,SAAS,EACP,EACwD,CACxD,MAAO,UAAW,EAGpB,SAAgB,EACd,EACA,EAA8B,EAC9B,CACA,IAAM,EAAS,EAAU,EAAK,CAC9B,GAAI,CAAC,EAAO,MAAO,CACjB,IAAM,EAAU,EAAO,OACpB,IAAK,GAAU,GAAG,EAAM,KAAK,IAAI,EAAM,UAAU,CACjD,KAAK,KAAK,CACb,MAAU,MAAM,wBAAwB,EAAK,UAAU,KAAK,IAAU"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lssm/lib.overlay-engine",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Runtime overlay engine for ContractSpec personalization and adaptive UI rendering.",
   "type": "module",
   "main": "./dist/index.js",