cbrowser 20.2.2 → 21.0.0

package/dist/visual/cognitive-transport-chain.d.ts

@@ -2,7 +2,7 @@
  * Cognitive Optimal Transport — Sequential Transport Chain
  *
  * Implements the CHI 2027 paper's core contribution:
- * - 26-dimensional demand distribution computed from page features
+ * - 29-dimensional demand distribution computed from page features
  * - Sequential transport chain where each layer depletes capacity
  * - Asymmetric deficit-surplus cost
  * - Layer interaction terms
@@ -14,7 +14,8 @@
  * @see Section 3.4 of "Cognitive Optimal Transport: A Unified Framework"
  * @since v18.39.0
  */
-import { type OTCognitiveProfile } from './cognitive-transport.js';
+import { type OTCognitiveProfile, type MetricScope } from './cognitive-transport.js';
+import { type PercentileCurve, type PercentileInterval } from './ctc-reference.js';
 /** Page metrics extracted from a live page (matches extractPageMetrics return) */
 export interface PageMetrics {
     informationDensity: number;
@@ -30,16 +31,77 @@ export interface PageMetrics {
     longWordRatio?: number;
     technicalDensity?: number;
     scriptFamily?: 'alphabetic' | 'cjk' | 'abjad';
+    /** What the metrics were measured over; extractPageMetrics always sets it. */
+    scope?: MetricScope;
+    /**
+     * Stage B: seconds of work for the reference user from published laws
+     * (deriveMetrics, demand-laws.ts). The motor, decision, procedure and
+     * reading demands are these against one time budget, d = T / (T + tau)
+     * (law.timeBudget). Required: computeDemandDistribution throws without them,
+     * so no demand falls back to a hand-set curve.
+     */
+    pointingSeconds: number;
+    choosingSeconds: number;
+    readingSeconds: number;
+    procedureSeconds: number;
+    /**
+     * Stage C: the same choices by Hick-Hyman, the expert limit of the menu
+     * model whose novice limit is choosingSeconds (Cockburn, Gutwin & Greenberg
+     * 2007). cognitiveLoad's demand reads (1 - e) choosingSeconds +
+     * e choosingSecondsExpert, e the run's siteFamiliarity (DemandOptions).
+     * Required like the four above.
+     */
+    choosingSecondsExpert: number;
+}
+/** What a run supplies to the demand besides the page: the visit, the same for every persona scored in it. */
+export interface DemandOptions {
+    /**
+     * Cockburn et al.'s (2007) expertise e with the page's choices, from 0 (a
+     * first visit, the default and the reference curve's) to 1 (a daily user
+     * who knows where everything is): Eq. 4, T = (1 - e) T_novice + e T_expert,
+     * applied to the choosing time the cognitiveLoad abilities are asked (the
+     * decision dispositions keep the first-visit time; see
+     * computeDemandDistribution). A definition: the parameter IS their e, with
+     * the layout's learnability L folded in by whoever supplies it. Refused
+     * outside [0, 1], never clamped.
+     */
+    siteFamiliarity?: number;
 }
 export interface DemandDistribution {
-    /** 26-dimensional demand vector (0-1 per trait) */
+    /** 29-dimensional demand vector (0-1 per trait), one slot per DEMAND_DIMENSIONS entry */
     demands: Record<string, number>;
-    /** Per-dimension demand variance (from spatial variability across page) */
-    variance: Record<string, number>;
+    /**
+     * The scope the page metrics were measured at, carried from PageMetrics so
+     * that totalCTC is ranked against reference pages measured the same way. A
+     * full-page measurement of a long page asks far more than its first screen,
+     * and ranking it among first screens would call every long page hard.
+     * Absent on a demand built from raw numbers; such a demand is ranked against
+     * the viewport reference, extractPageMetrics' default scope.
+     */
+    scope?: MetricScope;
 }
 export interface LayerResult {
     name: string;
     transportCost: number;
+    /**
+     * Capacity this layer actually removed from the account, summed over all
+     * DEMAND_DIMENSIONS: its own dimensions (direct drawdown) and every other one
+     * (indirect, cross-layer fatigue). Measured from the balances before and
+     * after the layer, so everything that limits the draw is inside it: 0 when
+     * the content gate kept the layer from depleting, the drawdown cap
+     * (chain.maxDrawdownFraction) on a heavy layer, and the capacity floor
+     * (chain.capacityEpsilon), which can stop a draw but is never counted as one.
+     * Units are capacity summed over dimensions, so the most one layer can
+     * remove is the number of dimensions.
+     *
+     * Why this definition. The name promises what the layer took out of the
+     * budget. The indirect share is the part every LATER layer on the page
+     * feels (a layer's own dimensions are not read again on the same page), so
+     * a figure without it would report only the part that matters least.
+     * Through 21.0 this was depletionRate x cost: the draw the layer would have
+     * made with no gate, no cap and no floor, reported even when nothing was
+     * drawn.
+     */
     capacityConsumed: number;
     residualCapacity: Record<string, number>;
     /**
@@ -50,17 +112,45 @@ export interface LayerResult {
     headroom: number;
 }
 export interface SequentialTransportResult {
-    /** Total Cognitive Transport Cost */
+    /**
+     * Total Cognitive Transport Cost as a PERCENTILE in [0, 1]: where `rawCTC`
+     * falls among the raw costs of the reference pages (src/data/ctc-reference-*.ts,
+     * measured at this demand's scope) for every built-in persona, pooled, under
+     * the same asymmetric and interactions options. Linear between the order
+     * statistics (ctc-reference.ts). 0.5 is the pooled median; 1 means at least
+     * as costly as the costliest (page, persona) pair in the reference, and 0 no
+     * costlier than the cheapest. Relative to real pages, not a probability and
+     * not a validated difficulty: no human data has tested it.
+     */
     totalCTC: number;
+    /**
+     * 95% interval for totalCTC, [low, high]: where this rawCTC's percentile
+     * falls across bootstrap resamples of the reference PAGES
+     * (ctc-reference.ts, bootstrapPercentileInterval). It measures how firmly
+     * the reference fixes the scale, the sampling error of ranking against a
+     * few hundred real pages; it says nothing about whether rawCTC is right.
+     * [0, 0] below the reference and [1, 1] above it.
+     */
+    totalCTCInterval: [number, number];
+    /** Which reference totalCTC was ranked against: the demand's scope, or viewport when it has none. */
+    referenceScope: MetricScope;
     /** Per-layer results in sequential order */
     layers: LayerResult[];
     /** Pairwise interaction terms */
     interactions: Record<string, number>;
     /** Additive-only CTC for comparison */
     additiveCTC: number;
-    /** Un-normalized total. `totalCTC` is a sigmoid of this. */
+    /**
+     * The un-normalised total, in layer-cost units: the sum of layer costs and
+     * interaction terms. `totalCTC` is its percentile, so any ratio against
+     * additiveCTC, and any bound on the chain itself (dro-bound.ts), uses this.
+     */
     rawCTC: number;
-    /** Asymmetric deficit-surplus breakdown */
+    /**
+     * Asymmetric deficit-surplus breakdown. deficitCost also holds the exposure
+     * cost of EXPOSURE_DIMENSIONS (a cost the page imposes), and abandonment
+     * reads it; surplusCost is billed surplus only.
+     */
     deficitCost: number;
     surplusCost: number;
     /** Per-trait transport cost */
@@ -78,12 +168,20 @@ export interface SequentialTransportResult {
     remainingCapacity: Record<string, number>;
 }
 /**
- * The 26 demand dimensions used by the sequential transport chain.
- * Superset of the base 25 OT cognitive traits — includes extended traits
- * from CognitiveTraits that capture decision biases, learning transfer,
- * and emotional regulation.
+ * The 29 demand dimensions used by the sequential transport chain, covering
+ * the core capacities plus decision biases, learning transfer, emotional
+ * regulation and the bridged reading/motor/attention capacities.
+ *
+ * NOT the same space as COGNITIVE_TRAITS (29). Four dimensions exist only here
+ * (attentionPattern, motorPrecision, processingSpeed, textProcessing: no persona
+ * in the tool path carries them, so they read the missing-trait fallback, and
+ * none is in a layer). Four traits exist only there (attributionStyle,
+ * timeHorizon, authoritySensitivity: no demand term; siteFamiliarity: a visit
+ * state the demand reads, DemandOptions, since 21.0). Both differences are
+ * pinned in tests/transport-dimension-alignment.test.ts, so a new one fails a
+ * test; nothing asserts the two sets are equal.
  */
-export declare const DEMAND_DIMENSIONS: readonly ["patience", "riskTolerance", "comprehension", "persistence", "workingMemory", "readingTendency", "resilience", "selfEfficacy", "emotionalContagion", "satisficing", "anchoringBias", "fearOfMissingOut", "socialProofSensitivity", "changeBlindness", "attentionPattern", "motorPrecision", "proceduralFluency", "informationForaging", "metacognitivePlanning", "transferLearning", "interruptRecovery", "trustCalibration", "mentalModelFlexibility", "curiosity", "processingSpeed", "textProcessing", "siteFamiliarity", "readingCapacity", "motorCapacity", "sustainedAttention"];
+export declare const DEMAND_DIMENSIONS: readonly ["patience", "riskTolerance", "comprehension", "persistence", "workingMemory", "readingTendency", "resilience", "selfEfficacy", "emotionalContagion", "satisficing", "anchoringBias", "fearOfMissingOut", "socialProofSensitivity", "changeBlindness", "attentionPattern", "motorPrecision", "proceduralFluency", "informationForaging", "metacognitivePlanning", "transferLearning", "interruptRecovery", "trustCalibration", "mentalModelFlexibility", "curiosity", "processingSpeed", "textProcessing", "readingCapacity", "motorCapacity", "sustainedAttention"];
 /**
  * Layer definitions for the sequential transport chain.
  * Order reflects temporal processing: perception -> cognition -> decision -> action -> affect -> comprehension.
@@ -100,6 +198,91 @@ export declare const LAYER_DEFINITIONS: Array<{
     name: string;
     traits: string[];
 }>;
+/**
+ * Pairwise interaction definitions: five cross-layer couplings, each a
+ * hand-set hypothesis registered in provenance/chain.ts (no empirical
+ * calibration exists for them; an earlier comment claimed one). The weight
+ * is read through param() so a run records that it depended on it.
+ */
+export declare const INTERACTION_PAIRS: Array<{
+    a: string;
+    b: string;
+    weight: string;
+}>;
+/**
+ * Dimensions where having MORE than the page asks for costs nothing at all.
+ *
+ * THE RULE, decided 2026-08-03, and it is derivable rather than chosen: surplus
+ * is FREE where the dimension's own `highEnd` names an ABILITY, and BILLED
+ * where it names a TENDENCY, a BIAS, or a SUSCEPTIBILITY. Read the trait
+ * reference and the classification falls out; a new dimension is classified by
+ * its own definition, not by anyone's taste.
+ *
+ * Why the split is real. Billing surplus is defensible for a disposition: a
+ * maximiser on a trivial page genuinely over-deliberates, and a careful reader
+ * genuinely reads a page that did not need reading. That is effort spent. It is
+ * NOT defensible for an ability -- having more working memory, or recognising
+ * conventions faster, than a page requires cannot make that page harder. The
+ * capacity/disposition axis is the same one that moved readingTendency to the
+ * demand side and kept comprehension out of the readability layer.
+ *
+ * What it was costing. Measured on a mid-density page before this change,
+ * SEVENTY PERCENT of `power-user`'s total cost was surplus, and 60% of
+ * `cognitive-adhd`'s. A uniform-capacity sweep produced a U:
+ *
+ *   capacity  0.2    0.4    0.6    0.8    1.0
+ *   cost      0.549  0.081  0.076  0.179  0.516
+ *
+ * A maximally capable persona scored almost exactly as badly as a maximally
+ * impaired one, for opposite reasons, and the output could not tell you which.
+ * That is the same defect as every other one this campaign found: a number that
+ * does not mean what its name says.
+ *
+ * Three dimensions stay billed BECAUSE THEIR SCALE IS INVERTED -- trustCalibration,
+ * curiosity and attentionPattern name a deficit at their high end ("accepts
+ * claims at face value", "easily distracted"), and none is in a layer, so the
+ * billing moves no number. changeBlindness was the fourth until 2026-10-24
+ * (below).
+ *
+ * `selfEfficacy` is the weakest call in the free set: over-confidence is a real
+ * hazard, but its cost surfaces through riskTolerance and trustCalibration
+ * rather than as effort spent, so it is treated as the ability its high end
+ * describes.
+ *
+ * A STIMULUS NEVER MAKES A PAGE CHEAPER (2026-10-24, option f of
+ * research/surplus-billing-design.md). A billed surplus costs
+ * weightSurplus (c - d)^2, which FALLS as the page's demand d rises toward the
+ * persona's value c. Measured on the 514 reference pages, one carousel on a
+ * static page lowered the typical user's viewport totalCTC by 0.085 and was
+ * cheaper on 92% of them, because emotionalContagion's only demand is motion
+ * (0 on a calm page) and its calm-page surplus was the largest bill on the
+ * page. So:
+ *  - emotionalContagion is priced by EXPOSURE (EXPOSURE_DIMENSIONS):
+ *    weightSurplus x c x d. Contagion is caught from an expression (Hatfield,
+ *    Bensman, Thornton & Rapson 2014), so with no stimulus nothing is caught
+ *    and with no susceptibility nothing is caught either. The product form,
+ *    the weight and animation as the stimulus are hypotheses.
+ *  - changeBlindness is surplus-free: missing more changes than a page makes
+ *    costs nothing on a page that makes none (Simons & Levin 1997: change
+ *    blindness is "the inability to detect changes"). Its deficit side still
+ *    prices a good noticer on a complex page, a named limit.
+ *  - patience is surplus-free: its value reads as tolerated reading time
+ *    (Stage C), and tolerance left unused is not time spent; the page's time
+ *    is priced by the reading and decision layers.
+ * The decision-layer susceptibilities (fearOfMissingOut,
+ * socialProofSensitivity, anchoringBias, riskTolerance) are DEFERRED, a named
+ * limit: they still get cheaper as choosing time grows, because the cue each
+ * responds to (urgency, reviews, a first option, uncertain controls) is not
+ * measured and a share of choosing time stands in for it.
+ */
+export declare const SURPLUS_FREE_DIMENSIONS: Set<string>;
+/**
+ * Dimensions priced by exposure rather than by a gap: weightSurplus x c x d,
+ * the persona's susceptibility times the stimulus, in asymmetric mode (the
+ * symmetric ablation keeps the gap). 0 when the page presents nothing, never
+ * lower for more stimulus or more susceptibility. See the note above.
+ */
+export declare const EXPOSURE_DIMENSIONS: Set<string>;
 /**
  * Hill exponent on the abandonment curve. UNCALIBRATED.
  *
@@ -119,7 +302,7 @@ export declare const LAYER_DEFINITIONS: Array<{
  * or a dose-response fit on real session data. Until then it is a shape someone
  * chose, not a shape anyone measured. (2026-08-03)
  */
-export declare const ABANDONMENT_HILL_EXPONENT = 2;
+export declare const ABANDONMENT_HILL_EXPONENT: number;
 /**
  * Relative weighting between the two motor layers. BOTH DEFAULT TO 1.0 AND ARE
  * UNCALIBRATED.
@@ -141,27 +324,76 @@ export declare const MOTOR_LAYER_WEIGHTS: {
     readonly motorProcedure: 1;
 };
 /**
- * Compute the 26-dimensional demand distribution from page metrics.
+ * Compute the 29-dimensional demand distribution from page metrics.
  *
- * Each page feature maps to specific trait dimensions via calibrated
- * sigmoid functions. The mapping encodes HOW each page characteristic
- * creates cognitive demand on specific user capacities.
+ * Since Stage B and C the demand is law times against one time budget, d =
+ * T / (T + tau) (demand-laws.ts, law.timeBudget): pointing (Fitts), choosing
+ * (Cockburn et al.'s menu model), reading (Brysbaert), procedure (KLM). What
+ * remains hand-set are the shares of those demands some traits take and the
+ * motion and clutter curves, every one a hypothesis in provenance/chain.ts.
+ * The text features (informationDensity, textDensity, word and sentence
+ * length, lexical diversity, long and technical words) and navigationDepth
+ * are reported on PageMetrics and drive no demand: reading time prices text,
+ * and depth is a property of the path, not the page (research/stage-c-design.md).
  *
  * Traits not affected by any page feature receive demand = 0.0 (no demand).
  *
  * @param pageMetrics - Extracted page analysis metrics
- * @returns DemandDistribution with per-trait demand and variance
+ * @param options - The visit: siteFamiliarity, Cockburn et al.'s expertise e
+ *   on the choosing time, the same for every persona scored in a run
+ * @returns DemandDistribution with per-trait demand
+ */
+export declare function computeDemandDistribution(pageMetrics: PageMetrics, options?: DemandOptions): DemandDistribution;
+/**
+ * Resolve a trait value from the persona's trait record.
+ * Falls back to chain.missingTraitCapacity (0.5, a hypothesis) for missing traits.
+ */
+/**
+ * A persona's capacity vector over DEMAND_DIMENSIONS, exactly as the chain reads
+ * it at the start of a page: each trait through traitValue (clamped to [0, 1],
+ * missing or non-numeric traits at chain.missingTraitCapacity).
+ * The Wasserstein-DRO bound (dro-bound.ts) works on these vectors.
  */
-export declare function computeDemandDistribution(pageMetrics: PageMetrics): DemandDistribution;
+export declare function capacityVector(traits: Record<string, number | string>): Record<string, number>;
+/**
+ * Schwartz Value → Trait Demand Modulation Coefficients
+ *
+ * Each entry maps a Schwartz value to the cognitive traits it amplifies or
+ * dampens in the demand distribution. The coefficient represents how much
+ * a high value score (1.0) amplifies (+) or dampens (-) the demand on that trait.
+ * Every coefficient is a hand-set hypothesis registered in provenance/chain.ts
+ * (the citations below motivate a direction, not a number) and is read
+ * through param() by id.
+ *
+ * Theoretical basis:
+ * - Security-driven personas demand MORE trustCalibration (Fogg 2003)
+ * - Achievement-driven personas demand LESS satisficing (Simon 1956 — they optimize)
+ * - Conformity-driven personas amplify socialProof demands (Cialdini 2001)
+ * - Stimulation-driven personas amplify curiosity but deplete patience faster
+ *
+ * @see Schwartz (1992) "Universals in the content and structure of values"
+ * @see Section 4.2 of "Cognitive Optimal Transport: A Unified Framework"
+ * @since v18.54.0
+ *
+ * Exported so cognitive_effort's useValues description can be checked against
+ * it; this table is the only place values reach a transport score.
+ */
+export declare const VALUE_DEMAND_MODULATION: Array<{
+    value: string;
+    trait: string;
+    coefficient: string;
+    layer: string;
+}>;
 /**
  * Compute the Sequential Cognitive Transport Cost (CTC).
  *
  * Unlike additive cognitive load models, the sequential chain depletes
  * capacity at each processing layer. A user who spends cognitive resources
- * on saliency detection has LESS available for subsequent decision-making.
+ * on visual clutter and motion has LESS available for subsequent decision-making.
  *
- * The algorithm processes layers in temporal order:
- *   Saliency -> Cognitive Load -> Decision -> Motor -> Frustration -> Readability
+ * The algorithm processes the eight layers of LAYER_DEFINITIONS in order:
+ *   visualComplexity -> cognitiveLoad -> decision -> motor -> motorProcedure
+ *   -> frustration -> readability -> readingAttention
  *
  * Each layer:
  * 1. Applies Schwartz value modulation to demand (v18.54.0)
@@ -170,11 +402,13 @@ export declare function computeDemandDistribution(pageMetrics: PageMetrics): Dem
  * 4. Records the remaining capacity for downstream layers
  *
  * @param persona - OTCognitiveProfile with trait values
- * @param demand - 26D demand distribution from page analysis
+ * @param demand - 29D demand distribution from page analysis
  * @param options - Enable/disable asymmetric costs, interaction terms, and value modulation
  * @returns Complete sequential transport result with per-layer breakdown
  */
-export declare function computeSequentialCTC(persona: OTCognitiveProfile, demand: DemandDistribution, options?: {
+export declare function computeSequentialCTC(persona: OTCognitiveProfile, demand: DemandDistribution, options?: ChainOptions): SequentialTransportResult;
+/** Options every chain entry point takes. */
+export interface ChainOptions {
     asymmetric?: boolean;
     interactions?: boolean;
     schwartzValues?: Record<string, number>;
@@ -187,12 +421,62 @@ export declare function computeSequentialCTC(persona: OTCognitiveProfile, demand
      * spent. (2026-08-03)
      */
     carriedCapacity?: Record<string, number>;
-}): SequentialTransportResult;
+}
+/** The curve totalCTC is read from, for one scope and option set, and what it was built from. */
+export interface ReferenceCurve {
+    scope: MetricScope;
+    asymmetric: boolean;
+    interactions: boolean;
+    /** Graded reference pages at this scope. */
+    pages: number;
+    /** Built-in personas pooled on every page. */
+    personas: number;
+    /**
+     * Every registry id the build read: the chain's constants (demand curves
+     * included), the page-metric constants the reference pages were derived and
+     * measured with, the reference's page count and the interval's settings.
+     */
+    reads: readonly string[];
+    curve: PercentileCurve;
+    /** The bootstrap interval of the curve, precomputed on a grid of raw costs. */
+    interval: PercentileInterval;
+}
+/**
+ * The percentile curve for one scope and option set: rawCTC of every graded
+ * reference page (ctc-reference.ts) for every built-in persona, through this
+ * chain, pooled. Each page's metrics are derived from its stored raw
+ * measurement (deriveMetrics) inside the build, so the page-metric
+ * normalisers move the curve exactly as the chain's constants do.
+ *
+ * WHICH OPTIONS SELECT A CURVE. `asymmetric` and `interactions` change the
+ * cost function, so each pair has its own curve: a symmetric raw cost ranked
+ * among asymmetric ones would compare two different quantities.
+ * `schwartzValues` and `carriedCapacity` do not. Both describe the person
+ * being scored (what they value, what earlier screens left them), not the
+ * yardstick, and a curve that moved with them would cancel part of the effect
+ * it is there to show. So a values-modulated score, and every screen after the
+ * first in a scroll, are ranked against the reference population as it
+ * arrives at a page. cognitive_effort's useValues edits demand before the chain
+ * runs, which lands in the same place.
+ *
+ * COST AND CACHE. One build is one deriveMetrics per page, one chain run per
+ * page per persona, and the page bootstrap (ctcReference.interval.*), under a
+ * second for the whole reference; cached per scope and option set for the
+ * life of the process, so every later score pays two binary searches. While a
+ * test overrides registered constants (activeOverrides() is non-null) a curve
+ * is cached against that override object instead: a change to any chain or
+ * page-metric constant re-derives the curve rather than reusing one built
+ * under other constants.
+ */
+export declare function ctcReferenceCurve(scope: MetricScope, options?: {
+    asymmetric?: boolean;
+    interactions?: boolean;
+}): ReferenceCurve;
 /**
  * End-to-end Cognitive Optimal Transport computation.
  *
  * Extracts page metrics from a live Playwright page, computes the
- * 26D demand distribution, and runs the full sequential transport chain.
+ * 29D demand distribution, and runs the full sequential transport chain.
  *
  * This is the primary entry point for MCP tools that need a single
  * CTC score with full breakdown.
@@ -205,8 +489,14 @@ export declare function computeFullCOT(persona: OTCognitiveProfile, page: any):
 /**
  * Compute demand distribution from raw metric values (no page required).
  * Useful for testing, simulation, and sensitivity analysis.
+ *
+ * informationDensity, textDensity and navigationDepth are carried onto the
+ * PageMetrics as reported values; since Stage C no demand reads them.
+ * choosingSecondsExpert (Stage C) is the choosing time's Hick-Hyman expert
+ * limit. It is required like the other law times and moves a demand only when
+ * options.siteFamiliarity is above 0.
  */
-export declare function computeDemandFromRawMetrics(informationDensity: number, visualComplexity: number, interactiveElementCount: number, textDensity: number, animationLevel: number, choiceCount: number, navigationDepth: number): DemandDistribution;
+export declare function computeDemandFromRawMetrics(informationDensity: number, visualComplexity: number, textDensity: number, animationLevel: number, navigationDepth: number, pointingSeconds: number, choosingSeconds: number, readingSeconds: number, procedureSeconds: number, choosingSecondsExpert: number, options?: DemandOptions): DemandDistribution;
 /**
  * Compare sequential vs. additive CTC to quantify the sequential effect.
  *
@@ -248,7 +538,11 @@ export interface ScreenResult {
     screen: number;
     /** Layer costs for this screen alone. */
     layers: LayerResult[];
-    /** This screen's own transport cost. */
+    /**
+     * This screen's totalCTC, rounded: its own raw cost (against the capacity
+     * earlier screens left) as a percentile of the reference, ranked against the
+     * reference matching its demand's scope (viewport for per-screen metrics).
+     */
     screenCTC: number;
     /** P(this persona stops HERE, given they reached this screen). */
     stopHazard: number;
@@ -273,7 +567,11 @@ export interface SequentialScrollResult {
         layer: string;
         share: number;
     } | null;
-    /** Demand each screen contributed, weighted by the chance of reaching it. */
+    /**
+     * Sum over screens of reachProbability x screenCTC: each screen's percentile,
+     * weighted by the chance of reaching it. A sum of percentiles, so it grows
+     * with the number of screens reached and is not itself a percentile.
+     */
     reachWeightedCTC: number;
 }
 /**

package/dist/visual/cognitive-transport-chain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cognitive-transport-chain.d.ts","sourceRoot":"","sources":["../../src/visual/cognitive-transport-chain.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cognitive-transport-chain.d.ts","sourceRoot":"","sources":["../../src/visual/cognitive-transport-chain.ts"],"names":[],"mappings":"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"}