cbrowser 18.40.0 → 18.41.0

package/dist/visual/cognitive-models.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Cognitive Models — Formal implementations from cognitive science
+ *
+ * Layer 4: Grossman & Balakrishnan (2005) probabilistic pointing model
+ * Layer 6: Perry, Zorzi & Ziegler (2019) multi-deficit reading model
+ *
+ * These replace the heuristic multipliers in cognitive-transport.ts
+ * with empirically grounded computational models.
+ *
+ * @see Grossman & Balakrishnan (2005) ACM TOCHI — probabilistic 2D pointing
+ * @see Perry, Zorzi & Ziegler (2019) Psychological Science — personalized dyslexia models
+ * @since v18.39.0
+ */
+/**
+ * Standard normal CDF (cumulative distribution function).
+ * Abramowitz and Stegun approximation (7.1.26), error < 7.5e-8.
+ */
+declare function normalCDF(x: number): number;
+/**
+ * Standard normal PDF (probability density function).
+ */
+declare function normalPDF(x: number): number;
+export interface PointingProfile {
+    /** Endpoint dispersion SD in pixels (x-axis) */
+    sigmaX: number;
+    /** Endpoint dispersion SD in pixels (y-axis) */
+    sigmaY: number;
+    /** Correlation between x and y endpoint distributions */
+    rho: number;
+    /** Fitts' throughput (bits/s) */
+    throughput: number;
+}
+export interface TargetElement {
+    /** CSS selector or description */
+    selector: string;
+    /** Target width in pixels */
+    width: number;
+    /** Target height in pixels */
+    height: number;
+    /** Distance from likely cursor position (center of viewport) in pixels */
+    distance: number;
+}
+export interface MotorAccessibilityResult {
+    /** Per-element hit probability (0-1) */
+    elements: Array<{
+        selector: string;
+        hitProbability: number;
+        movementTime: number;
+        isBarrier: boolean;
+    }>;
+    /** Overall motor accessibility score (0-1, higher = more accessible) */
+    score: number;
+    /** Number of motor barriers found */
+    barrierCount: number;
+    /** Transport cost for this layer */
+    transportCost: number;
+}
+/**
+ * Known pointing profiles from the empirical literature.
+ *
+ * - Neurotypical baseline: MacKenzie (1992), Soukoreff & MacKenzie (2004)
+ * - Motor tremor: Hwang et al. (2004) ACM ASSETS
+ * - Elderly 65+: Chaparro et al. (1999), Ketcham et al. (2002)
+ * - ADHD: Flapper et al. (2006) — impulsive timing, near-normal precision
+ */
+declare const KNOWN_POINTING_PROFILES: Record<string, PointingProfile>;
+/**
+ * Derive a pointing profile from persona traits.
+ *
+ * Maps cognitive trait values to motor parameters by interpolating
+ * between known empirical profiles. Uses `motorPrecision` (derived from
+ * proceduralFluency and patience) as the primary interpolation axis.
+ *
+ * @param persona - Persona traits object with cognitive dimensions
+ * @returns Empirically calibrated pointing profile
+ */
+export declare function getPointingProfile(persona: {
+    traits?: Record<string, number>;
+    accessibilityTraits?: Record<string, boolean>;
+    name?: string;
+}): PointingProfile;
+/**
+ * Compute the probability that a user hits a rectangular target.
+ *
+ * Grossman & Balakrishnan (2005) bivariate normal integral over target rectangle.
+ * For independent axes (rho=0): P(hit) = Phi(W/(2*sigmaX)) * Phi(H/(2*sigmaY))
+ * For correlated axes (rho!=0): applies the Plackett (1954) correction term.
+ *
+ * Assumes the user aims at the target center (optimal aiming point).
+ *
+ * @param target - Target element dimensions
+ * @param profile - User's pointing profile
+ * @returns Hit probability in [0, 1]
+ */
+export declare function computeHitProbability(target: TargetElement, profile: PointingProfile): number;
+/**
+ * Compute Fitts' Law movement time for reaching a target.
+ *
+ * Uses the Shannon formulation (MacKenzie 1992, ISO 9241-9):
+ *   MT = (1/throughput) * log2(D/W + 1)
+ *
+ * @param distance - Distance to target center in pixels
+ * @param width - Effective target width in the movement direction (pixels)
+ * @param throughput - User's Fitts' throughput in bits/s
+ * @returns Movement time in milliseconds
+ */
+export declare function computeFittsTime(distance: number, width: number, throughput: number): number;
+/**
+ * Compute motor accessibility for a set of target elements.
+ *
+ * For each element, computes hit probability and movement time using the
+ * Grossman & Balakrishnan pointing model and Fitts' Law. Identifies
+ * motor barriers: elements where P(hit) falls below a persona-adjusted threshold.
+ *
+ * Barrier thresholds (from WCAG 2.5 / AAA guidance):
+ * - Neurotypical (throughput >= 4.0): P(hit) < 0.85 is a barrier
+ * - Impaired (throughput < 4.0): P(hit) < 0.70 is a barrier (relaxed standard)
+ *
+ * @param targets - Interactive elements on the page
+ * @param persona - Persona to evaluate for
+ * @returns Motor accessibility result with per-element breakdown
+ */
+export declare function motorAccessibility(targets: TargetElement[], persona: {
+    traits?: Record<string, number>;
+    accessibilityTraits?: Record<string, boolean>;
+    name?: string;
+}): MotorAccessibilityResult;
+export interface ReadingProfile {
+    /** Orthographic processing speed (0-1, 1=fluent) */
+    orthographic: number;
+    /** Phonological decoding ability (0-1) */
+    phonological: number;
+    /** Visual span (number of characters processed per fixation) */
+    visualSpan: number;
+    /** Vocabulary breadth (0-1) */
+    vocabulary: number;
+    /** Crowding sensitivity (0-1, higher = more affected by crowding) */
+    crowding: number;
+}
+export interface TextBlock {
+    /** Text content */
+    text: string;
+    /** Font size in pixels */
+    fontSize: number;
+    /** Line height ratio (e.g., 1.5) */
+    lineHeight: number;
+    /** Font family */
+    fontFamily: string;
+    /** Whether font is serif or sans-serif */
+    isSerif: boolean;
+    /** Contrast ratio (foreground vs background) */
+    contrastRatio: number;
+}
+export interface ReadabilityResult {
+    /** Per-text-block reading difficulty */
+    blocks: Array<{
+        text: string;
+        difficulty: number;
+        fixationDuration: number;
+        wordsPerMinute: number;
+        penalties: string[];
+    }>;
+    /** Overall readability score (0-1, higher = more readable) */
+    score: number;
+    /** Transport cost for this layer */
+    transportCost: number;
+}
+/**
+ * Known reading profiles from the empirical literature.
+ *
+ * - Neurotypical: Rayner (2009) — typical college reader
+ * - Dyslexic: Perry, Zorzi & Ziegler (2019) Psychological Science
+ * - Low vision: Legge et al. (2007) — central scotoma and crowding
+ * - ADHD: Dhar et al. (2010) — intact decoding, reduced sustained attention
+ * - Elderly: Rayner et al. (2006) — aging effects on eye movements
+ */
+declare const KNOWN_READING_PROFILES: Record<string, ReadingProfile>;
+/**
+ * Derive a reading profile from persona traits.
+ *
+ * Maps cognitive trait values to reading parameters by selecting the
+ * closest known profile and interpolating with the neurotypical baseline.
+ *
+ * @param persona - Persona traits object
+ * @returns Empirically calibrated reading profile
+ */
+export declare function getReadingProfile(persona: {
+    traits?: Record<string, number>;
+    name?: string;
+}): ReadingProfile;
+/**
+ * Estimate the proportion of irregular words in a text passage.
+ *
+ * Returns the fraction of words that contain irregular grapheme-phoneme
+ * correspondences. This determines the orthographic processing demand:
+ * higher irregularity = more reliance on whole-word recognition.
+ *
+ * @param text - Text passage to analyze
+ * @returns Proportion of irregular words (0-1)
+ */
+export declare function estimateIrregularity(text: string): number;
+/**
+ * Compute reading difficulty for a text block using the multi-deficit model.
+ *
+ * The Perry, Zorzi & Ziegler (2019) framework models dyslexia as the
+ * intersection of multiple independent deficits. Each deficit independently
+ * increases fixation duration. The total penalty is additive (not multiplicative)
+ * because deficits affect different processing stages in the reading pipeline:
+ *
+ *   Visual input -> Visual span (crowding) -> Orthographic processing ->
+ *   Phonological decoding -> Lexical access (vocabulary) -> Comprehension
+ *
+ * Additional penalties from Rello & Baeza-Yates (2016) for font effects
+ * and WCAG 2.1 contrast requirements.
+ *
+ * @param text - Text content to analyze
+ * @param profile - Reader's deficit profile
+ * @param textBlock - Typographic properties of the text
+ * @returns Reading difficulty (0-1) and fixation duration
+ */
+export declare function computeReadingDifficulty(text: string, profile: ReadingProfile, textBlock: TextBlock): {
+    difficulty: number;
+    fixationDuration: number;
+    wordsPerMinute: number;
+    penalties: string[];
+};
+/**
+ * Compute readability for multiple text blocks using the multi-deficit model.
+ *
+ * Evaluates each text block independently, then computes an aggregate
+ * readability score weighted by text length (longer blocks matter more).
+ *
+ * @param blocks - Array of text blocks with typographic properties
+ * @param persona - Persona to evaluate for
+ * @returns Readability result with per-block breakdown and aggregate score
+ */
+export declare function readability(blocks: TextBlock[], persona: {
+    traits?: Record<string, number>;
+    name?: string;
+}): ReadabilityResult;
+/**
+ * Compute both motor and reading accessibility for a persona.
+ *
+ * Combines Layer 4 (pointing model) and Layer 6 (reading model) into
+ * a single assessment. Each layer contributes independently to the
+ * total transport cost.
+ *
+ * @param targets - Interactive elements for motor assessment
+ * @param textBlocks - Text blocks for reading assessment
+ * @param persona - Persona to evaluate
+ * @returns Combined accessibility result
+ */
+export declare function cognitiveAccessibility(targets: TargetElement[], textBlocks: TextBlock[], persona: {
+    traits?: Record<string, number>;
+    accessibilityTraits?: Record<string, boolean>;
+    name?: string;
+}): {
+    motor: MotorAccessibilityResult;
+    reading: ReadabilityResult;
+    combinedScore: number;
+    combinedTransportCost: number;
+};
+export { normalCDF as _normalCDF, normalPDF as _normalPDF };
+export { KNOWN_POINTING_PROFILES, KNOWN_READING_PROFILES };
+//# sourceMappingURL=cognitive-models.d.ts.map

