@contractspec/lib.overlay-engine 1.57.0 → 1.59.0

package/dist/react.js

@@ -1,23 +1,22 @@
+// @bun
+// src/react.ts
 import { useMemo } from "react";
-
-//#region src/react.ts
 function useOverlay(engine, params, deps = []) {
-	return useMemo(() => {
-		if (!engine) return {
-			target: params.target,
-			overlaysApplied: []
-		};
-		return engine.apply(params);
-	}, [
-		engine,
-		params,
-		...deps
-	]);
+  return useMemo(() => {
+    if (!engine) {
+      return {
+        target: params.target,
+        overlaysApplied: []
+      };
+    }
+    return engine.apply(params);
+  }, [engine, params, ...deps]);
 }
 function useOverlayFields(engine, params, deps = []) {
-	return useOverlay(engine, params, deps).target.fields;
+  const result = useOverlay(engine, params, deps);
+  return result.target.fields;
 }
-
-//#endregion
-export { useOverlay, useOverlayFields };
-//# sourceMappingURL=react.js.map
+export {
+  useOverlayFields,
+  useOverlay
+};

package/dist/registry.d.ts

@@ -1,28 +1,25 @@
-import { OverlayInput, OverlayScopeContext, OverlayTargetRef, SignedOverlaySpec } from "./spec.js";
-import { OverlayValidator } from "./validator.js";
-
-//#region src/registry.d.ts
-interface OverlayRegistryOptions {
-  validator?: OverlayValidator;
-  allowUnsigned?: boolean;
+import type { OverlayInput, OverlayScopeContext, OverlayTargetRef, SignedOverlaySpec } from './spec';
+import type { OverlayValidator } from './validator';
+export 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;
+export interface OverlayLookup extends OverlayScopeContext, OverlayTargetRef {
+}
+export 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

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","names":[],"sources":["../src/registry.ts"],"mappings":";;;;UAUiB,sBAAA;EACf,SAAA,GAAY,gBAAA;EACZ,aAAA;AAAA;AAAA,UAGe,aAAA,SAAsB,mBAAA,EAAqB,gBAAA;AAAA,cAwB/C,eAAA;EAAA,iBAGkB,OAAA;EAAA,iBAFZ,QAAA;cAEY,OAAA,GAAS,sBAAA;EAEtC,QAAA,CACE,OAAA,EAAS,YAAA,EACT,OAAA;IAAY,cAAA;EAAA,IACX,iBAAA;EAyBH,UAAA,CAAW,SAAA,UAAmB,OAAA;EAa9B,IAAA,CAAA,GAAQ,iBAAA;EAIR,GAAA,CAAI,SAAA,UAAmB,OAAA,WAAkB,iBAAA;EAIzC,UAAA,CAAW,KAAA,EAAO,aAAA,GAAgB,iBAAA;EAYlC,KAAA,CAAA;EAIA,IAAA,CAAA;EAAA,QAIQ,YAAA;EAAA,QAiBA,MAAA;AAAA"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EAEZ,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,QAAQ,CAAC;AAChB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD,MAAM,WAAW,sBAAsB;IACrC,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,aAAc,SAAQ,mBAAmB,EAAE,gBAAgB;CAAG;AAwB/E,qBAAa,eAAe;IAGd,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;gBAEhC,OAAO,GAAE,sBAA2B;IAEjE,QAAQ,CACN,OAAO,EAAE,YAAY,EACrB,OAAO,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,OAAO,CAAA;KAAE,GACrC,iBAAiB;IAyBpB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;IAa9C,IAAI,IAAI,iBAAiB,EAAE;IAI3B,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAItE,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,iBAAiB,EAAE;IAYrD,KAAK;IAIL,IAAI,IAAI,MAAM;IAId,OAAO,CAAC,YAAY;IAiBpB,OAAO,CAAC,MAAM;CAGf"}

package/dist/registry.js

