okengine 0.1.4

package/src/console/ui/channels/a11y.test.tsx

@@ -0,0 +1,96 @@
+/**
+ * Accessibility gate — axe reports zero violations at WCAG 2.2 AA
+ * (console §7.5 · §9.9).
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import axe from "axe-core";
+import { Window } from "happy-dom";
+import { createRoot, type Root } from "react-dom/client";
+import { act } from "react";
+import { ChannelsA11yView } from "./ChannelsA11yView.tsx";
+
+describe("Channels panel accessibility", () => {
+  let window: Window;
+  let root: Root;
+  let container: HTMLElement;
+
+  beforeEach(() => {
+    (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT =
+      true;
+    window = new Window({ url: "http://console.test/channels" });
+    Object.defineProperty(globalThis, "window", {
+      value: window,
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, "document", {
+      value: window.document,
+      configurable: true,
+    });
+    Object.defineProperty(globalThis, "HTMLElement", {
+      value: window.HTMLElement,
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, "Node", {
+      value: window.Node,
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, "navigator", {
+      value: window.navigator,
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, "getComputedStyle", {
+      value: window.getComputedStyle.bind(window),
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(globalThis, "requestAnimationFrame", {
+      value: (cb: FrameRequestCallback) => window.setTimeout(cb, 0),
+      configurable: true,
+      writable: true,
+    });
+
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => {
+      root.unmount();
+    });
+    container.remove();
+    window.close();
+  });
+
+  test("axe reports zero violations at WCAG 2.2 AA", async () => {
+    await act(async () => {
+      root.render(<ChannelsA11yView openTemplate="otp-code" />);
+    });
+
+    await new Promise((r) => setTimeout(r, 10));
+
+    const results = await axe.run(container, {
+      runOnly: {
+        type: "tag",
+        values: ["wcag2a", "wcag2aa", "wcag22aa"],
+      },
+    });
+
+    if (results.violations.length > 0) {
+      const summary = results.violations
+        .map(
+          (v) =>
+            `${v.id}: ${v.help} (${v.nodes.length} nodes) — ${v.nodes.map((n) => n.html).join("; ")}`,
+        )
+        .join("\n");
+      console.error(summary);
+    }
+
+    expect(results.violations).toEqual([]);
+  });
+});

package/src/console/ui/channels/confirmation.test.ts

@@ -0,0 +1,37 @@
+/**
+ * Send-test confirmation — typed SEND in production.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  sendTestConfirmation,
+  validateTypedConfirm,
+} from "./confirmation.ts";
+
+describe("sendTestConfirmation", () => {
+  test("production requires typed SEND + reason", () => {
+    expect(sendTestConfirmation({ production: true })).toEqual({
+      kind: "typed",
+      phrase: "SEND",
+      requireReason: true,
+    });
+    expect(
+      validateTypedConfirm({
+        typed: "SEND",
+        reason: "verify otp",
+        phrase: "SEND",
+      }),
+    ).toBeNull();
+    expect(
+      validateTypedConfirm({
+        typed: "send",
+        reason: "x",
+        phrase: "SEND",
+      }),
+    ).not.toBeNull();
+  });
+
+  test("non-production uses undo window", () => {
+    expect(sendTestConfirmation({ production: false }).kind).toBe("undo");
+  });
+});

package/src/console/ui/channels/confirmation.ts

@@ -0,0 +1,27 @@
+/**
+ * Reversibility-governed confirmation for Channel send-test (console §10.5 · §9.9).
+ *
+ * Send test is a real external send — typed confirm in production, never stubbed.
+ */
+
+import {
+  UNDO_WINDOW_MS,
+  type ConfirmationPattern,
+} from "../flows/confirmation.ts";
+
+export { UNDO_WINDOW_MS, validateTypedConfirm } from "../flows/confirmation.ts";
+export type { ConfirmationPattern } from "../flows/confirmation.ts";
+
+/**
+ * Confirmation for a real send-test.
+ *
+ * @param options - Environment
+ */
+export function sendTestConfirmation(
+  options: { readonly production: boolean } = { production: true },
+): ConfirmationPattern {
+  if (options.production) {
+    return { kind: "typed", phrase: "SEND", requireReason: true };
+  }
+  return { kind: "undo", windowMs: UNDO_WINDOW_MS };
+}

