import { z } from "zod";

export const PositioningVariantSchema = z.object({
  id: z.string().uuid(),
  version: z.string().regex(/^\d+\.\d+\.\d+$/),
  audience: z.enum(["enterprise", "developer", "startup", "default"]),
  context: z.object({
    trafficSource: z.string().optional(),
    deviceType: z.enum(["mobile", "desktop", "tablet"]).optional(),
    userTier: z.enum(["free", "pro", "enterprise"]).optional(),
    region: z.string().optional(),
  }).optional(),
  content: z.object({
    headline: z.string().min(1).max(120),
    subheadline: z.string().min(1).max(240),
    cta: z.string().min(1).max(60),
    metadata: z.record(z.string()).optional(),
  }),
  priority: z.number().int().min(0).max(100),
  enabled: z.boolean().default(true),
});

export type PositioningVariant = z.infer<typeof PositioningVariantSchema>;

export interface RequestContext {
  trafficSource?: string;
  deviceType?: "mobile" | "desktop" | "tablet";
  userTier?: "free" | "pro" | "enterprise";
  region?: string;
  experimentBucket?: string;
}

export class ContextResolver {
  resolve(req: Request): RequestContext {
    const ua = req.headers.get("user-agent") || "";
    const deviceType = this.detectDevice(ua);
    const trafficSource = this.extractSource(req.url);
    const userTier = this.extractTier(req.headers);
    const region = req.headers.get("cf-ipcountry") || "US";
    const experimentBucket = req.headers.get("x-experiment-bucket") || "control";

    return { trafficSource, deviceType, userTier, region, experimentBucket };
  }

  private detectDevice(ua: string): "mobile" | "desktop" | "tablet" {
    if (/mobile|android|iphone/i.test(ua)) return "mobile";
    if (/tablet|ipad/i.test(ua)) return "tablet";
    return "desktop";
  }

  private extractSource(url: string): string | undefined {
    const params = new URL(url).searchParams;
    return params.get("utm_source") || params.get("ref");
  }

  private extractTier(headers: Headers): "free" | "pro" | "enterprise" | undefined {
    const tier = headers.get("x-user-tier");
    if (tier === "pro" || tier === "enterprise") return tier;
    return "free";
  }
}

export class PositioningEngine {
  private variants: PositioningVariant[] = [];
  private cache = new Map<string, PositioningVariant>();

  constructor(variants: PositioningVariant[]) {
    this.variants = variants.sort((a, b) => b.priority - a.priority);
  }

  evaluate(context: RequestContext): PositioningVariant {
    const ca

cheKey = this.hashContext(context); if (this.cache.has(cacheKey)) return this.cache.get(cacheKey)!;

const matched = this.variants.find((v) => this.matchesContext(v, context));
const result = matched || this.getDefaultVariant();

this.cache.set(cacheKey, result);
return result;

}

private matchesContext(variant: PositioningVariant, ctx: RequestContext): boolean { if (!variant.enabled) return false; if (variant.audience !== "default" && variant.audience !== this.inferAudience(ctx)) { return false; } if (!variant.context) return true;

const vCtx = variant.context;
const checks: boolean[] = [];

if (vCtx.trafficSource) checks.push(ctx.trafficSource === vCtx.trafficSource);
if (vCtx.deviceType) checks.push(ctx.deviceType === vCtx.deviceType);
if (vCtx.userTier) checks.push(ctx.userTier === vCtx.userTier);
if (vCtx.region) checks.push(ctx.region === vCtx.region);

return checks.every(Boolean);

}

private inferAudience(ctx: RequestContext): string { if (ctx.userTier === "enterprise") return "enterprise"; if (ctx.trafficSource?.includes("github") || ctx.trafficSource?.includes("docs")) return "developer"; if (ctx.userTier === "free") return "startup"; return "default"; }

private getDefaultVariant(): PositioningVariant { return this.variants.find((v) => v.audience === "default") || this.variants[0]; }

private hashContext(ctx: RequestContext): string { return JSON.stringify(ctx); } }

### Step 4: Delivery Integration

The framework integrates with frontend and backend layers via providers, hooks, or middleware. React example:

```typescript
import { createContext, useContext, useMemo } from "react";
import { PositioningEngine, PositioningVariant } from "./engine";

const PositioningContext = createContext<PositioningVariant | null>(null);

export function PositioningProvider({
  children,
  variants,
  context,
}: {
  children: React.ReactNode;
  variants: PositioningVariant[];
  context: RequestContext;
}) {
  const engine = useMemo(() => new PositioningEngine(variants), [variants]);
  const positioning = useMemo(() => engine.evaluate(context), [engine, context]);

  return (
    <PositioningContext.Provider value={positioning}>
      {children}
    </PositioningContext.Provider>
  );
}

export function usePositioning() {
  const ctx = useContext(PositioningContext);
  if (!ctx) throw new Error("usePositioning must be used within PositioningProvider");
  return ctx;
}

Architecture Decisions & Rationale

• Stateless Evaluation: The engine is pure function-based. No external dependencies during evaluation. This enables edge deployment, serverless scaling, and deterministic testing.
• Priority-Based Resolution: Variants are sorted by priority. First match wins. This prevents ambiguous routing and simplifies debugging.
• Context Hash Caching: Identical context payloads return cached results. Reduces CPU overhead in high-traffic routes. Cache TTL is managed by the host environment (Vercel Edge, Cloudflare Workers, or Node process).
• Experiment Routing: The experimentBucket field in context allows integration with existing A/B testing infrastructure. Positioning variants can be gated by flag state without code changes.
• Schema Validation: Zod enforces contract stability. Invalid payloads fail at build or CI time, not runtime.

Pitfall Guide

1. Overcomplicating Rule Syntax

   • Mistake: Writing nested boolean logic, regex patterns, or dynamic expressions inside positioning rules.
   • Impact: Evaluation latency spikes, debugging becomes impossible, and non-engineers cannot maintain rules.
   • Fix: Keep rules declarative. Use exact matches, enums, and priority ordering. Delegate complex logic to experiment flags or backend services.

2. Ignoring Evaluation Latency

   • Mistake: Running heavy context resolution or external API calls during positioning evaluation.
   • Impact: TTFB increases, core web vitals degrade, and conversion drops.
   • Fix: Resolve context at the edge or middleware layer. Pass pre-resolved context to the positioning engine. Cache aggressively.

3. Hardcoding Fallbacks Without Audit Trails

   • Mistake: Defaulting to a hardcoded variant when no match occurs, with no logging.
   • Impact: Silent misalignment between intended and delivered messaging. Wasted experiment budget.
   • Fix: Always log fallback events with context payload, variant ID, and timestamp. Route fallbacks to a monitored analytics stream.

4. Mixing Positioning Logic with Business Rules

   • Mistake: Embedding pricing logic, feature access checks, or authentication state inside positioning rules.
   • Impact: Tight coupling, deployment risk, and inability to isolate positioning experiments.
   • Fix: Positioning handles messaging only. Business rules live in feature flags, policy engines, or backend services. Pass their output as context fields.

5. Neglecting Version Control & Rollback

   • Mistake: Updating positioning variants directly in production without schema versioning or diff tracking.
   • Impact: Regression bugs, untracked changes, and inability to revert failed campaigns.
   • Fix: Store variants in version-controlled files or a managed registry. Require PR reviews for changes. Implement semantic versioning and rollback endpoints.

6. Skipping Cross-Environment Parity Testing

   • Mistake: Testing positioning only in staging without replicating production traffic patterns, headers, or experiment buckets.
   • Impact: Rules behave differently in production due to missing context fields or flag states.
   • Fix: Use contract tests with production-like payloads. Mock experiment buckets, regional headers, and device signals. Validate parity before rollout.

7. Under-Instrumenting for Analytics

   • Mistake: Delivering positioned content without tracking which variant served, to whom, and how it performed.
   • Impact: No feedback loop. Cannot measure lift, optimize rules, or justify engineering investment.
   • Fix: Emit positioning decisions to analytics pipelines. Include variant ID, context hash, experiment bucket, and conversion events. Correlate in BI tools.

Production Bundle

Action Checklist

• Define positioning schema with Zod or equivalent strict validator
• Build context resolver that extracts traffic, device, tier, and region signals
• Implement priority-based evaluation engine with fallback chain
• Integrate engine into delivery layer via provider/hook/middleware
• Add observability: log decisions, fallbacks, and experiment routing
• Version control variant payloads and require CI validation
• Instrument analytics pipeline with variant ID and context correlation
• Run parity tests across staging and production-like environments

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Early-stage startup	Single-file YAML variants + edge middleware	Low overhead, fast iteration, minimal infra	$0–$50/mo (hosting)
Growth-stage SaaS	Schema-validated registry + React provider + analytics integration	Enables A/B testing, localization, and cross-team ownership	$200–$800/mo (tooling + engineering)
Enterprise multi-tenant	Centralized positioning service + feature flag integration + audit logging	Compliance, rollback safety, tenant isolation	$1.5k–$3k/mo (infra + support)
Compliance-heavy (fintech/health)	Immutable variant snapshots + manual approval workflow + PII-safe context hashing	Auditability, regulatory alignment, risk mitigation	$2k–$5k/mo (process + tooling)

Configuration Template

# positioning.yaml
version: "1.2.0"
variants:
  - id: "v1-enterprise-landing"
    version: "1.2.0"
    audience: "enterprise"
    context:
      trafficSource: "partner"
      userTier: "enterprise"
    content:
      headline: "Scale securely with dedicated infrastructure"
      subheadline: "SOC 2 compliant, SSO-enabled, and backed by 24/7 engineering support."
      cta: "Request Enterprise Demo"
      metadata:
        experiment: "ent-landing-v2"
    priority: 90
    enabled: true

  - id: "v1-developer-docs"
    version: "1.2.0"
    audience: "developer"
    context:
      trafficSource: "github"
      deviceType: "desktop"
    content:
      headline: "Ship faster with type-safe SDKs"
      subheadline: "Full TypeScript support, zero-config auth, and automated CI templates."
      cta: "View Documentation"
      metadata:
        experiment: "dev-landing-v1"
    priority: 80
    enabled: true

  - id: "v1-default"
    version: "1.2.0"
    audience: "default"
    content:
      headline: "Build products that scale"
      subheadline: "From prototype to production in days, not months."
      cta: "Start Free Trial"
      metadata: {}
    priority: 0
    enabled: true

Quick Start Guide

1. Install dependencies: npm install zod react (or equivalent for your stack)
2. Create positioning.yaml using the template above. Validate with zod or a YAML linter.
3. Bootstrap the engine: Import variants, instantiate PositioningEngine, and wrap your app with PositioningProvider.
4. Consume in components: Call usePositioning() to access headline, subheadline, cta, and metadata. Render dynamically.
5. Verify & instrument: Check network headers for x-positioning-variant-id, confirm fallback logging, and route decisions to your analytics pipeline.

Deploy. Iterate. Measure. Positioning is no longer a static deliverable. It is a versioned, testable system that aligns product, engineering, and growth around measurable outcomes.