@@ -1,107 +1,263 @@
-import { defaultOverlayValidator } from "./validator.js";
+// @bun
+// src/validator.ts
+var TARGET_KEYS = [
+  "capability",
+  "workflow",
+  "dataView",
+  "presentation",
+  "operation"
+];
+var defaultOverlayValidator = (spec) => validateOverlaySpec(spec);
+function validateOverlaySpec(spec) {
+  const issues = [];
+  if (!spec.overlayId?.trim()) {
+    issues.push({
+      code: "overlay.id",
+      message: "overlayId is required",
+      path: ["overlayId"]
+    });
+  }
+  if (!spec.version?.trim()) {
+    issues.push({
+      code: "overlay.version",
+      message: "version is required",
+      path: ["version"]
+    });
+  }
+  const hasTarget = TARGET_KEYS.some((key) => {
+    const value = spec.appliesTo?.[key];
+    return typeof value === "string" && value.trim().length > 0;
+  });
+  if (!hasTarget) {
+    issues.push({
+      code: "overlay.target",
+      message: "Overlay must specify at least one target (capability, workflow, dataView, presentation, or operation).",
+      path: ["appliesTo"]
+    });
+  }
+  if (!spec.modifications?.length) {
+    issues.push({
+      code: "overlay.modifications.empty",
+      message: "Overlay must include at least one modification.",
+      path: ["modifications"]
+    });
+  } else {
+    spec.modifications.forEach((mod, idx) => {
+      const path = ["modifications", String(idx)];
+      validateModification(mod, path, issues);
+    });
+  }
+  return {
+    valid: issues.length === 0,
+    issues
+  };
+}
+function validateModification(modification, path, issues) {
+  const push = (code, message, extraPath) => {
+    issues.push({
+      code,
+      message,
+      path: extraPath ? [...path, ...extraPath] : path
+    });
+  };
+  if (isFieldModification(modification)) {
+    if (!modification.field?.trim()) {
+      push("overlay.mod.field", "field is required for this modification", [
+        "field"
+      ]);
+    }
+  }
+  switch (modification.type) {
+    case "renameLabel": {
+      if (!modification.newLabel?.trim()) {
+        push("overlay.mod.renameLabel.newLabel", "newLabel is required", [
+          "newLabel"
+        ]);
+      }
+      break;
+    }
+    case "reorderFields": {
+      if (!modification.fields?.length) {
+        push("overlay.mod.reorderFields.fields", "fields list cannot be empty", ["fields"]);
+      }
+      const seen = new Set;
+      for (const field of modification.fields ?? []) {
+        if (!field?.trim()) {
+          push("overlay.mod.reorderFields.fields.blank", "fields entries must be non-empty");
+          break;
+        }
+        if (seen.has(field)) {
+          push("overlay.mod.reorderFields.fields.duplicate", `field "${field}" was listed multiple times`);
+          break;
+        }
+        seen.add(field);
+      }
+      break;
+    }
+    case "setDefault": {
+      if (modification.value === undefined) {
+        push("overlay.mod.setDefault.value", "value is required", ["value"]);
+      }
+      break;
+    }
+    case "addHelpText": {
+      if (!modification.text?.trim()) {
+        push("overlay.mod.addHelpText.text", "text is required", ["text"]);
+      }
+      break;
+    }
+    case "makeRequired":
+    case "hideField":
+      break;
+    default: {
+      const exhaustive = modification;
+      throw new Error(`Unsupported overlay modification ${exhaustive?.type ?? "unknown"}`);
+    }
+  }
+}
+function isFieldModification(mod) {
+  return "field" in mod;
+}
+function assertOverlayValid(spec, validator = defaultOverlayValidator) {
+  const result = validator(spec);
+  if (!result.valid) {
+    const message = result.issues.map((issue) => `${issue.code}: ${issue.message}`).join("; ");
+    throw new Error(`Invalid OverlaySpec "${spec.overlayId}": ${message}`);
+  }
+}
 