package/src/console/ui/channels/fallback.test.ts

@@ -0,0 +1,15 @@
+/**
+ * Fallback weekly cost copy.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { formatFallbackLine } from "./fallback.ts";
+import { CHANNELS_LIST_FIXTURE } from "./fixture.ts";
+
+describe("formatFallbackLine", () => {
+  test("includes chain and weekly bill", () => {
+    const line = formatFallbackLine(CHANNELS_LIST_FIXTURE.fallback);
+    expect(line).toContain("whatsapp failed → sms succeeded");
+    expect(line).toContain("$38 / week above whatsapp-only");
+  });
+});

package/src/console/ui/channels/fallback.ts

@@ -0,0 +1,20 @@
+/**
+ * Fallback chain + weekly cost copy (console §9.9 · §9.12).
+ */
+
+import type { FallbackMetric } from "./types.ts";
+
+/**
+ * Format the financial fallback line for the panel.
+ *
+ * @param metric - Fallback projection
+ */
+export function formatFallbackLine(metric: FallbackMetric): string {
+  if (metric.totalCount === 0) {
+    return "No sends in the last week";
+  }
+  if (metric.chainExample) {
+    return `${metric.chainExample} · ${metric.summary}`;
+  }
+  return metric.summary;
+}

package/src/console/ui/channels/findings.ts

@@ -0,0 +1,38 @@
+/**
+ * Spam-complaint findings for Overview aggregation (console §9.9 · §9.16).
+ *
+ * Uses the Channels taxonomy — complaints burn sender reputation.
+ */
+
+import { isConsequenceEmphasized } from "./taxonomy.ts";
+import type { OutcomeRow } from "./types.ts";
+
+/** One spam-complaint finding from the Channels panel. */
+export interface SpamComplaintFinding {
+  readonly state: "delivered-then-complained";
+  readonly count: number;
+  readonly verdict: OutcomeRow["verdict"];
+  readonly weight: number;
+}
+
+/**
+ * Delivered-then-complained rows with consequence emphasis.
+ *
+ * @param outcomes - Channels seven-state outcome rows
+ */
+export function spamComplaintFindings(
+  outcomes: readonly OutcomeRow[],
+): readonly SpamComplaintFinding[] {
+  return outcomes
+    .filter(
+      (r) =>
+        r.state === "delivered-then-complained" &&
+        isConsequenceEmphasized(r),
+    )
+    .map((r) => ({
+      state: "delivered-then-complained" as const,
+      count: r.count,
+      verdict: r.verdict,
+      weight: r.weight,
+    }));
+}

package/src/console/ui/channels/fixture.ts

