@lssm/lib.overlay-engine 0.0.0-canary-20251206160926

package/README.md

@@ -0,0 +1,71 @@
+# @lssm/lib.overlay-engine
+
+Runtime utilities for executing **OverlaySpecs** inside ContractSpec applications. The library tracks signed overlays, validates their safety guarantees, merges multi-scope overlays, and exposes React helpers to render personalized layouts without bespoke code.
+
+## Features
+
+- Type-safe OverlaySpec definitions that mirror the docs.
+- Cryptographic signing and verification (Ed25519, RSA-PSS).
+- Registry + validator that enforces policy boundaries.
+- Deterministic merge engine for tenant / role / user overlays.
+- Runtime helpers + React hooks for applying overlays to form/data view field definitions.
+
+## Usage
+
+```ts
+import {
+  OverlayEngine,
+  OverlayRegistry,
+  defineOverlay,
+  signOverlay,
+} from '@lssm/lib.overlay-engine';
+
+const registry = new OverlayRegistry();
+const engine = new OverlayEngine({ registry });
+
+const overlay = defineOverlay({
+  overlayId: 'acme-order-form',
+  version: '1.0.0',
+  appliesTo: {
+    capability: 'billing.createOrder',
+    tenantId: 'acme',
+  },
+  modifications: [
+    { type: 'hideField', field: 'internalNotes' },
+    { type: 'renameLabel', field: 'customerReference', newLabel: 'PO Number' },
+  ],
+});
+
+const signed = await signOverlay(overlay, PRIVATE_KEY_PEM, { keyId: 'acme' });
+registry.register(signed);
+
+const result = engine.apply({
+  target: {
+    fields: baseFields,
+  },
+  context: { tenantId: 'acme', userId: 'u_123' },
+  capability: 'billing.createOrder',
+});
+```
+
+See `docs/tech/personalization/overlay-engine.md` for additional details.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

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,10 @@
+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 };

package/dist/merger.js

@@ -0,0 +1 @@
+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};

package/dist/react.d.ts

@@ -0,0 +1,9 @@
+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 };

package/dist/react.js

@@ -0,0 +1 @@
+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};

package/dist/registry.d.ts

@@ -0,0 +1,27 @@
+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 };

package/dist/registry.js

@@ -0,0 +1 @@
+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};

package/dist/runtime.d.ts

@@ -0,0 +1,27 @@
+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 };

package/dist/runtime.js

@@ -0,0 +1 @@
+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};

package/dist/signer.d.ts

@@ -0,0 +1,18 @@
+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 };

package/dist/signer.js

@@ -0,0 +1 @@
+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};

package/dist/spec.d.ts

@@ -0,0 +1,82 @@
+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 };

package/dist/spec.js

@@ -0,0 +1 @@
+const e=[`tenantId`,`role`,`userId`,`device`,`tags`];function t(e){return e}export{e as OVERLAY_SCOPE_ORDER,t as defineOverlay};

package/dist/types.d.ts

@@ -0,0 +1,32 @@
+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 };

package/dist/validator.d.ts

@@ -0,0 +1,18 @@
+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 };

package/dist/validator.js

@@ -0,0 +1 @@
+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};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@lssm/lib.overlay-engine",
+  "version": "0.0.0-canary-20251206160926",
+  "description": "Runtime overlay engine for ContractSpec personalization and adaptive UI rendering.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "build": "bun build:bundle && bun build:types",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "test": "bun run"
+  },
+  "dependencies": {
+    "@lssm/lib.contracts": "workspace:*",
+    "fast-json-stable-stringify": "^2.1.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@lssm/tool.tsdown": "workspace:*",
+    "@lssm/tool.typescript": "workspace:*",
+    "tsdown": "^0.17.0",
+    "typescript": "^5.9.3"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./react": "./dist/react.js",
+    "./*": "./*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}