@lssm/lib.overlay-engine 0.3.1 → 1.41.0

package/README.md

@@ -64,4 +64,9 @@ See `docs/tech/personalization/overlay-engine.md` for additional details.
 
 
 
+
+
+
+
+
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lssm/lib.overlay-engine",
-  "version": "0.3.1",
+  "version": "1.41.0",
   "description": "Runtime overlay engine for ContractSpec personalization and adaptive UI rendering.",
   "type": "module",
   "main": "./dist/index.js",
@@ -23,7 +23,7 @@
     "test": "bun run"
   },
   "dependencies": {
-    "@lssm/lib.contracts": "1.11.1",
+    "@lssm/lib.contracts": "workspace:*",
     "fast-json-stable-stringify": "^2.1.0"
   },
   "peerDependencies": {
@@ -35,17 +35,36 @@
     }
   },
   "devDependencies": {
-    "@lssm/tool.tsdown": "0.12.1",
-    "@lssm/tool.typescript": "0.11.1",
-    "tsdown": "^0.16.6",
+    "@lssm/tool.tsdown": "workspace:*",
+    "@lssm/tool.typescript": "workspace:*",
+    "tsdown": "^0.17.4",
     "typescript": "^5.9.3"
   },
   "exports": {
-    ".": "./dist/index.js",
-    "./react": "./dist/react.js",
+    ".": "./src/index.ts",
+    "./merger": "./src/merger.ts",
+    "./react": "./src/react.ts",
+    "./registry": "./src/registry.ts",
+    "./runtime": "./src/runtime.ts",
+    "./signer": "./src/signer.ts",
+    "./spec": "./src/spec.ts",
+    "./types": "./src/types.ts",
+    "./validator": "./src/validator.ts",
     "./*": "./*"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "exports": {
+      ".": "./dist/index.js",
+      "./merger": "./dist/merger.js",
+      "./react": "./dist/react.js",
+      "./registry": "./dist/registry.js",
+      "./runtime": "./dist/runtime.js",
+      "./signer": "./dist/signer.js",
+      "./spec": "./dist/spec.js",
+      "./types": "./dist/types.js",
+      "./validator": "./dist/validator.js",
+      "./*": "./*"
+    }
   }
 }

package/dist/index.d.ts

@@ -1,8 +0,0 @@
-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/merger.d.ts

@@ -1,10 +0,0 @@
-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/react.d.ts

@@ -1,9 +0,0 @@
-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/registry.d.ts

@@ -1,27 +0,0 @@
-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/runtime.d.ts

@@ -1,27 +0,0 @@
-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/signer.d.ts

@@ -1,18 +0,0 @@
-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/spec.d.ts

@@ -1,82 +0,0 @@
-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/types.d.ts

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

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