@contractspec/example.personalization 3.7.6 → 3.7.10

package/dist/node/workflow-extension.js

@@ -1,7 +1,7 @@
 // src/workflow-extension.ts
 import { StabilityEnum } from "@contractspec/lib.contracts-spec";
-import { WorkflowComposer } from "@contractspec/lib.workflow-composer";
 import { Logger, LogLevel } from "@contractspec/lib.logger";
+import { WorkflowComposer } from "@contractspec/lib.workflow-composer";
 var logger = new Logger({
   level: LogLevel.INFO,
   environment: "production",

package/dist/overlay-customization.js

@@ -1,12 +1,12 @@
 // @bun
 // src/overlay-customization.ts
-import { defineOverlay } from "@contractspec/lib.overlay-engine/spec";
-import { signOverlay } from "@contractspec/lib.overlay-engine/signer";
+import { Logger, LogLevel } from "@contractspec/lib.logger";
 import {
   OverlayEngine,
   OverlayRegistry
 } from "@contractspec/lib.overlay-engine";
-import { Logger, LogLevel } from "@contractspec/lib.logger";
+import { signOverlay } from "@contractspec/lib.overlay-engine/signer";
+import { defineOverlay } from "@contractspec/lib.overlay-engine/spec";
 var logger = new Logger({
   level: LogLevel.INFO,
   environment: "production",

package/dist/personalization.experiment.d.ts

@@ -0,0 +1,2 @@
+import type { ExperimentSpec } from '@contractspec/lib.contracts-spec/experiments/spec';
+export declare const PersonalizationExperiment: ExperimentSpec;

package/dist/personalization.experiment.js

@@ -0,0 +1,63 @@
+// @bun
+// src/personalization.experiment.ts
+import {
+  OwnersEnum,
+  StabilityEnum
+} from "@contractspec/lib.contracts-spec/ownership";
+var PersonalizationExperiment = {
+  meta: {
+    key: "personalization.experiment.overlay-copy",
+    version: "1.0.0",
+    title: "Personalization Overlay Copy Experiment",
+    description: "Tests a control onboarding copy against a personalized overlay variant.",
+    domain: "personalization",
+    owners: [OwnersEnum.PlatformCore],
+    tags: ["personalization", "experiment", "overlay"],
+    stability: StabilityEnum.Experimental
+  },
+  controlVariant: "control",
+  variants: [
+    {
+      id: "control",
+      key: "control",
+      description: "Default onboarding copy and standard workflow."
+    },
+    {
+      id: "personalized-overlay",
+      key: "personalized-overlay",
+      description: "Personalized copy with a branded theme override.",
+      overrides: [
+        {
+          type: "theme",
+          target: "personalization.theme.guided-onboarding",
+          version: "1.0.0"
+        },
+        {
+          type: "workflow",
+          target: "billing.invoiceApproval",
+          version: "1.0.0"
+        }
+      ]
+    }
+  ],
+  allocation: {
+    type: "sticky",
+    attribute: "userId",
+    salt: "personalization-overlay-copy"
+  },
+  successMetrics: [
+    {
+      key: "checklist-completion-rate",
+      telemetryEvent: {
+        key: "personalization.assignment.completed",
+        version: "1.0.0"
+      },
+      aggregation: "count",
+      target: 1
+    }
+  ],
+  tags: ["personalization", "experiment"]
+};
+export {
+  PersonalizationExperiment
+};

package/dist/personalization.theme.d.ts

@@ -0,0 +1,2 @@
+import type { ThemeSpec } from '@contractspec/lib.contracts-spec/themes';
+export declare const PersonalizationTheme: ThemeSpec;

package/dist/personalization.theme.js

@@ -0,0 +1,65 @@
+// @bun
+// src/personalization.theme.ts
+import {
+  OwnersEnum,
+  StabilityEnum
+} from "@contractspec/lib.contracts-spec/ownership";
+var PersonalizationTheme = {
+  meta: {
+    key: "personalization.theme.guided-onboarding",
+    version: "1.0.0",
+    title: "Guided Onboarding Theme",
+    description: "Theme tokens used when the personalized onboarding experience is active.",
+    domain: "personalization",
+    owners: [OwnersEnum.PlatformCore],
+    tags: ["personalization", "theme", "onboarding"],
+    stability: StabilityEnum.Experimental,
+    scopes: ["tenant", "user"]
+  },
+  tokens: {
+    colors: {
+      surface: { value: "#FCF6E8" },
+      accent: { value: "#C8742A" },
+      text: { value: "#2F2419" }
+    },
+    radii: {
+      card: { value: 18 }
+    },
+    space: {
+      panel: { value: 24 }
+    },
+    typography: {
+      body: { value: 16 },
+      title: { value: 28 }
+    },
+    motion: {
+      stagger: { value: "180ms" }
+    }
+  },
+  components: [
+    {
+      component: "OnboardingChecklist",
+      variants: {
+        guided: {
+          props: {
+            emphasis: "warm"
+          }
+        }
+      }
+    }
+  ],
+  overrides: [
+    {
+      scope: "tenant",
+      target: "tenant:acme",
+      tokens: {
+        colors: {
+          accent: { value: "#8A4B12" }
+        }
+      }
+    }
+  ]
+};
+export {
+  PersonalizationTheme
+};

package/dist/workflow-extension.js

@@ -1,8 +1,8 @@
 // @bun
 // src/workflow-extension.ts
 import { StabilityEnum } from "@contractspec/lib.contracts-spec";
-import { WorkflowComposer } from "@contractspec/lib.workflow-composer";
 import { Logger, LogLevel } from "@contractspec/lib.logger";
+import { WorkflowComposer } from "@contractspec/lib.workflow-composer";
 var logger = new Logger({
   level: LogLevel.INFO,
   environment: "production",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/example.personalization",
-  "version": "3.7.6",
+  "version": "3.7.10",
   "description": "Personalization examples: behavior tracking, overlay customization, workflow extension.",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -47,6 +47,13 @@
       "node": "./dist/node/overlay-customization.js",
       "default": "./dist/overlay-customization.js"
     },
+    "./personalization.experiment": {
+      "types": "./dist/personalization.experiment.d.ts",
+      "browser": "./dist/browser/personalization.experiment.js",
+      "bun": "./dist/personalization.experiment.js",
+      "node": "./dist/node/personalization.experiment.js",
+      "default": "./dist/personalization.experiment.js"
+    },
     "./personalization.feature": {
       "types": "./dist/personalization.feature.d.ts",
       "browser": "./dist/browser/personalization.feature.js",
@@ -54,6 +61,13 @@
       "node": "./dist/node/personalization.feature.js",
       "default": "./dist/personalization.feature.js"
     },
+    "./personalization.theme": {
+      "types": "./dist/personalization.theme.d.ts",
+      "browser": "./dist/browser/personalization.theme.js",
+      "bun": "./dist/personalization.theme.js",
+      "node": "./dist/node/personalization.theme.js",
+      "default": "./dist/personalization.theme.js"
+    },
     "./workflow-extension": {
       "types": "./dist/workflow-extension.d.ts",
       "browser": "./dist/browser/workflow-extension.js",
@@ -71,23 +85,23 @@
     "dev": "contractspec-bun-build dev",
     "clean": "rimraf dist .turbo",
     "lint": "bun lint:fix",
-    "lint:fix": "eslint src --fix",
-    "lint:check": "eslint src",
+    "lint:fix": "biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .",
+    "lint:check": "biome check .",
     "test": "bun test --pass-with-no-tests",
     "prebuild": "contractspec-bun-build prebuild",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@contractspec/lib.personalization": "6.0.6",
-    "@contractspec/lib.overlay-engine": "3.7.6",
-    "@contractspec/lib.workflow-composer": "3.7.6",
-    "@contractspec/lib.contracts-spec": "3.7.6",
-    "@contractspec/lib.logger": "3.7.6"
+    "@contractspec/lib.personalization": "6.0.10",
+    "@contractspec/lib.overlay-engine": "3.7.10",
+    "@contractspec/lib.workflow-composer": "3.7.10",
+    "@contractspec/lib.contracts-spec": "4.1.2",
+    "@contractspec/lib.logger": "3.7.8"
   },
   "devDependencies": {
-    "@contractspec/tool.typescript": "3.7.6",
+    "@contractspec/tool.typescript": "3.7.8",
     "typescript": "^5.9.3",
-    "@contractspec/tool.bun": "3.7.6"
+    "@contractspec/tool.bun": "3.7.8"
   },
   "publishConfig": {
     "access": "public",
@@ -134,6 +148,13 @@
         "node": "./dist/node/overlay-customization.js",
         "default": "./dist/overlay-customization.js"
       },
+      "./personalization.experiment": {
+        "types": "./dist/personalization.experiment.d.ts",
+        "browser": "./dist/browser/personalization.experiment.js",
+        "bun": "./dist/personalization.experiment.js",
+        "node": "./dist/node/personalization.experiment.js",
+        "default": "./dist/personalization.experiment.js"
+      },
       "./personalization.feature": {
         "types": "./dist/personalization.feature.d.ts",
         "browser": "./dist/browser/personalization.feature.js",
@@ -141,6 +162,13 @@
         "node": "./dist/node/personalization.feature.js",
         "default": "./dist/personalization.feature.js"
       },
+      "./personalization.theme": {
+        "types": "./dist/personalization.theme.d.ts",
+        "browser": "./dist/browser/personalization.theme.js",
+        "bun": "./dist/personalization.theme.js",
+        "node": "./dist/node/personalization.theme.js",
+        "default": "./dist/personalization.theme.js"
+      },
       "./workflow-extension": {
         "types": "./dist/workflow-extension.d.ts",
         "browser": "./dist/browser/workflow-extension.js",

package/src/behavior-tracking.ts

@@ -1,47 +1,47 @@
-import { createBehaviorTracker } from '@contractspec/lib.personalization/tracker';
-import { InMemoryBehaviorStore } from '@contractspec/lib.personalization/store';
-import { BehaviorAnalyzer } from '@contractspec/lib.personalization/analyzer';
 import { Logger, LogLevel } from '@contractspec/lib.logger';
+import { BehaviorAnalyzer } from '@contractspec/lib.personalization/analyzer';
+import { InMemoryBehaviorStore } from '@contractspec/lib.personalization/store';
+import { createBehaviorTracker } from '@contractspec/lib.personalization/tracker';
 
 const logger = new Logger({
-  level: process.env.NODE_ENV === 'production' ? LogLevel.INFO : LogLevel.DEBUG,
-  environment:
-    (process.env.NODE_ENV as 'production' | 'development' | 'test') ||
-    'development',
-  enableColors: process.env.NODE_ENV !== 'production',
+	level: process.env.NODE_ENV === 'production' ? LogLevel.INFO : LogLevel.DEBUG,
+	environment:
+		(process.env.NODE_ENV as 'production' | 'development' | 'test') ||
+		'development',
+	enableColors: process.env.NODE_ENV !== 'production',
 });
 
 export async function runBehaviorTrackingExample(): Promise<void> {
-  const store = new InMemoryBehaviorStore();
-  const tracker = createBehaviorTracker({
-    store,
-    context: {
-      tenantId: 'acme',
-      userId: 'user-123',
-    },
-  });
+	const store = new InMemoryBehaviorStore();
+	const tracker = createBehaviorTracker({
+		store,
+		context: {
+			tenantId: 'acme',
+			userId: 'user-123',
+		},
+	});
 
-  tracker.trackFieldAccess({
-    operation: 'billing.createOrder',
-    field: 'internalNotes',
-  });
-  tracker.trackFieldAccess({
-    operation: 'billing.createOrder',
-    field: 'customerReference',
-  });
-  tracker.trackFeatureUsage({ feature: 'workflow-editor', action: 'opened' });
-  tracker.trackWorkflowStep({
-    workflow: 'invoice-approval',
-    step: 'review',
-    status: 'entered',
-  });
-  await tracker.flush();
+	tracker.trackFieldAccess({
+		operation: 'billing.createOrder',
+		field: 'internalNotes',
+	});
+	tracker.trackFieldAccess({
+		operation: 'billing.createOrder',
+		field: 'customerReference',
+	});
+	tracker.trackFeatureUsage({ feature: 'workflow-editor', action: 'opened' });
+	tracker.trackWorkflowStep({
+		workflow: 'invoice-approval',
+		step: 'review',
+		status: 'entered',
+	});
+	await tracker.flush();
 
-  const analyzer = new BehaviorAnalyzer(store);
-  const insights = await analyzer.analyze({
-    tenantId: 'acme',
-    userId: 'user-123',
-  });
+	const analyzer = new BehaviorAnalyzer(store);
+	const insights = await analyzer.analyze({
+		tenantId: 'acme',
+		userId: 'user-123',
+	});
 
-  logger.info('Behavior insights computed', { insights });
+	logger.info('Behavior insights computed', { insights });
 }

package/src/contracts.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from 'bun:test';
+import {
+	PersonalizationExperiment,
+	PersonalizationFeature,
+	PersonalizationTheme,
+} from './index';
+
+describe('@contractspec/example.personalization', () => {
+	test('exports the canonical experiment and theme', () => {
+		expect(PersonalizationExperiment.meta.key).toBe(
+			'personalization.experiment.overlay-copy'
+		);
+		expect(PersonalizationExperiment.variants).toHaveLength(2);
+		expect(PersonalizationTheme.meta.key).toBe(
+			'personalization.theme.guided-onboarding'
+		);
+		expect(PersonalizationTheme.overrides).toHaveLength(1);
+		expect(PersonalizationFeature.meta.key).toBe('personalization');
+	});
+});

package/src/docs/personalization.docblock.ts

@@ -2,27 +2,27 @@ import type { DocBlock } from '@contractspec/lib.contracts-spec/docs';
 import { registerDocBlocks } from '@contractspec/lib.contracts-spec/docs';
 
 const blocks: DocBlock[] = [
-  {
-    id: 'docs.examples.personalization',
-    title: 'Personalization Patterns (example)',
-    summary:
-      'Behavior tracking, overlay-driven UI tweaks, and tenant workflow extension patterns.',
-    kind: 'reference',
-    visibility: 'public',
-    route: '/docs/examples/personalization',
-    tags: ['personalization', 'overlays', 'workflows', 'example'],
-    body: `## Includes\n- Behavior tracking + insight analysis.\n- Overlay customization (hide fields, rename labels).\n- Workflow extension (inject tenant-specific steps).\n\n## Guardrails\n- Keep tracking events structured and non-PII.\n- Keep overlays signed and scoped.\n- Keep workflow composition deterministic.`,
-  },
-  {
-    id: 'docs.examples.personalization.usage',
-    title: 'Personalization — Usage',
-    summary: 'How to run the small examples and swap adapters.',
-    kind: 'usage',
-    visibility: 'public',
-    route: '/docs/examples/personalization/usage',
-    tags: ['personalization', 'usage'],
-    body: `## Usage\n- Call \`runBehaviorTrackingExample()\` for insights.\n- Call \`runOverlayCustomizationExample()\` to apply overlays.\n- Call \`composeTenantWorkflowExample()\` and \`logTenantWorkflowSteps()\` to inspect steps.\n\n## Notes\n- Replace in-memory stores with app-layer storage.\n- Keep PII out of logs and markdown outputs.`,
-  },
+	{
+		id: 'docs.examples.personalization',
+		title: 'Personalization Patterns (example)',
+		summary:
+			'Behavior tracking, overlay-driven UI tweaks, and tenant workflow extension patterns.',
+		kind: 'reference',
+		visibility: 'public',
+		route: '/docs/examples/personalization',
+		tags: ['personalization', 'overlays', 'workflows', 'example'],
+		body: `## Includes\n- Behavior tracking + insight analysis.\n- Overlay customization (hide fields, rename labels).\n- Workflow extension (inject tenant-specific steps).\n\n## Guardrails\n- Keep tracking events structured and non-PII.\n- Keep overlays signed and scoped.\n- Keep workflow composition deterministic.`,
+	},
+	{
+		id: 'docs.examples.personalization.usage',
+		title: 'Personalization — Usage',
+		summary: 'How to run the small examples and swap adapters.',
+		kind: 'usage',
+		visibility: 'public',
+		route: '/docs/examples/personalization/usage',
+		tags: ['personalization', 'usage'],
+		body: `## Usage\n- Call \`runBehaviorTrackingExample()\` for insights.\n- Call \`runOverlayCustomizationExample()\` to apply overlays.\n- Call \`composeTenantWorkflowExample()\` and \`logTenantWorkflowSteps()\` to inspect steps.\n\n## Notes\n- Replace in-memory stores with app-layer storage.\n- Keep PII out of logs and markdown outputs.`,
+	},
 ];
 
 registerDocBlocks(blocks);

package/src/example.ts

@@ -1,32 +1,32 @@
 import { defineExample } from '@contractspec/lib.contracts-spec';
 
 const example = defineExample({
-  meta: {
-    key: 'personalization',
-    version: '1.0.0',
-    title: 'Personalization Patterns',
-    description:
-      'Small examples for behavior tracking, overlay-based UI customization, and tenant workflow extension.',
-    kind: 'library',
-    visibility: 'public',
-    stability: 'experimental',
-    owners: ['@platform.core'],
-    tags: ['personalization', 'overlays', 'behavior', 'workflows'],
-  },
-  docs: {
-    rootDocId: 'docs.examples.personalization',
-    usageDocId: 'docs.examples.personalization.usage',
-  },
-  entrypoints: {
-    packageName: '@contractspec/example.personalization',
-    docs: './docs',
-  },
-  surfaces: {
-    templates: true,
-    sandbox: { enabled: true, modes: ['markdown', 'specs'] },
-    studio: { enabled: true, installable: true },
-    mcp: { enabled: true },
-  },
+	meta: {
+		key: 'personalization',
+		version: '1.0.0',
+		title: 'Personalization Patterns',
+		description:
+			'Small examples for behavior tracking, overlay-based UI customization, and tenant workflow extension.',
+		kind: 'library',
+		visibility: 'public',
+		stability: 'experimental',
+		owners: ['@platform.core'],
+		tags: ['personalization', 'overlays', 'behavior', 'workflows'],
+	},
+	docs: {
+		rootDocId: 'docs.examples.personalization',
+		usageDocId: 'docs.examples.personalization.usage',
+	},
+	entrypoints: {
+		packageName: '@contractspec/example.personalization',
+		docs: './docs',
+	},
+	surfaces: {
+		templates: true,
+		sandbox: { enabled: true, modes: ['markdown', 'specs'] },
+		studio: { enabled: true, installable: true },
+		mcp: { enabled: true },
+	},
 });
 
 export default example;

package/src/index.ts

@@ -1,6 +1,8 @@
 export * from './behavior-tracking';
+export { default as example } from './example';
 export * from './overlay-customization';
-export * from './workflow-extension';
+export * from './personalization.experiment';
 export * from './personalization.feature';
-export { default as example } from './example';
+export * from './personalization.theme';
+export * from './workflow-extension';
 import './docs';

package/src/overlay-customization.ts

@@ -1,57 +1,57 @@
-import { defineOverlay } from '@contractspec/lib.overlay-engine/spec';
-import { signOverlay } from '@contractspec/lib.overlay-engine/signer';
+import { Logger, LogLevel } from '@contractspec/lib.logger';
 import {
-  OverlayEngine,
-  OverlayRegistry,
+	OverlayEngine,
+	OverlayRegistry,
 } from '@contractspec/lib.overlay-engine';
-import { Logger, LogLevel } from '@contractspec/lib.logger';
+import { signOverlay } from '@contractspec/lib.overlay-engine/signer';
+import { defineOverlay } from '@contractspec/lib.overlay-engine/spec';
 
 const logger = new Logger({
-  level: process.env.NODE_ENV === 'production' ? LogLevel.INFO : LogLevel.DEBUG,
-  environment:
-    (process.env.NODE_ENV as 'production' | 'development' | 'test') ||
-    'development',
-  enableColors: process.env.NODE_ENV !== 'production',
+	level: process.env.NODE_ENV === 'production' ? LogLevel.INFO : LogLevel.DEBUG,
+	environment:
+		(process.env.NODE_ENV as 'production' | 'development' | 'test') ||
+		'development',
+	enableColors: process.env.NODE_ENV !== 'production',
 });
 
 export async function runOverlayCustomizationExample(): Promise<void> {
-  const registry = new OverlayRegistry({ allowUnsigned: true });
-  const engine = new OverlayEngine({ registry });
+	const registry = new OverlayRegistry({ allowUnsigned: true });
+	const engine = new OverlayEngine({ registry });
 
-  const overlay = defineOverlay({
-    overlayId: 'demo-overlay',
-    version: '1.0.0',
-    appliesTo: {
-      capability: 'billing.createOrder',
-      tenantId: 'demo',
-    },
-    modifications: [
-      { type: 'hideField', field: 'internalNotes' },
-      {
-        type: 'renameLabel',
-        field: 'customerReference',
-        newLabel: 'PO Number',
-      },
-    ],
-  });
+	const overlay = defineOverlay({
+		overlayId: 'demo-overlay',
+		version: '1.0.0',
+		appliesTo: {
+			capability: 'billing.createOrder',
+			tenantId: 'demo',
+		},
+		modifications: [
+			{ type: 'hideField', field: 'internalNotes' },
+			{
+				type: 'renameLabel',
+				field: 'customerReference',
+				newLabel: 'PO Number',
+			},
+		],
+	});
 
-  const signed = await signOverlay(overlay, process.env.PRIVATE_KEY_PEM ?? '');
-  registry.register(signed);
+	const signed = await signOverlay(overlay, process.env.PRIVATE_KEY_PEM ?? '');
+	registry.register(signed);
 
-  const result = engine.apply({
-    target: {
-      fields: [
-        {
-          key: 'customerReference',
-          label: 'Customer Reference',
-          visible: true,
-        },
-        { key: 'internalNotes', label: 'Internal Notes', visible: true },
-      ],
-    },
-    capability: 'billing.createOrder',
-    tenantId: 'demo',
-  });
+	const result = engine.apply({
+		target: {
+			fields: [
+				{
+					key: 'customerReference',
+					label: 'Customer Reference',
+					visible: true,
+				},
+				{ key: 'internalNotes', label: 'Internal Notes', visible: true },
+			],
+		},
+		capability: 'billing.createOrder',
+		tenantId: 'demo',
+	});
 
-  logger.info('Overlay applied', { fields: result.target.fields });
+	logger.info('Overlay applied', { fields: result.target.fields });
 }