@@ -0,0 +1,134 @@
+/**
+ * Fixture channels for unit tests and the axe gate.
+ */
+
+import type { ChannelsListResponse } from "./types.ts";
+
+/** Sample Channels list (deliverability face). */
+export const CHANNELS_LIST_FIXTURE: ChannelsListResponse = {
+  face: "deliverability",
+  production: true,
+  templates: [
+    {
+      name: "otp-code",
+      medium: "any",
+      locales: ["en", "ar"],
+      from: "noreply@example.com",
+      schema: {
+        type: "object",
+        properties: { code: { type: "string" } },
+      },
+    },
+    {
+      name: "booking-confirmed",
+      medium: "email",
+      locales: ["en"],
+      from: "bookings@example.com",
+      schema: null,
+    },
+  ],
+  outcomes: [
+    {
+      state: "delivered-then-complained",
+      count: 4,
+      verdict: "review",
+      weight: 10,
+    },
+    {
+      state: "hard-bounce",
+      count: 14,
+      verdict: "suppress",
+      weight: 5,
+    },
+    {
+      state: "soft-bounce",
+      count: 8,
+      verdict: "retry",
+      weight: 4,
+    },
+    {
+      state: "provider-error",
+      count: 2,
+      verdict: "retry",
+      weight: 4,
+    },
+    {
+      state: "blocked/invalid-address",
+      count: 1,
+      verdict: "review",
+      weight: 3,
+    },
+    {
+      state: "suppressed/prior-bounce",
+      count: 6,
+      verdict: "correct",
+      weight: 1,
+    },
+    {
+      state: "suppressed/opted-out",
+      count: 12,
+      verdict: "correct",
+      weight: 0,
+    },
+  ],
+  fallback: {
+    template: null,
+    chainExample: "whatsapp failed → sms succeeded",
+    fallbackRate: 0.23,
+    fallbackCount: 23,
+    totalCount: 100,
+    weeklyDeltaUsd: 38,
+    primaryMedium: "whatsapp",
+    fallbackMedium: "sms",
+    summary: "23% fell back · $38 / week above whatsapp-only",
+  },
+  inbox: [
+    {
+      id: "in-1",
+      medium: "sms",
+      toMasked: "+966***000",
+      subject: null,
+      text: "code 1234",
+      html: null,
+      template: "otp-code",
+      locale: "ar",
+      at: 1,
+    },
+  ],
+  receipts: [
+    {
+      id: "r-1",
+      template: "otp-code",
+      toMasked: "a***@e***.com",
+      medium: "any",
+      locale: "ar",
+      localeChain: ["accept-language:ar", "default:en"],
+      status: "fallback",
+      chain: "whatsapp failed → sms succeeded",
+      messageId: "m-1",
+      at: 2,
+      error: null,
+    },
+  ],
+  suppression: [
+    {
+      subjectMasked: "b***@e***.com",
+      medium: "email",
+      reason: "prior-bounce",
+      at: 3,
+    },
+    {
+      subjectMasked: "u***@e***.com",
+      medium: "email",
+      reason: "opted-out",
+      at: 4,
+    },
+  ],
+};
+
+/** Dev-face fixture. */
+export const CHANNELS_INBOX_FIXTURE: ChannelsListResponse = {
+  ...CHANNELS_LIST_FIXTURE,
+  face: "inbox",
+  production: false,
+};

package/src/console/ui/channels/group.ts

@@ -0,0 +1,25 @@
+/**
+ * Filter / group channel templates by query.
+ */
+
+import type { ChannelTemplate } from "./types.ts";
+
+/**
+ * Filter templates by name / medium / locale query.
+ *
+ * @param templates - Template rows
+ * @param q - Free-text filter
+ */
+export function filterTemplates(
+  templates: readonly ChannelTemplate[],
+  q: string,
+): readonly ChannelTemplate[] {
+  const needle = q.trim().toLowerCase();
+  if (!needle) return templates;
+  return templates.filter(
+    (t) =>
+      t.name.toLowerCase().includes(needle) ||
+      t.medium.toLowerCase().includes(needle) ||
+      t.locales.some((l) => l.toLowerCase().includes(needle)),
+  );
+}

package/src/console/ui/channels/index.ts

