@holoscript/plugin-retail-ecommerce 2.0.1 → 2.0.2

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@holoscript/plugin-retail-ecommerce",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "HoloScript domain plugin for retail-ecommerce",
   "main": "src/index.ts",
   "peerDependencies": {
-    "@holoscript/core": "8.0.6"
+    "@holoscript/core": ">=8.0.0"
   },
   "license": "MIT",
   "scripts": {
     "test": "vitest run --passWithNoTests",
     "test:coverage": "vitest run --coverage --passWithNoTests"
   }
-}
+}

package/src/__tests__/retailsolver.test.ts

@@ -30,7 +30,7 @@ describe('economicOrderQuantity', () => {
    */
   it('EOQ = √(2DS/H)', () => {
     const r = economicOrderQuantity(1000, 10, 2.5);
-    expect(r.eoq).toBeCloseTo(Math.sqrt(2 * 1000 * 10 / 2.5), 1);
+    expect(r.eoq).toBeCloseTo(Math.sqrt((2 * 1000 * 10) / 2.5), 1);
   });
 
   it('ordersPerYear = demand / EOQ', () => {
@@ -150,12 +150,12 @@ describe('customerLifetimeValue', () => {
    * Discounted CLV = Σ_{t=1}^{5} 400 / 1.1^t ≈ 400 × 3.791 ≈ $1516
    */
   it('simpleCLV = AOV × frequency × lifespan', () => {
-    const r = customerLifetimeValue(100, 4, 5, 0.10);
+    const r = customerLifetimeValue(100, 4, 5, 0.1);
     expect(r.simpleCLV).toBeCloseTo(2000, 4);
   });
 
   it('discountedCLV < simpleCLV for positive discount rate', () => {
-    const r = customerLifetimeValue(100, 4, 5, 0.10);
+    const r = customerLifetimeValue(100, 4, 5, 0.1);
     expect(r.discountedCLV).toBeLessThan(r.simpleCLV);
   });
 
@@ -165,18 +165,18 @@ describe('customerLifetimeValue', () => {
   });
 
   it('CLV:CAC ratio computed when CAC provided', () => {
-    const r = customerLifetimeValue(100, 4, 5, 0.10, 200);
+    const r = customerLifetimeValue(100, 4, 5, 0.1, 200);
     expect(r.clvToCac).not.toBeNull();
     expect(r.clvToCac!).toBeCloseTo(r.discountedCLV / 200, 4);
   });
 
   it('CLV:CAC null when CAC not provided', () => {
-    const r = customerLifetimeValue(100, 4, 5, 0.10);
+    const r = customerLifetimeValue(100, 4, 5, 0.1);
     expect(r.clvToCac).toBeNull();
   });
 
   it('throws for zero AOV', () => {
-    expect(() => customerLifetimeValue(0, 4, 5, 0.10)).toThrow();
+    expect(() => customerLifetimeValue(0, 4, 5, 0.1)).toThrow();
   });
 });
 
@@ -194,9 +194,9 @@ describe('conversionFunnelAnalysis', () => {
 
   it('step conversions correct', () => {
     const r = conversionFunnelAnalysis(stages, counts, 75);
-    expect(r.stepConversions[0]).toBeCloseTo(0.20, 4);
+    expect(r.stepConversions[0]).toBeCloseTo(0.2, 4);
     expect(r.stepConversions[1]).toBeCloseTo(0.25, 4);
-    expect(r.stepConversions[2]).toBeCloseTo(0.50, 4);
+    expect(r.stepConversions[2]).toBeCloseTo(0.5, 4);
   });
 
   it('overall conversion = final / first', () => {
@@ -222,9 +222,9 @@ describe('conversionFunnelAnalysis', () => {
 
 describe('abcClassification', () => {
   const items = [
-    { id: 'SKU-1', annualVolume: 100, unitCost: 500 },  // $50k — A
-    { id: 'SKU-2', annualVolume: 500, unitCost: 20  },  // $10k — A/B
-    { id: 'SKU-3', annualVolume: 1000, unitCost: 5  },  // $5k  — B
+    { id: 'SKU-1', annualVolume: 100, unitCost: 500 }, // $50k — A
+    { id: 'SKU-2', annualVolume: 500, unitCost: 20 }, // $10k — A/B
+    { id: 'SKU-3', annualVolume: 1000, unitCost: 5 }, // $5k  — B
     { id: 'SKU-4', annualVolume: 5000, unitCost: 0.5 }, // $2.5k — C
     { id: 'SKU-5', annualVolume: 2000, unitCost: 0.2 }, // $400  — C
   ];
@@ -303,13 +303,13 @@ describe('buildRetailReceipt', () => {
   });
 
   it('accepted=true for healthy metrics', () => {
-    const clv = customerLifetimeValue(200, 5, 3, 0.10, 150); // CLV:CAC ≈ 3+
+    const clv = customerLifetimeValue(200, 5, 3, 0.1, 150); // CLV:CAC ≈ 3+
     const receipt = buildRetailReceipt({ clv, converged: true });
     expect(receipt.acceptance.accepted).toBe(true);
   });
 
   it('accepted=false when CLV:CAC < 3', () => {
-    const clv = customerLifetimeValue(50, 1, 1, 0.10, 500); // poor CLV:CAC
+    const clv = customerLifetimeValue(50, 1, 1, 0.1, 500); // poor CLV:CAC
     const receipt = buildRetailReceipt({ clv, converged: true });
     if (clv.clvToCac! < 3) {
       expect(receipt.acceptance.accepted).toBe(false);

package/src/__tests__/runtime-integration.test.ts

@@ -79,9 +79,7 @@ describe('retail-ecommerce -> HoloScript runtime integration (eoq)', () => {
     await flush();
 
     const state = runtime.getState() as Record<string, unknown>;
-    const persisted = state['eoq:retail'] as
-      | { eoq?: number; annualDemand?: number }
-      | undefined;
+    const persisted = state['eoq:retail'] as { eoq?: number; annualDemand?: number } | undefined;
     expect(persisted).toBeDefined();
     expect(persisted?.eoq).toBeCloseTo(EXPECTED_EOQ, 5);
     expect(persisted?.annualDemand).toBe(1000);
@@ -97,9 +95,7 @@ describe('retail-ecommerce -> HoloScript runtime integration (eoq)', () => {
     });
 
     // holdingCostPerUnit omitted -> the handler emits eoq_error, never throws.
-    await runtime.executeNode(
-      eoqOrb({ annualDemand: 1000, orderingCost: 10 }) as never,
-    );
+    await runtime.executeNode(eoqOrb({ annualDemand: 1000, orderingCost: 10 }) as never);
     await flush();
 
     expect(errors).toHaveLength(1);

package/src/index.ts

@@ -1,7 +1,26 @@
-export { createCartHandler, type CartConfig, type CartItem, type CartState } from './traits/CartTrait';
-export { createCheckoutHandler, type CheckoutConfig, type CheckoutStep, type PaymentMethod, type Address } from './traits/CheckoutTrait';
-export { createProductCatalogHandler, type ProductCatalogConfig, type Product } from './traits/ProductCatalogTrait';
-export { createShippingRateHandler, type ShippingRateConfig, type ShippingMethod } from './traits/ShippingRateTrait';
+export {
+  createCartHandler,
+  type CartConfig,
+  type CartItem,
+  type CartState,
+} from './traits/CartTrait';
+export {
+  createCheckoutHandler,
+  type CheckoutConfig,
+  type CheckoutStep,
+  type PaymentMethod,
+  type Address,
+} from './traits/CheckoutTrait';
+export {
+  createProductCatalogHandler,
+  type ProductCatalogConfig,
+  type Product,
+} from './traits/ProductCatalogTrait';
+export {
+  createShippingRateHandler,
+  type ShippingRateConfig,
+  type ShippingMethod,
+} from './traits/ShippingRateTrait';
 export { createReturnHandler, type ReturnConfig, type ReturnStatus } from './traits/ReturnTrait';
 export * from './traits/types';
 
@@ -12,7 +31,29 @@ import { createShippingRateHandler } from './traits/ShippingRateTrait';
 import { createReturnHandler } from './traits/ReturnTrait';
 
 export * from './retailsolver';
-export * from './runtime';
 
-export const pluginMeta = { name: '@holoscript/plugin-retail-ecommerce', version: '1.0.0', traits: ['cart', 'checkout', 'product_catalog', 'shipping_rate', 'return', 'eoq', 'price_optimization', 'markdown', 'clv', 'conversion_funnel', 'abc_classification', 'inventory_metrics'] };
-export const traitHandlers = [createCartHandler(), createCheckoutHandler(), createProductCatalogHandler(), createShippingRateHandler(), createReturnHandler()];
+export const pluginMeta = {
+  name: '@holoscript/plugin-retail-ecommerce',
+  version: '1.0.0',
+  traits: [
+    'cart',
+    'checkout',
+    'product_catalog',
+    'shipping_rate',
+    'return',
+    'eoq',
+    'price_optimization',
+    'markdown',
+    'clv',
+    'conversion_funnel',
+    'abc_classification',
+    'inventory_metrics',
+  ],
+};
+export const traitHandlers = [
+  createCartHandler(),
+  createCheckoutHandler(),
+  createProductCatalogHandler(),
+  createShippingRateHandler(),
+  createReturnHandler(),
+];

package/src/retailsolver.ts

@@ -62,7 +62,12 @@ export interface MarkdownResult {
   /** Days until season end */
   daysRemaining: number;
   /** Optimal markdown schedule */
-  schedule: Array<{ dayOfMarkdown: number; discountPct: number; price: number; expectedUnits: number }>;
+  schedule: Array<{
+    dayOfMarkdown: number;
+    discountPct: number;
+    price: number;
+    expectedUnits: number;
+  }>;
   /** Expected total revenue */
   expectedRevenue: number;
   /** Expected unsold units */
@@ -126,7 +131,7 @@ export function economicOrderQuantity(
   orderingCost: number,
   holdingCostPerUnit: number,
   leadTimeDays = 0,
-  workingDaysPerYear = 250,
+  workingDaysPerYear = 250
 ): EOQResult {
   if (annualDemand <= 0) throw new Error('annualDemand must be positive');
   if (orderingCost <= 0) throw new Error('orderingCost must be positive');
@@ -138,7 +143,15 @@ export function economicOrderQuantity(
   const dailyDemand = annualDemand / workingDaysPerYear;
   const reorderPoint = dailyDemand * leadTimeDays;
 
-  return { annualDemand, orderingCost, holdingCostPerUnit, eoq, ordersPerYear, totalAnnualCost, reorderPoint };
+  return {
+    annualDemand,
+    orderingCost,
+    holdingCostPerUnit,
+    eoq,
+    ordersPerYear,
+    totalAnnualCost,
+    reorderPoint,
+  };
 }
 
 // ─── Price optimization via demand elasticity ─────────────────────────────────
@@ -159,7 +172,7 @@ export function priceOptimization(
   currentDemand: number,
   elasticity: number,
   variableCost = 0,
-  priceRange?: [number, number],
+  priceRange?: [number, number]
 ): PriceOptimizationResult {
   if (currentPrice <= 0) throw new Error('currentPrice must be positive');
   if (currentDemand <= 0) throw new Error('currentDemand must be positive');
@@ -167,22 +180,24 @@ export function priceOptimization(
 
   const demandAt = (p: number) => currentDemand * Math.pow(p / currentPrice, elasticity);
   const revenueAt = (p: number) => p * demandAt(p);
-  const profitAt  = (p: number) => (p - variableCost) * demandAt(p);
+  const profitAt = (p: number) => (p - variableCost) * demandAt(p);
 
   // Profit-maximizing price via ternary search
   const pLo = priceRange ? priceRange[0] : variableCost * 1.01;
   const pHi = priceRange ? priceRange[1] : currentPrice * 3;
 
-  let lo = Math.max(pLo, variableCost + 0.01), hi = pHi;
+  let lo = Math.max(pLo, variableCost + 0.01),
+    hi = pHi;
   for (let i = 0; i < 100; i++) {
     const m1 = lo + (hi - lo) / 3;
     const m2 = hi - (hi - lo) / 3;
-    if (profitAt(m1) < profitAt(m2)) lo = m1; else hi = m2;
+    if (profitAt(m1) < profitAt(m2)) lo = m1;
+    else hi = m2;
   }
   const optimalPrice = (lo + hi) / 2;
 
-  const currentRevenue  = revenueAt(currentPrice);
-  const optimalRevenue  = revenueAt(optimalPrice);
+  const currentRevenue = revenueAt(currentPrice);
+  const optimalRevenue = revenueAt(optimalPrice);
   const revenueUpliftPct = ((optimalRevenue - currentRevenue) / currentRevenue) * 100;
 
   // Price-demand curve: 20 points from 50% to 200% of current price
@@ -191,7 +206,15 @@ export function priceOptimization(
     return { price: p, demand: demandAt(p), revenue: revenueAt(p) };
   });
 
-  return { currentPrice, elasticity, optimalPrice, currentRevenue, optimalRevenue, revenueUpliftPct, priceDemandCurve };
+  return {
+    currentPrice,
+    elasticity,
+    optimalPrice,
+    currentRevenue,
+    optimalRevenue,
+    revenueUpliftPct,
+    priceDemandCurve,
+  };
 }
 
 // ─── Markdown optimization ────────────────────────────────────────────────────
@@ -206,7 +229,7 @@ export function markdownOptimization(
   daysRemaining: number,
   baseDailySalesRate: number,
   elasticity: number,
-  markdownSteps: number[] = [10, 20, 30, 50],
+  markdownSteps: number[] = [10, 20, 30, 50]
 ): MarkdownResult {
   if (originalPrice <= 0) throw new Error('originalPrice must be positive');
   if (inventory <= 0) throw new Error('inventory must be positive');
@@ -236,7 +259,12 @@ export function markdownOptimization(
     totalRevenue += unitsSold * currentPrice;
     remaining = Math.max(0, remaining - unitsSold);
 
-    schedule.push({ dayOfMarkdown, discountPct, price: newPrice, expectedUnits: Math.round(newRate * stepSize) });
+    schedule.push({
+      dayOfMarkdown,
+      discountPct,
+      price: newPrice,
+      expectedUnits: Math.round(newRate * stepSize),
+    });
 
     currentPrice = newPrice;
     currentRate = newRate;
@@ -249,7 +277,14 @@ export function markdownOptimization(
   totalRevenue += finalUnits * currentPrice;
   remaining = Math.max(0, remaining - finalUnits);
 
-  return { originalPrice, inventory, daysRemaining, schedule, expectedRevenue: totalRevenue, expectedUnsold: remaining };
+  return {
+    originalPrice,
+    inventory,
+    daysRemaining,
+    schedule,
+    expectedRevenue: totalRevenue,
+    expectedUnsold: remaining,
+  };
 }
 
 // ─── Customer Lifetime Value ──────────────────────────────────────────────────
@@ -264,7 +299,7 @@ export function customerLifetimeValue(
   purchaseFrequency: number,
   lifespanYears: number,
   discountRate: number,
-  cac?: number,
+  cac?: number
 ): CLVResult {
   if (avgOrderValue <= 0) throw new Error('avgOrderValue must be positive');
   if (purchaseFrequency <= 0) throw new Error('purchaseFrequency must be positive');
@@ -283,7 +318,15 @@ export function customerLifetimeValue(
 
   const clvToCac = cac != null && cac > 0 ? discountedCLV / cac : null;
 
-  return { avgOrderValue, purchaseFrequency, lifespanYears, discountRate, simpleCLV, discountedCLV, clvToCac };
+  return {
+    avgOrderValue,
+    purchaseFrequency,
+    lifespanYears,
+    discountRate,
+    simpleCLV,
+    discountedCLV,
+    clvToCac,
+  };
 }
 
 // ─── Conversion funnel analysis ───────────────────────────────────────────────
@@ -294,25 +337,25 @@ export function customerLifetimeValue(
 export function conversionFunnelAnalysis(
   stages: string[],
   counts: number[],
-  avgOrderValue: number,
+  avgOrderValue: number
 ): FunnelAnalysisResult {
   if (stages.length !== counts.length) throw new Error('stages and counts must have same length');
   if (stages.length < 2) throw new Error('Funnel needs at least 2 stages');
-  if (counts.some(c => c < 0)) throw new Error('counts must be non-negative');
+  if (counts.some((c) => c < 0)) throw new Error('counts must be non-negative');
   if (avgOrderValue <= 0) throw new Error('avgOrderValue must be positive');
 
-  const stepConversions = counts.slice(1).map((c, i) => counts[i] > 0 ? c / counts[i] : 0);
+  const stepConversions = counts.slice(1).map((c, i) => (counts[i] > 0 ? c / counts[i] : 0));
   const overallConversion = counts[0] > 0 ? counts[counts.length - 1] / counts[0] : 0;
   const currentRevenue = counts[counts.length - 1] * avgOrderValue;
 
   // Sensitivity: if step i conversion improves by 10pp, how much extra revenue?
   const sensitivityRevenue = stepConversions.map((conv, i) => {
-    const newConv = Math.min(1, conv + 0.10);
+    const newConv = Math.min(1, conv + 0.1);
     const upliftFactor = newConv / (conv || 1e-9);
     // Downstream: all subsequent stages are multiplied by this factor
     let newFinal = counts[i + 1] * upliftFactor;
     for (let j = i + 2; j < counts.length; j++) {
-      newFinal *= (counts[j - 1] > 0 ? counts[j] / counts[j - 1] : 1);
+      newFinal *= counts[j - 1] > 0 ? counts[j] / counts[j - 1] : 1;
     }
     return (newFinal - counts[counts.length - 1]) * avgOrderValue;
   });
@@ -329,21 +372,23 @@ export function conversionFunnelAnalysis(
  * C: remaining 5% of value
  */
 export function abcClassification(
-  items: Array<{ id: string; annualVolume: number; unitCost: number }>,
+  items: Array<{ id: string; annualVolume: number; unitCost: number }>
 ): ABCClassification {
   if (items.length === 0) throw new Error('No items provided');
 
-  const withValues = items.map(item => ({
-    id: item.id,
-    annualValue: item.annualVolume * item.unitCost,
-  })).sort((a, b) => b.annualValue - a.annualValue);
+  const withValues = items
+    .map((item) => ({
+      id: item.id,
+      annualValue: item.annualVolume * item.unitCost,
+    }))
+    .sort((a, b) => b.annualValue - a.annualValue);
 
   const totalValue = withValues.reduce((a, b) => a + b.annualValue, 0);
   let cumulative = 0;
   const classCounts = { A: 0, B: 0, C: 0 };
-  const classValue  = { A: 0, B: 0, C: 0 };
+  const classValue = { A: 0, B: 0, C: 0 };
 
-  const classified = withValues.map(item => {
+  const classified = withValues.map((item) => {
     cumulative += item.annualValue;
     const cumulativePct = (cumulative / totalValue) * 100;
     const cls: 'A' | 'B' | 'C' = cumulativePct <= 80 ? 'A' : cumulativePct <= 95 ? 'B' : 'C';
@@ -381,7 +426,7 @@ export interface InventoryMetrics {
 export function inventoryMetrics(
   cogs: number,
   avgInventory: number,
-  targetDsi?: number,
+  targetDsi?: number
 ): InventoryMetrics {
   if (cogs <= 0) throw new Error('COGS must be positive');
   if (avgInventory <= 0) throw new Error('avgInventory must be positive');
@@ -390,7 +435,10 @@ export function inventoryMetrics(
   const dsi = 365 / inventoryTurnover;
 
   return {
-    cogs, avgInventory, inventoryTurnover, dsi,
+    cogs,
+    avgInventory,
+    inventoryTurnover,
+    dsi,
     targetDsi,
     withinTarget: targetDsi != null ? dsi <= targetDsi : undefined,
   };
@@ -411,7 +459,7 @@ export interface RetailAnalysisResult {
 
 export function buildRetailReceipt(
   result: RetailAnalysisResult,
-  options?: RetailReceiptOptions,
+  options?: RetailReceiptOptions
 ): DomainSimulationReceipt {
   const violations: Array<{ criterion: string; message: string }> = [];
 
@@ -440,7 +488,11 @@ export function buildRetailReceipt(
       clv: result.clv?.discountedCLV ?? null,
       overallConversion: result.funnel?.overallConversion ?? null,
     },
-    cael: { version: 'cael.v1', event: 'retail_ecommerce.retail_analysis', solverType: 'retail-ecommerce.analytics' },
+    cael: {
+      version: 'cael.v1',
+      event: 'retail_ecommerce.retail_analysis',
+      solverType: 'retail-ecommerce.analytics',
+    },
     acceptance: { accepted: violations.length === 0, violations },
   });
 }

package/src/runtime.ts

@@ -63,7 +63,7 @@ export interface RuntimeTraitHandler {
     node: unknown,
     config: EoqTraitConfig,
     context: TraitDispatchContext,
-    delta: number,
+    delta: number
   ) => void;
 }
 
@@ -78,7 +78,7 @@ interface EoqNode {
 function solveOntoNode(
   node: unknown,
   config: EoqTraitConfig | undefined,
-  context: TraitDispatchContext,
+  context: TraitDispatchContext
 ): void {
   const carrier = node as EoqNode;
   const nodeId = carrier.id ?? carrier.name ?? 'unknown';
@@ -106,7 +106,7 @@ function solveOntoNode(
       orderingCost,
       holdingCostPerUnit,
       config?.leadTimeDays ?? 0,
-      config?.workingDaysPerYear ?? 250,
+      config?.workingDaysPerYear ?? 250
     );
     carrier.__eoqResult = result;
     carrier.properties = {

package/src/traits/CartTrait.ts

@@ -1,39 +1,72 @@
 /** @cart Trait — Shopping cart management. @trait cart */
 import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
 
-export interface CartItem { productId: string; quantity: number; price: number; variant?: string; name: string; }
-export interface CartConfig { currency: string; items: CartItem[]; maxItems: number; taxRate: number; }
-export interface CartState { items: CartItem[]; subtotal: number; tax: number; total: number; itemCount: number; }
+export interface CartItem {
+  productId: string;
+  quantity: number;
+  price: number;
+  variant?: string;
+  name: string;
+}
+export interface CartConfig {
+  currency: string;
+  items: CartItem[];
+  maxItems: number;
+  taxRate: number;
+}
+export interface CartState {
+  items: CartItem[];
+  subtotal: number;
+  tax: number;
+  total: number;
+  itemCount: number;
+}
 
 const defaultConfig: CartConfig = { currency: 'USD', items: [], maxItems: 99, taxRate: 0 };
 
-function computeTotals(items: CartItem[], taxRate: number): Pick<CartState, 'subtotal' | 'tax' | 'total' | 'itemCount'> {
+function computeTotals(
+  items: CartItem[],
+  taxRate: number
+): Pick<CartState, 'subtotal' | 'tax' | 'total' | 'itemCount'> {
   const subtotal = items.reduce((sum, i) => sum + i.price * i.quantity, 0);
   const tax = subtotal * taxRate;
-  return { subtotal, tax, total: subtotal + tax, itemCount: items.reduce((sum, i) => sum + i.quantity, 0) };
+  return {
+    subtotal,
+    tax,
+    total: subtotal + tax,
+    itemCount: items.reduce((sum, i) => sum + i.quantity, 0),
+  };
 }
 
 export function createCartHandler(): TraitHandler<CartConfig> {
   return {
-    name: 'cart', defaultConfig,
+    name: 'cart',
+    defaultConfig,
     onAttach(node: HSPlusNode, config: CartConfig, ctx: TraitContext) {
       const totals = computeTotals(config.items, config.taxRate);
       node.__cartState = { items: [...config.items], ...totals };
       ctx.emit?.('cart:created', { itemCount: totals.itemCount });
     },
-    onDetach(node: HSPlusNode, _c: CartConfig, ctx: TraitContext) { delete node.__cartState; ctx.emit?.('cart:cleared'); },
+    onDetach(node: HSPlusNode, _c: CartConfig, ctx: TraitContext) {
+      delete node.__cartState;
+      ctx.emit?.('cart:cleared');
+    },
     onUpdate() {},
     onEvent(node: HSPlusNode, config: CartConfig, ctx: TraitContext, event: TraitEvent) {
-      const s = node.__cartState as CartState | undefined; if (!s) return;
+      const s = node.__cartState as CartState | undefined;
+      if (!s) return;
       if (event.type === 'cart:add_item') {
         const item = event.payload as unknown as CartItem;
-        const existing = s.items.find(i => i.productId === item.productId && i.variant === item.variant);
-        if (existing) existing.quantity += item.quantity; else s.items.push({ ...item });
+        const existing = s.items.find(
+          (i) => i.productId === item.productId && i.variant === item.variant
+        );
+        if (existing) existing.quantity += item.quantity;
+        else s.items.push({ ...item });
         Object.assign(s, computeTotals(s.items, config.taxRate));
         ctx.emit?.('cart:updated', { itemCount: s.itemCount, total: s.total });
       }
       if (event.type === 'cart:remove_item') {
-        s.items = s.items.filter(i => i.productId !== (event.payload?.productId as string));
+        s.items = s.items.filter((i) => i.productId !== (event.payload?.productId as string));
         Object.assign(s, computeTotals(s.items, config.taxRate));
         ctx.emit?.('cart:updated', { itemCount: s.itemCount, total: s.total });
       }

package/src/traits/CheckoutTrait.ts

@@ -2,28 +2,83 @@
 import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
 
 export type CheckoutStep = 'shipping' | 'payment' | 'review' | 'confirm' | 'complete';
-export type PaymentMethod = 'credit_card' | 'debit_card' | 'paypal' | 'crypto' | 'bank_transfer' | 'apple_pay';
-export interface Address { line1: string; line2?: string; city: string; state: string; postalCode: string; country: string; }
-export interface CheckoutConfig { step: CheckoutStep; paymentMethod: PaymentMethod; shippingAddress: Address | null; billingAddress: Address | null; orderTotal: number; tax: number; }
-export interface CheckoutState { currentStep: CheckoutStep; isProcessing: boolean; orderId: string | null; error: string | null; }
+export type PaymentMethod =
+  | 'credit_card'
+  | 'debit_card'
+  | 'paypal'
+  | 'crypto'
+  | 'bank_transfer'
+  | 'apple_pay';
+export interface Address {
+  line1: string;
+  line2?: string;
+  city: string;
+  state: string;
+  postalCode: string;
+  country: string;
+}
+export interface CheckoutConfig {
+  step: CheckoutStep;
+  paymentMethod: PaymentMethod;
+  shippingAddress: Address | null;
+  billingAddress: Address | null;
+  orderTotal: number;
+  tax: number;
+}
+export interface CheckoutState {
+  currentStep: CheckoutStep;
+  isProcessing: boolean;
+  orderId: string | null;
+  error: string | null;
+}
 
-const defaultConfig: CheckoutConfig = { step: 'shipping', paymentMethod: 'credit_card', shippingAddress: null, billingAddress: null, orderTotal: 0, tax: 0 };
+const defaultConfig: CheckoutConfig = {
+  step: 'shipping',
+  paymentMethod: 'credit_card',
+  shippingAddress: null,
+  billingAddress: null,
+  orderTotal: 0,
+  tax: 0,
+};
 
 export function createCheckoutHandler(): TraitHandler<CheckoutConfig> {
   return {
-    name: 'checkout', defaultConfig,
-    onAttach(node: HSPlusNode, config: CheckoutConfig, ctx: TraitContext) { node.__checkoutState = { currentStep: config.step, isProcessing: false, orderId: null, error: null }; ctx.emit?.('checkout:started'); },
-    onDetach(node: HSPlusNode, _c: CheckoutConfig, ctx: TraitContext) { delete node.__checkoutState; ctx.emit?.('checkout:abandoned'); },
+    name: 'checkout',
+    defaultConfig,
+    onAttach(node: HSPlusNode, config: CheckoutConfig, ctx: TraitContext) {
+      node.__checkoutState = {
+        currentStep: config.step,
+        isProcessing: false,
+        orderId: null,
+        error: null,
+      };
+      ctx.emit?.('checkout:started');
+    },
+    onDetach(node: HSPlusNode, _c: CheckoutConfig, ctx: TraitContext) {
+      delete node.__checkoutState;
+      ctx.emit?.('checkout:abandoned');
+    },
     onUpdate() {},
     onEvent(node: HSPlusNode, _c: CheckoutConfig, ctx: TraitContext, event: TraitEvent) {
-      const s = node.__checkoutState as CheckoutState | undefined; if (!s) return;
+      const s = node.__checkoutState as CheckoutState | undefined;
+      if (!s) return;
       if (event.type === 'checkout:next_step') {
         const steps: CheckoutStep[] = ['shipping', 'payment', 'review', 'confirm', 'complete'];
         const idx = steps.indexOf(s.currentStep);
-        if (idx < steps.length - 1) { s.currentStep = steps[idx + 1]; ctx.emit?.('checkout:step_changed', { step: s.currentStep }); }
+        if (idx < steps.length - 1) {
+          s.currentStep = steps[idx + 1];
+          ctx.emit?.('checkout:step_changed', { step: s.currentStep });
+        }
+      }
+      if (event.type === 'checkout:process_payment') {
+        s.isProcessing = true;
+        ctx.emit?.('checkout:processing');
+      }
+      if (event.type === 'checkout:complete') {
+        s.currentStep = 'complete';
+        s.orderId = event.payload?.orderId as string;
+        ctx.emit?.('checkout:completed', { orderId: s.orderId });
       }
-      if (event.type === 'checkout:process_payment') { s.isProcessing = true; ctx.emit?.('checkout:processing'); }
-      if (event.type === 'checkout:complete') { s.currentStep = 'complete'; s.orderId = event.payload?.orderId as string; ctx.emit?.('checkout:completed', { orderId: s.orderId }); }
     },
   };
 }

package/src/traits/ProductCatalogTrait.ts

@@ -1,26 +1,60 @@
 /** @product_catalog Trait — Product catalog with search and filtering. @trait product_catalog */
 import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
 
-export interface Product { id: string; name: string; price: number; category: string; brand?: string; inStock: boolean; imageUrl?: string; }
-export interface ProductCatalogConfig { products: Product[]; categories: string[]; sortBy: 'price_asc' | 'price_desc' | 'name' | 'newest'; pageSize: number; }
+export interface Product {
+  id: string;
+  name: string;
+  price: number;
+  category: string;
+  brand?: string;
+  inStock: boolean;
+  imageUrl?: string;
+}
+export interface ProductCatalogConfig {
+  products: Product[];
+  categories: string[];
+  sortBy: 'price_asc' | 'price_desc' | 'name' | 'newest';
+  pageSize: number;
+}
 
-const defaultConfig: ProductCatalogConfig = { products: [], categories: [], sortBy: 'name', pageSize: 20 };
+const defaultConfig: ProductCatalogConfig = {
+  products: [],
+  categories: [],
+  sortBy: 'name',
+  pageSize: 20,
+};
 
 export function createProductCatalogHandler(): TraitHandler<ProductCatalogConfig> {
   return {
-    name: 'product_catalog', defaultConfig,
-    onAttach(node: HSPlusNode, config: ProductCatalogConfig, ctx: TraitContext) { node.__catalogState = { currentPage: 0, filteredCount: config.products.length, activeFilters: {} }; ctx.emit?.('catalog:loaded', { productCount: config.products.length }); },
-    onDetach(node: HSPlusNode, _c: ProductCatalogConfig, ctx: TraitContext) { delete node.__catalogState; ctx.emit?.('catalog:unloaded'); },
+    name: 'product_catalog',
+    defaultConfig,
+    onAttach(node: HSPlusNode, config: ProductCatalogConfig, ctx: TraitContext) {
+      node.__catalogState = {
+        currentPage: 0,
+        filteredCount: config.products.length,
+        activeFilters: {},
+      };
+      ctx.emit?.('catalog:loaded', { productCount: config.products.length });
+    },
+    onDetach(node: HSPlusNode, _c: ProductCatalogConfig, ctx: TraitContext) {
+      delete node.__catalogState;
+      ctx.emit?.('catalog:unloaded');
+    },
     onUpdate() {},
     onEvent(node: HSPlusNode, config: ProductCatalogConfig, ctx: TraitContext, event: TraitEvent) {
       if (event.type === 'catalog:search') {
-        const query = (event.payload?.query as string || '').toLowerCase();
-        const results = config.products.filter(p => p.name.toLowerCase().includes(query));
-        ctx.emit?.('catalog:results', { count: results.length, products: results.slice(0, config.pageSize) });
+        const query = ((event.payload?.query as string) || '').toLowerCase();
+        const results = config.products.filter((p) => p.name.toLowerCase().includes(query));
+        ctx.emit?.('catalog:results', {
+          count: results.length,
+          products: results.slice(0, config.pageSize),
+        });
       }
       if (event.type === 'catalog:filter') {
         const category = event.payload?.category as string;
-        const results = category ? config.products.filter(p => p.category === category) : config.products;
+        const results = category
+          ? config.products.filter((p) => p.category === category)
+          : config.products;
         ctx.emit?.('catalog:filtered', { count: results.length, category });
       }
     },

package/src/traits/ReturnTrait.ts

@@ -1,23 +1,61 @@
 /** @return Trait — Return and refund management. @trait return */
 import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
 
-export type ReturnStatus = 'requested' | 'approved' | 'shipped' | 'received' | 'refunded' | 'denied';
-export interface ReturnConfig { orderId: string; reason: string; status: ReturnStatus; refundAmount: number; returnWindowDays: number; }
+export type ReturnStatus =
+  | 'requested'
+  | 'approved'
+  | 'shipped'
+  | 'received'
+  | 'refunded'
+  | 'denied';
+export interface ReturnConfig {
+  orderId: string;
+  reason: string;
+  status: ReturnStatus;
+  refundAmount: number;
+  returnWindowDays: number;
+}
 
-const defaultConfig: ReturnConfig = { orderId: '', reason: '', status: 'requested', refundAmount: 0, returnWindowDays: 30 };
+const defaultConfig: ReturnConfig = {
+  orderId: '',
+  reason: '',
+  status: 'requested',
+  refundAmount: 0,
+  returnWindowDays: 30,
+};
 
 export function createReturnHandler(): TraitHandler<ReturnConfig> {
   return {
-    name: 'return', defaultConfig,
-    onAttach(node: HSPlusNode, config: ReturnConfig, ctx: TraitContext) { node.__returnState = { ...config, requestedAt: Date.now() }; ctx.emit?.('return:created', { orderId: config.orderId }); },
-    onDetach(node: HSPlusNode, _c: ReturnConfig, ctx: TraitContext) { delete node.__returnState; ctx.emit?.('return:cancelled'); },
+    name: 'return',
+    defaultConfig,
+    onAttach(node: HSPlusNode, config: ReturnConfig, ctx: TraitContext) {
+      node.__returnState = { ...config, requestedAt: Date.now() };
+      ctx.emit?.('return:created', { orderId: config.orderId });
+    },
+    onDetach(node: HSPlusNode, _c: ReturnConfig, ctx: TraitContext) {
+      delete node.__returnState;
+      ctx.emit?.('return:cancelled');
+    },
     onUpdate() {},
     onEvent(node: HSPlusNode, _c: ReturnConfig, ctx: TraitContext, event: TraitEvent) {
-      const s = node.__returnState as Record<string, unknown> | undefined; if (!s) return;
-      if (event.type === 'return:approve') { s.status = 'approved'; ctx.emit?.('return:approved'); }
-      if (event.type === 'return:ship') { s.status = 'shipped'; ctx.emit?.('return:shipped'); }
-      if (event.type === 'return:receive') { s.status = 'received'; ctx.emit?.('return:received'); }
-      if (event.type === 'return:refund') { s.status = 'refunded'; ctx.emit?.('return:refunded', { amount: s.refundAmount }); }
+      const s = node.__returnState as Record<string, unknown> | undefined;
+      if (!s) return;
+      if (event.type === 'return:approve') {
+        s.status = 'approved';
+        ctx.emit?.('return:approved');
+      }
+      if (event.type === 'return:ship') {
+        s.status = 'shipped';
+        ctx.emit?.('return:shipped');
+      }
+      if (event.type === 'return:receive') {
+        s.status = 'received';
+        ctx.emit?.('return:received');
+      }
+      if (event.type === 'return:refund') {
+        s.status = 'refunded';
+        ctx.emit?.('return:refunded', { amount: s.refundAmount });
+      }
     },
   };
 }

package/src/traits/ShippingRateTrait.ts

@@ -2,18 +2,49 @@
 import type { TraitHandler, HSPlusNode, TraitContext, TraitEvent } from './types';
 
 export type ShippingMethod = 'standard' | 'express' | 'overnight' | 'freight' | 'pickup';
-export interface ShippingRateConfig { carrier: string; method: ShippingMethod; weightKg: number; dimensions: { lengthCm: number; widthCm: number; heightCm: number; }; origin: string; destination: string; rate: number; estimatedDays: number; }
+export interface ShippingRateConfig {
+  carrier: string;
+  method: ShippingMethod;
+  weightKg: number;
+  dimensions: { lengthCm: number; widthCm: number; heightCm: number };
+  origin: string;
+  destination: string;
+  rate: number;
+  estimatedDays: number;
+}
 
-const defaultConfig: ShippingRateConfig = { carrier: '', method: 'standard', weightKg: 0, dimensions: { lengthCm: 0, widthCm: 0, heightCm: 0 }, origin: '', destination: '', rate: 0, estimatedDays: 5 };
+const defaultConfig: ShippingRateConfig = {
+  carrier: '',
+  method: 'standard',
+  weightKg: 0,
+  dimensions: { lengthCm: 0, widthCm: 0, heightCm: 0 },
+  origin: '',
+  destination: '',
+  rate: 0,
+  estimatedDays: 5,
+};
 
 export function createShippingRateHandler(): TraitHandler<ShippingRateConfig> {
   return {
-    name: 'shipping_rate', defaultConfig,
-    onAttach(node: HSPlusNode, config: ShippingRateConfig, ctx: TraitContext) { node.__shippingState = { calculatedRate: config.rate, carrier: config.carrier }; ctx.emit?.('shipping:rate_set', { rate: config.rate, method: config.method }); },
-    onDetach(node: HSPlusNode, _c: ShippingRateConfig, ctx: TraitContext) { delete node.__shippingState; ctx.emit?.('shipping:cleared'); },
+    name: 'shipping_rate',
+    defaultConfig,
+    onAttach(node: HSPlusNode, config: ShippingRateConfig, ctx: TraitContext) {
+      node.__shippingState = { calculatedRate: config.rate, carrier: config.carrier };
+      ctx.emit?.('shipping:rate_set', { rate: config.rate, method: config.method });
+    },
+    onDetach(node: HSPlusNode, _c: ShippingRateConfig, ctx: TraitContext) {
+      delete node.__shippingState;
+      ctx.emit?.('shipping:cleared');
+    },
     onUpdate() {},
     onEvent(_n: HSPlusNode, config: ShippingRateConfig, ctx: TraitContext, event: TraitEvent) {
-      if (event.type === 'shipping:calculate') { ctx.emit?.('shipping:calculated', { rate: config.rate, estimatedDays: config.estimatedDays, carrier: config.carrier }); }
+      if (event.type === 'shipping:calculate') {
+        ctx.emit?.('shipping:calculated', {
+          rate: config.rate,
+          estimatedDays: config.estimatedDays,
+          carrier: config.carrier,
+        });
+      }
     },
   };
 }

package/src/traits/types.ts

@@ -1,4 +1,25 @@
-export interface HSPlusNode { id?: string; properties?: Record<string, unknown>; [key: string]: unknown; }
-export interface TraitContext { emit?: (event: string, payload?: unknown) => void; getState?: () => Record<string, unknown>; setState?: (updates: Record<string, unknown>) => void; [key: string]: unknown; }
-export interface TraitEvent { type: string; source?: string; payload?: Record<string, unknown>; [key: string]: unknown; }
-export interface TraitHandler<TConfig = unknown> { name: string; defaultConfig: TConfig; onAttach(node: HSPlusNode, config: TConfig, ctx: TraitContext): void; onDetach(node: HSPlusNode, config: TConfig, ctx: TraitContext): void; onUpdate(node: HSPlusNode, config: TConfig, ctx: TraitContext, delta: number): void; onEvent(node: HSPlusNode, config: TConfig, ctx: TraitContext, event: TraitEvent): void; }
+export interface HSPlusNode {
+  id?: string;
+  properties?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+export interface TraitContext {
+  emit?: (event: string, payload?: unknown) => void;
+  getState?: () => Record<string, unknown>;
+  setState?: (updates: Record<string, unknown>) => void;
+  [key: string]: unknown;
+}
+export interface TraitEvent {
+  type: string;
+  source?: string;
+  payload?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+export interface TraitHandler<TConfig = unknown> {
+  name: string;
+  defaultConfig: TConfig;
+  onAttach(node: HSPlusNode, config: TConfig, ctx: TraitContext): void;
+  onDetach(node: HSPlusNode, config: TConfig, ctx: TraitContext): void;
+  onUpdate(node: HSPlusNode, config: TConfig, ctx: TraitContext, delta: number): void;
+  onEvent(node: HSPlusNode, config: TConfig, ctx: TraitContext, event: TraitEvent): void;
+}

package/tsconfig.json

@@ -1 +1,10 @@
-{ "extends": "../../../tsconfig.json", "compilerOptions": { "outDir": "dist", "rootDir": "src", "declaration": true, "declarationMap": true }, "include": ["src"] }
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": true
+  },
+  "include": ["src"]
+}

package/vitest.config.ts

@@ -1,13 +1,6 @@
 import { defineConfig } from 'vitest/config';
-import { resolve } from 'path';
 
 export default defineConfig({
-  resolve: {
-    alias: {
-      '@holoscript/engine': resolve(__dirname, '../../engine/src'),
-      '@holoscript/core': resolve(__dirname, '../../core/src'),
-    },
-  },
   test: {
     globals: true,
     environment: 'node',

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025-2026 HoloScript Contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.