-//#region src/registry.ts
-const TARGET_KEYS = [
-	"capability",
-	"workflow",
-	"dataView",
-	"presentation",
-	"operation"
+// src/registry.ts
+var TARGET_KEYS2 = [
+  "capability",
+  "workflow",
+  "dataView",
+  "presentation",
+  "operation"
 ];
-const SCOPE_WEIGHTS = {
-	tenantId: 8,
-	role: 4,
-	userId: 16,
-	device: 2,
-	tags: 1
-};
-var OverlayRegistry = class {
-	overlays = /* @__PURE__ */ new Map();
-	constructor(options = {}) {
-		this.options = options;
-	}
-	register(overlay, options) {
-		if (!options?.skipValidation) {
-			const result = (this.options.validator ?? defaultOverlayValidator)(overlay);
-			if (!result.valid) {
-				const reason = result.issues.map((issue) => `${issue.code}: ${issue.message}`).join("; ");
-				throw new Error(`Overlay "${overlay.overlayId}" failed validation: ${reason}`);
-			}
-		}
-		const normalized = this.ensureSigned(overlay);
-		const key = this.getKey(normalized.overlayId, normalized.version);
-		const stored = {
-			overlay: normalized,
-			specificity: computeSpecificity(normalized.appliesTo),
-			registeredAt: Date.now()
-		};
-		this.overlays.set(key, stored);
-		return normalized;
-	}
-	unregister(overlayId, version) {
-		if (version) {
-			this.overlays.delete(this.getKey(overlayId, version));
-			return;
-		}
-		for (const key of Array.from(this.overlays.keys())) if (key.startsWith(`${overlayId}@`)) this.overlays.delete(key);
-	}
-	list() {
-		return Array.from(this.overlays.values()).map((entry) => entry.overlay);
-	}
-	get(overlayId, version) {
-		return this.overlays.get(this.getKey(overlayId, version))?.overlay;
-	}
-	forContext(query) {
-		return Array.from(this.overlays.values()).filter((entry) => matches(entry.overlay.appliesTo, query)).sort((a, b) => {
-			if (a.specificity !== b.specificity) return a.specificity - b.specificity;
-			return a.registeredAt - b.registeredAt;
-		}).map((entry) => entry.overlay);
-	}
-	clear() {
-		this.overlays.clear();
-	}
-	size() {
-		return this.overlays.size;
-	}
-	ensureSigned(input) {
-		if (isSignedOverlay(input)) {
-			if (!input.signature?.signature && !this.options.allowUnsigned) throw new Error(`Overlay "${input.overlayId}" is missing a signature.`);
-			return input;
-		}
-		if (!this.options.allowUnsigned) throw new Error(`Overlay "${input.overlayId}" must be signed before registration.`);
-		return input;
-	}
-	getKey(overlayId, version) {
-		return `${overlayId}@${version}`;
-	}
+var SCOPE_WEIGHTS = {
+  tenantId: 8,
+  role: 4,
+  userId: 16,
+  device: 2,
+  tags: 1
 };
+
+class OverlayRegistry {
+  options;
+  overlays = new Map;
+  constructor(options = {}) {
+    this.options = options;
+  }
+  register(overlay, options) {
+    if (!options?.skipValidation) {
+      const validator = this.options.validator ?? defaultOverlayValidator;
+      const result = validator(overlay);
+      if (!result.valid) {
+        const reason = result.issues.map((issue) => `${issue.code}: ${issue.message}`).join("; ");
+        throw new Error(`Overlay "${overlay.overlayId}" failed validation: ${reason}`);
+      }
+    }
+    const normalized = this.ensureSigned(overlay);
+    const key = this.getKey(normalized.overlayId, normalized.version);
+    const stored = {
+      overlay: normalized,
+      specificity: computeSpecificity(normalized.appliesTo),
+      registeredAt: Date.now()
+    };
+    this.overlays.set(key, stored);
+    return normalized;
+  }
+  unregister(overlayId, version) {
+    if (version) {
+      this.overlays.delete(this.getKey(overlayId, version));
+      return;
+    }
+    for (const key of Array.from(this.overlays.keys())) {
+      if (key.startsWith(`${overlayId}@`)) {
+        this.overlays.delete(key);
+      }
+    }
+  }
+  list() {
+    return Array.from(this.overlays.values()).map((entry) => entry.overlay);
+  }
+  get(overlayId, version) {
+    return this.overlays.get(this.getKey(overlayId, version))?.overlay;
+  }
+  forContext(query) {
+    return Array.from(this.overlays.values()).filter((entry) => matches(entry.overlay.appliesTo, query)).sort((a, b) => {
+      if (a.specificity !== b.specificity) {
+        return a.specificity - b.specificity;
+      }
+      return a.registeredAt - b.registeredAt;
+    }).map((entry) => entry.overlay);
+  }
+  clear() {
+    this.overlays.clear();
+  }
+  size() {
+    return this.overlays.size;
+  }
+  ensureSigned(input) {
+    if (isSignedOverlay(input)) {
+      if (!input.signature?.signature && !this.options.allowUnsigned) {
+        throw new Error(`Overlay "${input.overlayId}" is missing a signature.`);
+      }
+      return input;
+    }
+    if (!this.options.allowUnsigned) {
+      throw new Error(`Overlay "${input.overlayId}" must be signed before registration.`);
+    }
+    return input;
+  }
+  getKey(overlayId, version) {
+    return `${overlayId}@${version}`;
+  }
+}
 function isSignedOverlay(spec) {
-	return Boolean(spec.signature);
+  return Boolean(spec.signature);
 }
 function computeSpecificity(appliesTo) {
-	let score = 0;
-	Object.keys(SCOPE_WEIGHTS).forEach((key) => {
-		if (key === "tags" ? Array.isArray(appliesTo.tags) && appliesTo.tags.length > 0 : Boolean(appliesTo[key])) score += SCOPE_WEIGHTS[key];
-	});
-	return score;
+  let score = 0;
+  Object.keys(SCOPE_WEIGHTS).forEach((key) => {
+    const hasValue = key === "tags" ? Array.isArray(appliesTo.tags) && appliesTo.tags.length > 0 : Boolean(appliesTo[key]);
+    if (hasValue) {
+      score += SCOPE_WEIGHTS[key];
+    }
+  });
+  return score;
 }
 function matches(appliesTo, ctx) {
-	for (const key of TARGET_KEYS) {
-		const expected = appliesTo[key];
-		if (expected && expected !== ctx[key]) return false;
-	}
-	if (appliesTo.tenantId && appliesTo.tenantId !== ctx.tenantId) return false;
-	if (appliesTo.role && appliesTo.role !== ctx.role) return false;
-	if (appliesTo.userId && appliesTo.userId !== ctx.userId) return false;
-	if (appliesTo.device && appliesTo.device !== ctx.device) return false;
-	if (appliesTo.tags?.length) {
-		if (!ctx.tags?.length) return false;
-		const ctxTags = new Set(ctx.tags);
-		if (!appliesTo.tags.every((tag) => ctxTags.has(tag))) return false;
-	}
-	return true;
+  for (const key of TARGET_KEYS2) {
+    const expected = appliesTo[key];
+    if (expected && expected !== ctx[key]) {
+      return false;
+    }
+  }
+  if (appliesTo.tenantId && appliesTo.tenantId !== ctx.tenantId) {
+    return false;
+  }
+  if (appliesTo.role && appliesTo.role !== ctx.role) {
+    return false;
+  }
+  if (appliesTo.userId && appliesTo.userId !== ctx.userId) {
+    return false;
+  }
+  if (appliesTo.device && appliesTo.device !== ctx.device) {
+    return false;
+  }
+  if (appliesTo.tags?.length) {
+    if (!ctx.tags?.length) {
+      return false;
+    }
+    const ctxTags = new Set(ctx.tags);
+    const satisfies = appliesTo.tags.every((tag) => ctxTags.has(tag));
+    if (!satisfies) {
+      return false;
+    }
+  }
+  return true;
 }
-
-//#endregion
-export { OverlayRegistry };
-//# sourceMappingURL=registry.js.map
+export {
+  OverlayRegistry
+};

package/dist/runtime.d.ts

@@ -1,28 +1,24 @@
-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;
+import { type ApplyOverlayOptions } from './merger';
+import { OverlayRegistry, type OverlayLookup } from './registry';
+import type { SignedOverlaySpec } from './spec';
+import type { OverlayRenderable, OverlayAuditEvent } from './types';
+export interface OverlayEngineOptions {
+    registry: OverlayRegistry;
+    audit?: (event: OverlayAuditEvent) => void;
 }
-interface OverlayApplyParams<T extends OverlayRenderable> extends OverlayLookup {
-  target: T;
-  overlays?: SignedOverlaySpec[];
-  strict?: ApplyOverlayOptions['strict'];
+export interface OverlayApplyParams<T extends OverlayRenderable> extends OverlayLookup {
+    target: T;
+    overlays?: SignedOverlaySpec[];
+    strict?: ApplyOverlayOptions['strict'];
 }
-interface OverlayRuntimeResult<T extends OverlayRenderable> {
-  target: T;
-  overlaysApplied: SignedOverlaySpec[];
+export 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>;
+export 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

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","names":[],"sources":["../src/runtime.ts"],"mappings":";;;;;;UAKiB,oBAAA;EACf,QAAA,EAAU,eAAA;EACV,KAAA,IAAS,KAAA,EAAO,iBAAA;AAAA;AAAA,UAGD,kBAAA,WACL,iBAAA,UACF,aAAA;EACR,MAAA,EAAQ,CAAA;EACR,QAAA,GAAW,iBAAA;EACX,MAAA,GAAS,mBAAA;AAAA;AAAA,UAGM,oBAAA,WAA+B,iBAAA;EAC9C,MAAA,EAAQ,CAAA;EACR,eAAA,EAAiB,iBAAA;AAAA;AAAA,cAGN,aAAA;EAAA,iBACM,QAAA;EAAA,iBACA,KAAA;cAEL,OAAA,EAAS,oBAAA;EAKrB,KAAA,WAAgB,iBAAA,CAAA,CACd,MAAA,EAAQ,kBAAA,CAAmB,CAAA,IAC1B,oBAAA,CAAqB,CAAA;AAAA"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAC/E,OAAO,EAAE,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AACjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAChD,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEpE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,eAAe,CAAC;IAC1B,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,kBAAkB,CACjC,CAAC,SAAS,iBAAiB,CAC3B,SAAQ,aAAa;IACrB,MAAM,EAAE,CAAC,CAAC;IACV,QAAQ,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAC/B,MAAM,CAAC,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,oBAAoB,CAAC,CAAC,SAAS,iBAAiB;IAC/D,MAAM,EAAE,CAAC,CAAC;IACV,eAAe,EAAE,iBAAiB,EAAE,CAAC;CACtC;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAqC;gBAEhD,OAAO,EAAE,oBAAoB;IAKzC,KAAK,CAAC,CAAC,SAAS,iBAAiB,EAC/B,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAC5B,oBAAoB,CAAC,CAAC,CAAC;CAqC3B"}