package/dist/visual/cognitive-models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cognitive-models.d.ts","sourceRoot":"","sources":["../../src/visual/cognitive-models.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH;;;GAGG;AACH,iBAAS,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAcpC;AAED;;GAEG;AACH,iBAAS,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpC;AAID,MAAM,WAAW,eAAe;IAC9B,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC,wCAAwC;IACxC,QAAQ,EAAE,KAAK,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,cAAc,EAAE,MAAM,CAAC;QACvB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,OAAO,CAAC;KACpB,CAAC,CAAC;IACH,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,QAAA,MAAM,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAK5D,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,eAAe,CA6ClB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,eAAe,GAAG,MAAM,CAsC7F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAK5F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,aAAa,EAAE,EACxB,OAAO,EAAE;IACP,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GACA,wBAAwB,CA6B1B;AAID,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,OAAO,EAAE,OAAO,CAAC;IACjB,gDAAgD;IAChD,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,wCAAwC;IACxC,MAAM,EAAE,KAAK,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC;QACnB,gBAAgB,EAAE,MAAM,CAAC;QACzB,cAAc,EAAE,MAAM,CAAC;QACvB,SAAS,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC,CAAC;IACH,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,QAAA,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAM1D,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,cAAc,CA2CjB;AAcD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAUzD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,SAAS,GACnB;IACD,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB,CAoFA;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,SAAS,EAAE,EACnB,OAAO,EAAE;IACP,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GACA,iBAAiB,CAkCnB;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,aAAa,EAAE,EACxB,UAAU,EAAE,SAAS,EAAE,EACvB,OAAO,EAAE;IACP,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GACA;IACD,KAAK,EAAE,wBAAwB,CAAC;IAChC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,qBAAqB,EAAE,MAAM,CAAC;CAC/B,CAeA;AAID,OAAO,EAAE,SAAS,IAAI,UAAU,EAAE,SAAS,IAAI,UAAU,EAAE,CAAC;AAC5D,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,CAAC"}