@@ -0,0 +1,57 @@
+/**
+ * Channels panel pure modules (console §9.9).
+ */
+
+export type {
+  ChannelPreview,
+  ChannelTemplate,
+  ChannelsFace,
+  ChannelsListResponse,
+  DeliveryOutcomeState,
+  DeliveryVerdict,
+  EmailAuthView,
+  FallbackMetric,
+  InboxRow,
+  OutcomeRow,
+  ReceiptRow,
+  SuppressionRow,
+} from "./types.ts";
+
+export {
+  isConsequenceEmphasized,
+  sortByConsequence,
+  STATE_LABEL,
+  VERDICT_LABEL,
+} from "./taxonomy.ts";
+
+export {
+  spamComplaintFindings,
+  type SpamComplaintFinding,
+} from "./findings.ts";
+
+export { formatFallbackLine } from "./fallback.ts";
+
+export { dirForLocale, formatLocaleChainDisplay } from "./locale.ts";
+
+export {
+  sendTestConfirmation,
+  UNDO_WINDOW_MS,
+  validateTypedConfirm,
+  type ConfirmationPattern,
+} from "./confirmation.ts";
+
+export { looksMasked } from "./mask.ts";
+
+export {
+  openTemplate,
+  parseChannelsSearch,
+  serializeChannelsSearch,
+  type ChannelsSearch,
+} from "./search.ts";
+
+export { filterTemplates } from "./group.ts";
+
+export {
+  CHANNELS_INBOX_FIXTURE,
+  CHANNELS_LIST_FIXTURE,
+} from "./fixture.ts";

package/src/console/ui/channels/locale.test.ts

@@ -0,0 +1,17 @@
+/**
+ * Locale chain + RTL.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { dirForLocale, formatLocaleChainDisplay } from "./locale.ts";
+
+describe("locale display", () => {
+  test("formats chain and detects RTL", () => {
+    expect(
+      formatLocaleChainDisplay(["profile:ar", "default:en"]),
+    ).toBe("profile:ar → default:en");
+    expect(dirForLocale("ar")).toBe("rtl");
+    expect(dirForLocale("ar-SA")).toBe("rtl");
+    expect(dirForLocale("en")).toBe("ltr");
+  });
+});

package/src/console/ui/channels/locale.ts

@@ -0,0 +1,31 @@
+/**
+ * Locale chain display + RTL dir (console §9.9).
+ */
+
+/**
+ * Format locale resolution chain for display.
+ *
+ * @param chain - Resolution steps
+ */
+export function formatLocaleChainDisplay(
+  chain: readonly string[],
+): string {
+  if (chain.length === 0) return "default";
+  return chain.join(" → ");
+}
+
+/**
+ * Document direction for a locale tag.
+ *
+ * @param locale - BCP 47 locale
+ */
+export function dirForLocale(locale: string): "ltr" | "rtl" {
+  const base = locale.toLowerCase().split("-")[0] ?? locale;
+  return base === "ar" ||
+    base === "he" ||
+    base === "fa" ||
+    base === "ur" ||
+    base === "yi"
+    ? "rtl"
+    : "ltr";
+}

package/src/console/ui/channels/mask.test.ts

@@ -0,0 +1,14 @@
+/**
+ * Masked recipient display helper.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { looksMasked } from "./mask.ts";
+
+describe("looksMasked", () => {
+  test("detects masked emails and phones", () => {
+    expect(looksMasked("a***@e***.com")).toBe(true);
+    expect(looksMasked("+966***000")).toBe(true);
+    expect(looksMasked("alice@example.com")).toBe(false);
+  });
+});

package/src/console/ui/channels/mask.ts

@@ -0,0 +1,12 @@
+/**
+ * Recipient display helpers — server already masks; UI never invents cleartext.
+ */
+
+/**
+ * Whether a displayed recipient looks masked.
+ *
+ * @param toMasked - Display string from the server
+ */
+export function looksMasked(toMasked: string): boolean {
+  return toMasked.includes("***") || toMasked === "[redacted]";
+}

package/src/console/ui/channels/search.ts

