writetrack 0.6.0 → 0.7.0

package/dist/esm/viz.d.ts

@@ -0,0 +1,360 @@
+import { W as WriteTrackDataSchema } from './index-ChEZuqzG.js';
+import { S as SessionAnalysis, a as SessionReport, d as IntegrityProof } from './analysis-types-CZ2xI-JI.js';
+
+/**
+ * BaseChart — abstract web component base class for WriteTrack visualizations.
+ *
+ * Handles Shadow DOM creation, CSS token injection, data management,
+ * resize observation, and provides an abstract render() hook for subclasses.
+ */
+declare abstract class BaseChart<T = unknown> extends HTMLElement {
+    /** Override in subclasses to set the custom element tag name */
+    static tagName: string;
+    protected shadow: ShadowRoot;
+    protected container: HTMLDivElement;
+    protected _data: T | null;
+    private _resizeObserver;
+    private _resizeRaf;
+    private _themeObserver;
+    private _initialResize;
+    private _rendered;
+    private _internalTheme;
+    static get observedAttributes(): string[];
+    constructor();
+    /** Override in subclasses to provide component-specific CSS */
+    protected getStylesheet(): string;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+    /** Set session data and trigger a render */
+    setData(data: T): void;
+    /** Get the current data */
+    getData(): T | null;
+    /** Whether the last render() produced visible content */
+    get hasRendered(): boolean;
+    /** Replace the chart container content with new element(s) */
+    protected replaceChart(...elements: (Node | string)[]): void;
+    /** Show an empty-state message when there's no renderable data */
+    protected showEmptyState(message?: string): void;
+    /** Tear down observers and clear the container */
+    destroy(): void;
+    /** Called on container resize. Override in subclasses that shouldn't full re-render. */
+    protected onResize(): void;
+    /** Subclasses implement this to draw their visualization */
+    protected abstract render(): void;
+    /** Register the custom element if not already defined */
+    static register(this: {
+        tagName: string;
+        new (): HTMLElement;
+    }): void;
+    /**
+     * Sync theme attribute from nearest ancestor with data-theme.
+     * Workaround for :host-context() not being supported in Firefox.
+     */
+    private _syncThemeFromAncestors;
+}
+
+/**
+ * Sparkline — compact typing speed chart using Observable Plot.
+ *
+ * Renders a minimal line chart (no axes, no cursor, no legend)
+ * showing rolling characters-per-minute derived from keydown flightTimes.
+ */
+
+/**
+ * Extract [timestamps[], speeds[]] from WriteTrack session data.
+ *
+ * - Filters keydown events with flightTime > 0
+ * - Computes rolling CPM (characters per minute) over a sliding window
+ * - Returns seconds-from-start on the X axis and CPM on the Y axis
+ */
+declare function extractSeries(data: WriteTrackDataSchema): [number[], number[]];
+declare class Sparkline extends BaseChart<WriteTrackDataSchema> {
+    static tagName: string;
+    connectedCallback(): void;
+    protected render(): void;
+    /**
+     * Programmatic factory: create a Sparkline, append it to a container,
+     * and set its data.
+     */
+    static create(container: HTMLElement, data: WriteTrackDataSchema): Sparkline;
+}
+
+/**
+ * SpeedTimeline — typing speed over time chart.
+ *
+ * Renders a line+area chart showing characters-per-minute from the
+ * WASM analysis pipeline's speedTimeline time series.
+ */
+
+interface SpeedPoint {
+    time: number;
+    speed: number;
+}
+/** Extract speed timeline data from analysis, converting ms to seconds. */
+declare function extractSpeedData(analysis: SessionAnalysis): SpeedPoint[];
+declare class SpeedTimeline extends BaseChart<SessionAnalysis> {
+    static tagName: string;
+    protected render(): void;
+}
+
+/**
+ * CompositionTimeline — session activity segments over time.
+ *
+ * Shows typing/paste/pause/tabAway segments as colored horizontal bars
+ * and paste events as dots scaled by character count.
+ */
+
+declare const SEGMENT_COLORS: Record<string, string>;
+interface SegmentDatum {
+    start: number;
+    end: number;
+    type: string;
+    color: string;
+}
+interface PasteDatum {
+    time: number;
+    chars: number;
+    source: string;
+}
+/** Extract activity segments from analysis, converting ms to seconds. */
+declare function extractSegments(analysis: SessionAnalysis): SegmentDatum[];
+/** Extract paste event markers from analysis. */
+declare function extractPasteMarkers(analysis: SessionAnalysis): PasteDatum[];
+declare class CompositionTimeline extends BaseChart<SessionAnalysis> {
+    static tagName: string;
+    protected render(): void;
+}
+
+/**
+ * RhythmHeatmap — dwell time vs flight time scatter plot.
+ *
+ * Shows the distribution of keystroke rhythm as a dot cloud,
+ * revealing clusters that indicate typing style (hunt-and-peck vs touch typing).
+ */
+
+interface RhythmPoint {
+    dwell: number;
+    flight: number;
+}
+/** Extract paired (dwell, flight) data points from timing series. */
+declare function extractRhythmPairs(analysis: SessionAnalysis): RhythmPoint[];
+declare class RhythmHeatmap extends BaseChart<SessionAnalysis> {
+    static tagName: string;
+    protected render(): void;
+}
+
+/**
+ * PauseDistribution — histogram of pause durations.
+ *
+ * Shows the distribution of typing pauses using pre-binned data
+ * from the WASM analysis pipeline.
+ */
+
+interface PauseBin {
+    start: number;
+    end: number;
+    count: number;
+}
+/** Extract pre-binned pause histogram data from analysis. */
+declare function extractPauseHistogram(analysis: SessionAnalysis): PauseBin[];
+declare class PauseDistribution extends BaseChart<SessionAnalysis> {
+    static tagName: string;
+    protected render(): void;
+}
+
+/**
+ * DocumentGrowth — cumulative character count over time.
+ *
+ * Vertical jumps indicate paste/cut events. Slope indicates typing speed.
+ * Consumes raw WriteTrackDataSchema (not WASM analysis output).
+ */
+
+interface GrowthPoint {
+    time: number;
+    chars: number;
+    isPaste: boolean;
+    isCut: boolean;
+    pasteLength?: number;
+    cutLength?: number;
+}
+/** Extract cumulative character growth from raw events. */
+declare function extractGrowthData(data: WriteTrackDataSchema): GrowthPoint[];
+declare class DocumentGrowth extends BaseChart<WriteTrackDataSchema> {
+    static tagName: string;
+    protected render(): void;
+}
+
+/**
+ * DocumentRibbon — keystroke ribbon colored by inter-key gap.
+ *
+ * Each bar represents one keystroke. Yellow = short gaps (fast), red = long gaps (slow).
+ * Consumes raw WriteTrackDataSchema (not WASM analysis output).
+ */
+
+interface RibbonDatum {
+    start: number;
+    end: number;
+    flight: number;
+}
+/** Extract ribbon data from raw keydown events. */
+declare function extractRibbonData(data: WriteTrackDataSchema): RibbonDatum[];
+declare class DocumentRibbon extends BaseChart<WriteTrackDataSchema> {
+    static tagName: string;
+    protected render(): void;
+}
+
+/**
+ * EditWaterfall — cursor position over time.
+ *
+ * Diagonal lines = sequential typing. Jumps = navigation.
+ * Cyan dots = paste events, orange dots = cut events. Y-axis reversed so position 0 is at top.
+ * Consumes raw WriteTrackDataSchema (not WASM analysis output).
+ */
+
+interface WaterfallPoint {
+    time: number;
+    position: number;
+}
+interface WaterfallData {
+    keystrokes: WaterfallPoint[];
+    pastes: WaterfallPoint[];
+    cuts: WaterfallPoint[];
+}
+/** Extract cursor position data from raw events. */
+declare function extractWaterfallData(data: WriteTrackDataSchema): WaterfallData;
+declare class EditWaterfall extends BaseChart<WriteTrackDataSchema> {
+    static tagName: string;
+    protected render(): void;
+}
+
+/**
+ * CorrectionsBubble — edit run visualization.
+ *
+ * Green bubbles = insertions, red = deletions, cyan = paste, orange = cut.
+ * Size = log2(character count). Consecutive same-type actions are grouped.
+ * Consumes raw WriteTrackDataSchema (not WASM analysis output).
+ */
+
+type EditType = 'insert' | 'delete' | 'paste' | 'cut';
+interface BubbleDatum {
+    time: number;
+    chars: number;
+    type: EditType;
+    size: number;
+}
+/** Group consecutive keystrokes into edit runs and add paste/cut events. */
+declare function extractCorrectionBubbles(data: WriteTrackDataSchema): BubbleDatum[];
+declare class CorrectionsBubble extends BaseChart<WriteTrackDataSchema> {
+    static tagName: string;
+    protected render(): void;
+}
+
+declare class WtScorecard extends BaseChart<SessionReport> {
+    static tagName: string;
+    private _activeDetail;
+    constructor();
+    /**
+     * Override onResize to only re-render charts instead of full re-render.
+     * A full re-render replaces container content → changes height →
+     * triggers ResizeObserver again → infinite loop.
+     */
+    protected onResize(): void;
+    protected getStylesheet(): string;
+    /** Override to handle theme changes without full re-render. */
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    protected render(): void;
+    private buildHeader;
+    private buildSummary;
+    private buildTierLabel;
+    private buildGrid;
+    private buildCell;
+    private buildCellMetrics;
+    private buildDetailPanel;
+    private selectCell;
+    private populateDetail;
+    private closeDetail;
+    private expandPanel;
+    private collapsePanel;
+    private getIndicatorCode;
+    private getComputedColors;
+    private getChartWidth;
+    private plotOpts;
+    private plotCategory;
+    private renderAllCharts;
+    private rerenderAllCharts;
+    private plotContentOrigin;
+    private plotTimingAuthenticity;
+    private plotRevisionBehavior;
+    private plotSessionContinuity;
+    private plotPhysicalPlausibility;
+    private plotTemporalPatterns;
+}
+
+interface IntegrityFooterData {
+    integrity: IntegrityProof;
+    outputSignature: string;
+    sessionId: string;
+}
+declare class IntegrityFooter extends BaseChart<IntegrityFooterData> {
+    static tagName: string;
+    protected getStylesheet(): string;
+    protected render(): void;
+    private renderQr;
+}
+
+/**
+ * Scorecard text generation — pass/flag classification, category names,
+ * summary generators, chart captions, and metric annotations.
+ *
+ * Pure functions with no DOM dependency. Used by scorecard components
+ * to generate explanatory text from SessionAnalysis data.
+ */
+declare function isPass(code: string): boolean;
+declare function getStatus(code: string | undefined): 'pass' | 'flag' | 'unknown';
+/** Display names for SessionAnalysis category fields. */
+declare const CATEGORY_NAMES: Record<string, string>;
+/** All 6 analysis category keys in display order. */
+declare const CATEGORY_KEYS: readonly ["contentOrigin", "timingAuthenticity", "revisionBehavior", "sessionContinuity", "physicalPlausibility", "temporalPatterns"];
+type CategoryKey = (typeof CATEGORY_KEYS)[number];
+/** Tier 1 categories are expanded by default. */
+declare const TIER1_CATEGORIES: CategoryKey[];
+/** Tier 2 categories are collapsed by default. */
+declare const TIER2_CATEGORIES: CategoryKey[];
+
+/** Generate a plain-English section summary from the indicator code + analysis data. */
+declare function generateSummary(category: string, analysis: SessionAnalysis): string;
+/** Return a chart caption for the given category, or null if no chart. */
+declare function generateCaption(category: string): string | null;
+/** A single metric for display in the metric grid. */
+interface ScorecardMetric {
+    label: string;
+    value: string;
+    flagged: boolean;
+}
+/**
+ * Extract displayable metrics for a given category from analysis data.
+ *
+ * Note: timing metrics use periodicity + entropy rather than WPM + variance
+ * because TimingAuthenticityAnalysis doesn't include WPM — those fields are
+ * directly available and diagnostically meaningful for automation detection.
+ */
+declare function getMetrics(category: string, analysis: SessionAnalysis): ScorecardMetric[];
+/** Format milliseconds to human-readable duration. */
+declare function formatDuration(ms: number): string;
+
+interface GlossaryEntry {
+    definition: string;
+    docsPath?: string;
+}
+declare const GLOSSARY: Record<string, GlossaryEntry>;
+/**
+ * Wrap known glossary terms in HTML with <abbr> elements containing
+ * a title tooltip. Terms with a docsPath are additionally wrapped
+ * in an <a> link (Amendment #3).
+ *
+ * Terms are matched case-insensitively.
+ */
+declare function wrapTerms(text: string, baseUrl?: string): string;
+
+export { BaseChart, type BubbleDatum, CATEGORY_NAMES, type CategoryKey, CompositionTimeline, CorrectionsBubble, DocumentGrowth, DocumentRibbon, type EditType, EditWaterfall, GLOSSARY, type GlossaryEntry, type GrowthPoint, IntegrityFooter, type PasteDatum, type PauseBin, PauseDistribution, RhythmHeatmap, type RhythmPoint, type RibbonDatum, SEGMENT_COLORS, type ScorecardMetric, type SegmentDatum, Sparkline, type SpeedPoint, SpeedTimeline, TIER1_CATEGORIES, TIER2_CATEGORIES, type WaterfallData, type WaterfallPoint, WtScorecard, extractCorrectionBubbles, extractGrowthData, extractPasteMarkers, extractPauseHistogram, extractRhythmPairs, extractRibbonData, extractSegments, extractSeries, extractSpeedData, extractWaterfallData, formatDuration, generateCaption, generateSummary, getMetrics, getStatus, isPass, wrapTerms };