cbrowser 20.2.2 → 21.0.0

package/dist/visual/model-provenance.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Where every number in the cognitive transport model comes from.
+ *
+ * A constant the model reads is either:
+ *   fitted      estimated from named data, with the held-out score in `source`
+ *   published   taken from a cited law or measurement in the literature
+ *   definition  a choice of units, scale or encoding that carries no empirical claim
+ *   hypothesis  set by hand; nothing in data or literature backs the value yet
+ *
+ * The paper and the tools report these labels instead of presenting hand-set
+ * numbers as findings. Everything the chain, the persona distance and the DRO
+ * bound read goes through `param()`, so the registry cannot drift from the code:
+ * tests record which ids a run reads and fail on an id that is read but not
+ * registered, or registered but never read.
+ *
+ * Entries live beside the code that reads them (provenance/*.ts) and are merged
+ * here, so a new constant is registered in the same file it is introduced in.
+ *
+ * @copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com https://cbrowser.ai
+ * @license MIT
+ */
+export type ProvenanceStatus = "fitted" | "published" | "definition" | "hypothesis";
+export interface ProvenanceEntry {
+    /** Stable id, `<area>.<name>`, e.g. "chain.weightDeficit". */
+    id: string;
+    value: number;
+    status: ProvenanceStatus;
+    /** Data and score for fitted, citation for published, reason for definition, what would test it for hypothesis. */
+    source: string;
+}
+export declare const MODEL_PROVENANCE: Readonly<Record<string, ProvenanceEntry>>;
+/** Read a registered constant. Throws on an unregistered id, so a typo cannot fall back silently. */
+export declare function param(id: string): number;
+/**
+ * TEST ONLY: run `fn` with some registered constants replaced, then restore
+ * them. It exists so tests/ctc-no-dead-constants.test.ts can perturb every
+ * constant and check that the output moves; no shipped code may call it (a
+ * test asserts that). Calls nest, the innermost value winning, and an
+ * unregistered id throws exactly as param() does.
+ */
+export declare function withParamOverrides<T>(values: Record<string, number>, fn: () => T): T;
+/**
+ * TEST ONLY: withParamOverrides for an async `fn`, the overrides holding
+ * until it settles. The override set is process-wide, not scoped to the async
+ * context, so anything else running meanwhile sees it too: a test awaits one
+ * override at a time (tests/journey-no-dead-constants.test.ts, which perturbs
+ * the constants a journey reads across its awaits).
+ */
+export declare function withParamOverridesAsync<T>(values: Record<string, number>, fn: () => Promise<T>): Promise<T>;
+/**
+ * The override set in force, or null outside withParamOverrides. A new object
+ * on every override call, so a cache of anything derived from registered
+ * constants (the CTC reference curve) can key on it by identity and is never
+ * served across a change of constants. Read-only: never mutate it.
+ */
+export declare function activeOverrides(): Readonly<Record<string, number>> | null;
+/** Start recording which ids `param()` reads. Returns the live set. Test and reporting use only. */
+export declare function startProvenanceRecording(): Set<string>;
+export declare function stopProvenanceRecording(): Set<string>;
+export interface ProvenanceSummary {
+    counts: Record<ProvenanceStatus, number>;
+    /** Ids of the hand-set constants the computation depended on. */
+    hypotheses: string[];
+    /** What the counts cover, so "0 fitted" is not read as "nothing in cbrowser is fitted". */
+    scope: string;
+    note: string;
+}
+/** What a block says it covers. Tools report the score's block with the defaults below. */
+export interface ProvenanceText {
+    scope?: string;
+    note?: string;
+}
+/** The text of an attention map's own block. */
+export declare const ATTENTION_PROVENANCE_TEXT: Readonly<Required<ProvenanceText>>;
+export declare const PERSONA_RATE_PROVENANCE_TEXT: Readonly<Required<ProvenanceText>>;
+export interface PersonaRateProvenance extends ProvenanceSummary {
+    /** Every rate id counted, sorted, so the published ones can be named as well as counted. */
+    rates: string[];
+}
+/** The persona-rate section of an answer, from the ids collectPersonaReads returned for the scored persona's bridge. */
+export declare function personaRateProvenance(ids: Iterable<string>): PersonaRateProvenance;
+export declare function provenanceSummary(ids: Iterable<string>, text?: ProvenanceText): ProvenanceSummary;
+/**
+ * Run `fn` and return the ids it read. Nests like withProvenance: the reads
+ * also land in any enclosing recording. Used to remember what a cached value
+ * was derived from, so a cache hit can record the same dependencies a miss
+ * would have.
+ */
+export declare function readsOf<T>(fn: () => T): {
+    result: T;
+    ids: ReadonlySet<string>;
+};
+/** Run `fn` as persona-model work: its reads go to the active collectPersonaReads set (if any) and the session, never to a score recording. */
+export declare function personaScope<T>(fn: () => T): T;
+/**
+ * Run `fn` as persona-model work and return the ids it read. A tool wraps the
+ * scored persona's bridge in this to report the rates that persona was scored
+ * with in a section of their own: computed from the persona, so no cache state
+ * can change it.
+ */
+export declare function collectPersonaReads<T>(fn: () => T): {
+    result: T;
+    ids: ReadonlySet<string>;
+};
+/**
+ * Run `fn` and return its result with the provenance of every constant it read.
+ *
+ * Synchronous: it records what `fn` reads before returning, so an async `fn`
+ * is recorded only up to its first await. Use withProvenanceAsync for that.
+ */
+export declare function withProvenance<T>(fn: () => T): {
+    result: T;
+    provenance: ProvenanceSummary;
+};
+/**
+ * withProvenance for an async function: every param() read inside `fn`,
+ * before and after each await, is recorded, and nothing read by code running
+ * concurrently in another context is. Nests like withProvenance in both
+ * directions: its reads land in any enclosing recording when it settles, and
+ * withProvenance, readsOf or another withProvenanceAsync inside it land in it.
+ *
+ * Covers what `fn` awaits. Work it starts and does not await (a fire-and-forget
+ * promise) can still read into this recording after the summary is taken, and
+ * is then counted nowhere; a tool answer awaits everything it reports.
+ */
+export declare function withProvenanceAsync<T>(fn: () => Promise<T>): Promise<{
+    result: T;
+    provenance: ProvenanceSummary;
+}>;
+/**
+ * withProvenanceAsync whose reads do NOT land in an enclosing recording: a
+ * block of its own. For work a tool does beside its score, such as the
+ * attention map cognitive_effort draws as context, whose constants (fitted
+ * gaze calibration, published colour science) would otherwise be counted as
+ * the score's and make it look partly fitted. Recordings nested inside it land
+ * in it as usual. A process-wide session (startProvenanceRecording) still sees
+ * its reads, since coverage tests count every read the process makes.
+ */
+export declare function isolatedProvenanceAsync<T>(fn: () => Promise<T>, text?: ProvenanceText): Promise<{
+    result: T;
+    provenance: ProvenanceSummary;
+}>;
+/**
+ * The provenance of the recording this code runs inside, as read so far, or
+ * null outside any. A tool handler running under withProvenanceAsync calls it
+ * as the last step before serialising its answer, so the block it reports is
+ * everything that answer read. Nested recordings that have finished are
+ * already merged into it; ones still running are not.
+ */
+export declare function activeProvenance(): ProvenanceSummary | null;
+//# sourceMappingURL=model-provenance.d.ts.map

package/dist/visual/model-provenance.d.ts.map

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

package/dist/visual/model-provenance.js

@@ -0,0 +1,334 @@
+/**
+ * Where every number in the cognitive transport model comes from.
+ *
+ * A constant the model reads is either:
+ *   fitted      estimated from named data, with the held-out score in `source`
+ *   published   taken from a cited law or measurement in the literature
+ *   definition  a choice of units, scale or encoding that carries no empirical claim
+ *   hypothesis  set by hand; nothing in data or literature backs the value yet
+ *
+ * The paper and the tools report these labels instead of presenting hand-set
+ * numbers as findings. Everything the chain, the persona distance and the DRO
+ * bound read goes through `param()`, so the registry cannot drift from the code:
+ * tests record which ids a run reads and fail on an id that is read but not
+ * registered, or registered but never read.
+ *
+ * Entries live beside the code that reads them (provenance/*.ts) and are merged
+ * here, so a new constant is registered in the same file it is introduced in.
+ *
+ * @copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com https://cbrowser.ai
+ * @license MIT
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { CHAIN_PROVENANCE } from "./provenance/chain.js";
+import { DISTANCE_PROVENANCE } from "./provenance/distance.js";
+import { DRO_PROVENANCE } from "./provenance/dro.js";
+import { PERSONA_PROVENANCE } from "./provenance/personas.js";
+import { CIF_PROVENANCE } from "./provenance/cif.js";
+import { CTC_REFERENCE_PROVENANCE } from "./provenance/ctc-reference.js";
+import { ATTENTION_PROVENANCE } from "./provenance/attention.js";
+import { PERCEPTUAL_PROVENANCE } from "./provenance/perceptual.js";
+import { PAGE_METRICS_PROVENANCE } from "./provenance/page-metrics.js";
+import { VISUAL_DISTANCE_PROVENANCE } from "./provenance/visual-distance.js";
+import { LAW_PROVENANCE } from "./provenance/laws.js";
+import { PROFILE_PROVENANCE } from "./provenance/profiles.js";
+import { PERSONA_RATE_PROVENANCE, CUSTOM_RATE_PROVENANCE } from "./provenance/persona-rates.js";
+import { JOURNEY_GROUP_PROVENANCE } from "./provenance/journey-group.js";
+function index(...groups) {
+    const out = {};
+    for (const g of groups)
+        for (const e of g) {
+            if (out[e.id])
+                throw new Error(`duplicate provenance id ${e.id}`);
+            out[e.id] = e;
+        }
+    return out;
+}
+export const MODEL_PROVENANCE = Object.freeze(index(CHAIN_PROVENANCE, DISTANCE_PROVENANCE, DRO_PROVENANCE, PERSONA_PROVENANCE, CIF_PROVENANCE, CTC_REFERENCE_PROVENANCE, ATTENTION_PROVENANCE, PERCEPTUAL_PROVENANCE, PAGE_METRICS_PROVENANCE, VISUAL_DISTANCE_PROVENANCE, LAW_PROVENANCE, PROFILE_PROVENANCE, PERSONA_RATE_PROVENANCE, CUSTOM_RATE_PROVENANCE, JOURNEY_GROUP_PROVENANCE));
+/**
+ * WHERE A READ IS RECORDED. Every recording (withProvenance, readsOf,
+ * withProvenanceAsync) is a set bound to the async context it runs in, so a
+ * read lands in the recording of the code that made it, across awaits, and
+ * never in a concurrent request's. Through 21.0 this was one module-level
+ * set: correct only while every recorded computation was synchronous, which
+ * is why a tool could record its chain run and not the page measurement or
+ * verdict around it (both happen across awaits). startProvenanceRecording is
+ * the one recording outside any context: a whole-process session for tests,
+ * seen by any read that no scoped recording claims.
+ */
+const scoped = new AsyncLocalStorage();
+let session = null;
+let overrides = null;
+/** The recording a read made here lands in: the innermost scoped one, else the session, else none. */
+function current() {
+    return scoped.getStore() ?? session;
+}
+/** Read a registered constant. Throws on an unregistered id, so a typo cannot fall back silently. */
+export function param(id) {
+    const e = MODEL_PROVENANCE[id];
+    if (!e)
+        throw new Error(`unregistered model constant "${id}"`);
+    current()?.add(id);
+    if (overrides && id in overrides)
+        return overrides[id];
+    return e.value;
+}
+/**
+ * TEST ONLY: run `fn` with some registered constants replaced, then restore
+ * them. It exists so tests/ctc-no-dead-constants.test.ts can perturb every
+ * constant and check that the output moves; no shipped code may call it (a
+ * test asserts that). Calls nest, the innermost value winning, and an
+ * unregistered id throws exactly as param() does.
+ */
+export function withParamOverrides(values, fn) {
+    for (const id of Object.keys(values)) {
+        if (!MODEL_PROVENANCE[id])
+            throw new Error(`unregistered model constant "${id}"`);
+    }
+    const outer = overrides;
+    overrides = { ...(outer ?? {}), ...values };
+    try {
+        return fn();
+    }
+    finally {
+        overrides = outer;
+    }
+}
+/**
+ * TEST ONLY: withParamOverrides for an async `fn`, the overrides holding
+ * until it settles. The override set is process-wide, not scoped to the async
+ * context, so anything else running meanwhile sees it too: a test awaits one
+ * override at a time (tests/journey-no-dead-constants.test.ts, which perturbs
+ * the constants a journey reads across its awaits).
+ */
+export async function withParamOverridesAsync(values, fn) {
+    for (const id of Object.keys(values)) {
+        if (!MODEL_PROVENANCE[id])
+            throw new Error(`unregistered model constant "${id}"`);
+    }
+    const outer = overrides;
+    overrides = { ...(outer ?? {}), ...values };
+    try {
+        return await fn();
+    }
+    finally {
+        overrides = outer;
+    }
+}
+/**
+ * The override set in force, or null outside withParamOverrides. A new object
+ * on every override call, so a cache of anything derived from registered
+ * constants (the CTC reference curve) can key on it by identity and is never
+ * served across a change of constants. Read-only: never mutate it.
+ */
+export function activeOverrides() {
+    return overrides;
+}
+/** Start recording which ids `param()` reads. Returns the live set. Test and reporting use only. */
+export function startProvenanceRecording() {
+    session = new Set();
+    return session;
+}
+export function stopProvenanceRecording() {
+    const r = session ?? new Set();
+    session = null;
+    return r;
+}
+/**
+ * The score block's scope: what a tool's `modelProvenance` counts. The
+ * attention maps a tool draws as context are recorded apart
+ * (isolatedProvenanceAsync) and carry ATTENTION_PROVENANCE_TEXT instead.
+ */
+const SCORE_SCOPE = "Every registered constant the score in this answer read: the page-metric extraction that measured the page (pageMetrics.*), " +
+    "the published laws that turn the page into seconds of pointing, choosing, reading and procedure for the reference user " +
+    "(law.*: Fitts, novice visual search, Brysbaert's reading rate, the keystroke-level model, and the first read of a menu label, " +
+    "law.reading.labelFirstRead, a hypothesis) and the one time budget each is a " +
+    "demand against (law.timeBudget, a hypothesis), the demand curves that turn the other page metrics into per-trait demand, " +
+    "the cognitive transport chain (with its Schwartz value modulation " +
+    "when values were applied), the reference set totalCTC is ranked against and the verdict bands cut on it (definitions), and the two " +
+    "persona-distance constants the persona profile reads. It does not count the attention model: an attention map in this answer " +
+    "(cognitive_effort's saliency overlay, visual_cognitive_story's attention analysis) is context for the page, not an input to the " +
+    "score, and carries its own block for the attention model's constants: published colour science, the gaze constants fitted on " +
+    "UEyes eye-tracking (held-out AUC 0.7367, GAZE_CALIBRATION) where a map applies them, and hand-set weights and filters.";
+const SCORE_NOTE = "Constants labelled hypothesis are set by hand and untested against human data. This reports where each number comes from; " +
+    "it is not a validation of the score. See MODEL_PROVENANCE for each source.";
+/** The text of an attention map's own block. */
+export const ATTENTION_PROVENANCE_TEXT = Object.freeze({
+    scope: "Every registered constant the attention model read to draw this map. The model's constants are the colour-science conversion " +
+        "(published: sRGB, CIE XYZ and L*a*b*), the gaze blend, smoothing width and spatial prior fitted on UEyes eye-tracking (held-out " +
+        "AUC 0.7367, GAZE_CALIBRATION), and hand-set channel weights, element weights and persona filters (hypotheses); the counts say " +
+        "which of them this map read. The map is context for the page, not an input to the cognitive transport score, whose constants " +
+        "are counted in modelProvenance.",
+    note: "Constants labelled fitted were estimated from free-viewing eye-tracking pooled over many people, so they say nothing about a " +
+        "particular persona; those labelled hypothesis are set by hand. This reports where each number in the map comes from; it is " +
+        "not a validation of the map. See MODEL_PROVENANCE for each source.",
+});
+/** Summarise a set of ids (what one computation read) for a tool response. */
+/** The two reference rates a capacity is a ratio against; they cancel in c = r_p / (r_p + r_ref). */
+const REFERENCE_RATE_IDS = new Set(["law.rate.pointing.reference", "law.reading.wpm"]);
+export const PERSONA_RATE_PROVENANCE_TEXT = Object.freeze({
+    scope: "The rates the scored persona's motor and reading capacities were computed from, counted apart from modelProvenance because " +
+        "they describe the persona, not the score's constants. A built-in persona's are registered with it (personaRate.*); a custom " +
+        "persona's are the rule it fell under (customRate.*), or, where it stated a reading profile, the fixation-model constants that " +
+        "turn that profile into a rate (profile.*). Each capacity is c = r_p / (r_p + r_ref) against the reference rates " +
+        "law.rate.pointing.reference and law.reading.wpm (published), which cancel in the ratio and are not counted here, nor is the pointing profile's endpoint dispersion (the hit-probability audit's, not a rate). The other " +
+        "personas' rates are part of the reference population totalCTC is ranked against (a definition) and are not listed.",
+    note: "A rate labelled published was measured on the persona's population against same-study controls; hypothesis rates include " +
+        "\"no measured difference\", the reference rate given where no source measures one. See MODEL_PROVENANCE for each source.",
+});
+/** The endpoint dispersion the bridge reads for the pointing profile it returns: the hit-probability audit's, not a rate. */
+const DISPERSION_ID = /^profile\.pointing\.(?:[^.]+\.(?:sigma|rho)|precision\..+)$/;
+/** The persona-rate section of an answer, from the ids collectPersonaReads returned for the scored persona's bridge. */
+export function personaRateProvenance(ids) {
+    const rates = [...new Set(ids)].filter((id) => MODEL_PROVENANCE[id] && !REFERENCE_RATE_IDS.has(id) && !DISPERSION_ID.test(id)).sort();
+    return { ...provenanceSummary(rates, PERSONA_RATE_PROVENANCE_TEXT), rates };
+}
+export function provenanceSummary(ids, text = {}) {
+    const counts = { fitted: 0, published: 0, definition: 0, hypothesis: 0 };
+    const hypotheses = [];
+    for (const id of ids) {
+        const e = MODEL_PROVENANCE[id];
+        if (!e)
+            continue;
+        counts[e.status]++;
+        if (e.status === "hypothesis")
+            hypotheses.push(id);
+    }
+    hypotheses.sort();
+    return {
+        counts,
+        hypotheses,
+        scope: text.scope ?? SCORE_SCOPE,
+        note: text.note ?? SCORE_NOTE,
+    };
+}
+/**
+ * Run `fn` and return the ids it read. Nests like withProvenance: the reads
+ * also land in any enclosing recording. Used to remember what a cached value
+ * was derived from, so a cache hit can record the same dependencies a miss
+ * would have.
+ */
+export function readsOf(fn) {
+    const outer = current();
+    const mine = new Set();
+    try {
+        return { result: scoped.run(mine, fn), ids: mine };
+    }
+    finally {
+        if (outer)
+            for (const id of mine)
+                outer.add(id);
+    }
+}
+/**
+ * The persona models' own recording channel. Reads made by the persona models
+ * in cognitive-models.ts (capacity rates, pointing and reading profiles, the
+ * fixation model the readability audit shares) describe the persona or an
+ * audit, not the score, so they never land in a score's recording: a score
+ * block counts demand, chain, reference and distance. Without this, a block
+ * would also count whichever personas the CTC reference curve happened to bridge
+ * on a cache miss, and the motor and readability audits a tool runs beside its
+ * score. A process-wide session (startProvenanceRecording) still sees them, as
+ * with isolatedProvenanceAsync, since coverage tests count every read the
+ * process makes. Overrides apply as usual.
+ */
+const personaCollector = new AsyncLocalStorage();
+/** Run `fn` as persona-model work: its reads go to the active collectPersonaReads set (if any) and the session, never to a score recording. */
+export function personaScope(fn) {
+    const mine = personaCollector.getStore() ?? new Set();
+    try {
+        return scoped.run(mine, fn);
+    }
+    finally {
+        if (session)
+            for (const id of mine)
+                session.add(id);
+    }
+}
+/**
+ * Run `fn` as persona-model work and return the ids it read. A tool wraps the
+ * scored persona's bridge in this to report the rates that persona was scored
+ * with in a section of their own: computed from the persona, so no cache state
+ * can change it.
+ */
+export function collectPersonaReads(fn) {
+    const mine = new Set();
+    const result = personaCollector.run(mine, () => personaScope(fn));
+    return { result, ids: mine };
+}
+/**
+ * Run `fn` and return its result with the provenance of every constant it read.
+ *
+ * Synchronous: it records what `fn` reads before returning, so an async `fn`
+ * is recorded only up to its first await. Use withProvenanceAsync for that.
+ */
+export function withProvenance(fn) {
+    const outer = current();
+    const mine = new Set();
+    try {
+        const result = scoped.run(mine, fn);
+        return { result, provenance: provenanceSummary(mine) };
+    }
+    finally {
+        if (outer)
+            for (const id of mine)
+                outer.add(id);
+    }
+}
+/**
+ * withProvenance for an async function: every param() read inside `fn`,
+ * before and after each await, is recorded, and nothing read by code running
+ * concurrently in another context is. Nests like withProvenance in both
+ * directions: its reads land in any enclosing recording when it settles, and
+ * withProvenance, readsOf or another withProvenanceAsync inside it land in it.
+ *
+ * Covers what `fn` awaits. Work it starts and does not await (a fire-and-forget
+ * promise) can still read into this recording after the summary is taken, and
+ * is then counted nowhere; a tool answer awaits everything it reports.
+ */
+export async function withProvenanceAsync(fn) {
+    const outer = current();
+    const mine = new Set();
+    try {
+        const result = await scoped.run(mine, fn);
+        return { result, provenance: provenanceSummary(mine) };
+    }
+    finally {
+        if (outer)
+            for (const id of mine)
+                outer.add(id);
+    }
+}
+/**
+ * withProvenanceAsync whose reads do NOT land in an enclosing recording: a
+ * block of its own. For work a tool does beside its score, such as the
+ * attention map cognitive_effort draws as context, whose constants (fitted
+ * gaze calibration, published colour science) would otherwise be counted as
+ * the score's and make it look partly fitted. Recordings nested inside it land
+ * in it as usual. A process-wide session (startProvenanceRecording) still sees
+ * its reads, since coverage tests count every read the process makes.
+ */
+export async function isolatedProvenanceAsync(fn, text = {}) {
+    const mine = new Set();
+    try {
+        const result = await scoped.run(mine, fn);
+        return { result, provenance: provenanceSummary(mine, text) };
+    }
+    finally {
+        if (session)
+            for (const id of mine)
+                session.add(id);
+    }
+}
+/**
+ * The provenance of the recording this code runs inside, as read so far, or
+ * null outside any. A tool handler running under withProvenanceAsync calls it
+ * as the last step before serialising its answer, so the block it reports is
+ * everything that answer read. Nested recordings that have finished are
+ * already merged into it; ones still running are not.
+ */
+export function activeProvenance() {
+    const r = current();
+    return r ? provenanceSummary(r) : null;
+}
+//# sourceMappingURL=model-provenance.js.map

package/dist/visual/model-provenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-provenance.js","sourceRoot":"","sources":["../../src/visual/model-provenance.ts"],"names":[],"mappings":"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"}

package/dist/visual/normal-cdf.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The standard normal CDF, on its own so a module can use it without
+ * importing cognitive-models.ts (and through it model-provenance.ts); see the
+ * note where cognitive-models.ts re-exports it as _normalCDF.
+ *
+ * @copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com https://cbrowser.ai
+ * @license MIT
+ */
+/**
+ * Standard normal CDF (cumulative distribution function).
+ * Abramowitz and Stegun approximation (7.1.26), error < 7.5e-8.
+ */
+export declare function normalCDF(x: number): number;
+//# sourceMappingURL=normal-cdf.d.ts.map

package/dist/visual/normal-cdf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normal-cdf.d.ts","sourceRoot":"","sources":["../../src/visual/normal-cdf.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAc3C"}

package/dist/visual/normal-cdf.js

@@ -0,0 +1,26 @@
+/**
+ * The standard normal CDF, on its own so a module can use it without
+ * importing cognitive-models.ts (and through it model-provenance.ts); see the
+ * note where cognitive-models.ts re-exports it as _normalCDF.
+ *
+ * @copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com https://cbrowser.ai
+ * @license MIT
+ */
+/**
+ * Standard normal CDF (cumulative distribution function).
+ * Abramowitz and Stegun approximation (7.1.26), error < 7.5e-8.
+ */
+export function normalCDF(x) {
+    const a1 = 0.254829592;
+    const a2 = -0.284496736;
+    const a3 = 1.421413741;
+    const a4 = -1.453152027;
+    const a5 = 1.061405429;
+    const p = 0.3275911;
+    const sign = x < 0 ? -1 : 1;
+    const absX = Math.abs(x) / Math.SQRT2;
+    const t = 1 / (1 + p * absX);
+    const y = 1 - (((((a5 * t + a4) * t) + a3) * t + a2) * t + a1) * t * Math.exp(-absX * absX);
+    return 0.5 * (1 + sign * y);
+}
+//# sourceMappingURL=normal-cdf.js.map

package/dist/visual/normal-cdf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normal-cdf.js","sourceRoot":"","sources":["../../src/visual/normal-cdf.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,CAAS;IACjC,MAAM,EAAE,GAAG,WAAW,CAAC;IACvB,MAAM,EAAE,GAAG,CAAC,WAAW,CAAC;IACxB,MAAM,EAAE,GAAG,WAAW,CAAC;IACvB,MAAM,EAAE,GAAG,CAAC,WAAW,CAAC;IACxB,MAAM,EAAE,GAAG,WAAW,CAAC;IACvB,MAAM,CAAC,GAAG,SAAS,CAAC;IAEpB,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC;IACtC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IAC7B,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IAE5F,OAAO,GAAG,GAAG,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC;AAC9B,CAAC"}

package/dist/visual/perceptual-transport.d.ts

@@ -57,14 +57,36 @@ export interface PerceptualAnalysis {
     transportDistance: number;
     computeTimeMs: number;
 }
+export declare const PERCEPTUAL_PROFILES: Record<string, PerceptualProfile>;
+export declare const DEFAULT_PROFILE: PerceptualProfile;
 /**
- * Get the perceptual profile for a persona.
+ * How a perceptual profile was found for a persona name.
+ *
+ * "builtin"     the name is one of PERCEPTUAL_PROFILES
+ * "synthesized" built from the caller's accessibility traits
+ * "inferred"    a built-in borrowed because of a keyword in the name
+ * "default"     nothing matched; DEFAULT_PROFILE, which models no one
+ */
+export type PerceptualResolution = 'builtin' | 'synthesized' | 'inferred' | 'default';
+export interface ResolvedPerceptualProfile {
+    profile: PerceptualProfile;
+    resolution: PerceptualResolution;
+    /**
+     * The profile actually used: the persona itself for builtin and synthesized,
+     * the borrowed built-in for inferred, "default" for default.
+     */
+    resolvedProfile: string;
+}
+/**
+ * Get the perceptual profile for a persona, and say how it was found.
  *
  * For built-in personas, returns the hardcoded profile.
  * For custom personas, synthesizes a profile from accessibility traits if provided,
- * or infers from the persona name as a fallback.
+ * or infers from the persona name as a fallback. An unknown name never throws
+ * (custom personas rely on the inference); it resolves to "default", and the
+ * resolution is what lets a caller tell that apart from a real profile.
  */
-export declare function getPerceptualProfile(personaName: string, accessibilityTraits?: {
+export declare function resolvePerceptualProfile(personaName: string, accessibilityTraits?: {
     motorControl?: number;
     tremor?: boolean;
     visionLevel?: number;
@@ -72,7 +94,9 @@ export declare function getPerceptualProfile(personaName: string, accessibilityT
     processingSpeed?: number;
     attentionSpan?: number;
     fatigueSusceptibility?: number;
-}): PerceptualProfile;
+}): ResolvedPerceptualProfile;
+/** `resolvePerceptualProfile` without the resolution. */
+export declare function getPerceptualProfile(personaName: string, accessibilityTraits?: Parameters<typeof resolvePerceptualProfile>[1]): PerceptualProfile;
 /**
  * Apply persona-weighted barrier scoring.
  *

package/dist/visual/perceptual-transport.d.ts.map

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