@@ -0,0 +1,58 @@
+/**
+ * Typed search params for the Channels panel (console §7 · §9.9).
+ */
+
+import { z } from "zod";
+
+const ChannelsSearchSchema = z.object({
+  q: z.string().optional(),
+  template: z.string().optional(),
+  locale: z.string().optional(),
+  view: z
+    .enum(["inbox", "outcomes", "receipts", "suppression", "preview"])
+    .optional(),
+});
+
+/** Parsed Channels URL search. */
+export type ChannelsSearch = z.infer<typeof ChannelsSearchSchema>;
+
+/**
+ * Parse Channels panel search params.
+ *
+ * @param search - Raw router search
+ */
+export function parseChannelsSearch(
+  search: Record<string, unknown>,
+): ChannelsSearch {
+  const parsed = ChannelsSearchSchema.safeParse(search);
+  return parsed.success ? parsed.data : {};
+}
+
+/**
+ * Serialize Channels search for navigation.
+ *
+ * @param search - Search state
+ */
+export function serializeChannelsSearch(
+  search: ChannelsSearch,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (search.q) out.q = search.q;
+  if (search.template) out.template = search.template;
+  if (search.locale) out.locale = search.locale;
+  if (search.view) out.view = search.view;
+  return out;
+}
+
+/**
+ * Open a template in the URL.
+ *
+ * @param search - Current search
+ * @param template - Template name
+ */
+export function openTemplate(
+  search: ChannelsSearch,
+  template: string,
+): ChannelsSearch {
+  return { ...search, template };
+}

package/src/console/ui/channels/taxonomy.test.ts

@@ -0,0 +1,17 @@
+/**
+ * Taxonomy weighting — complaints outrank many hard bounces.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { CHANNELS_LIST_FIXTURE } from "./fixture.ts";
+import { isConsequenceEmphasized, sortByConsequence } from "./taxonomy.ts";
+
+describe("channels taxonomy", () => {
+  test("complaints rank above hard bounces despite lower count", () => {
+    const ranked = sortByConsequence(CHANNELS_LIST_FIXTURE.outcomes);
+    expect(ranked[0]!.state).toBe("delivered-then-complained");
+    expect(ranked[0]!.count).toBe(4);
+    expect(ranked.find((r) => r.state === "hard-bounce")!.count).toBe(14);
+    expect(isConsequenceEmphasized(ranked[0]!)).toBe(true);
+  });
+});

package/src/console/ui/channels/taxonomy.ts

@@ -0,0 +1,49 @@
+/**
+ * Seven-state taxonomy presentation (console §9.9).
+ *
+ * Weight follows consequence, not magnitude.
+ */
+
+import type { DeliveryOutcomeState, DeliveryVerdict, OutcomeRow } from "./types.ts";
+
+/** Human labels for states. */
+export const STATE_LABEL: Readonly<Record<DeliveryOutcomeState, string>> = {
+  "suppressed/opted-out": "Suppressed · opted out",
+  "suppressed/prior-bounce": "Suppressed · prior hard bounce",
+  "blocked/invalid-address": "Blocked · invalid address",
+  "soft-bounce": "Soft bounce",
+  "hard-bounce": "Hard bounce",
+  "provider-error": "Provider error",
+  "delivered-then-complained": "Delivered then complained",
+};
+
+/** Human labels for verdicts. */
+export const VERDICT_LABEL: Readonly<Record<DeliveryVerdict, string>> = {
+  correct: "correct",
+  retry: "retry",
+  suppress: "suppress",
+  review: "review",
+};
+
+/**
+ * Sort rows by consequence weight (already ranked server-side; re-sort locally).
+ *
+ * @param rows - Outcome rows
+ */
+export function sortByConsequence(
+  rows: readonly OutcomeRow[],
+): readonly OutcomeRow[] {
+  return [...rows].sort((a, b) => {
+    if (b.weight !== a.weight) return b.weight - a.weight;
+    return b.count - a.count;
+  });
+}
+
+/**
+ * Whether a row should be visually emphasized (high consequence with count).
+ *
+ * @param row - Outcome row
+ */
+export function isConsequenceEmphasized(row: OutcomeRow): boolean {
+  return row.weight >= 10 && row.count > 0;
+}