@willwade/aac-processors 0.3.0 → 0.3.2

package/dist/processors/gotalkNowProcessor.js

@@ -41,6 +41,7 @@ function buildSemanticAction(rawButton, pageId, buttonIndex) {
     const actionData = rawButton.ActionData || {};
     const label = rawButton.ButtonText ?? '';
     const ttsText = actionData.TTSText;
+    const spoken = ttsText && ttsText.length > 0 ? ttsText : label;
     switch (buttonType) {
         case 'Jump': {
             const jumpTo = actionData.JumpTo;
@@ -51,7 +52,7 @@ function buildSemanticAction(rawButton, pageId, buttonIndex) {
                     intent: treeStructure_1.AACSemanticIntent.NAVIGATE_TO,
                     targetId: target,
                     platformData: {
-                        gotalkNow: { buttonType: 'Jump', jumpTo },
+                        gotalkNow: { buttonType: 'Jump', jumpTo, jumpBook: actionData.JumpBook },
                     },
                     fallback: { type: 'NAVIGATE', targetPageId: target },
                 },
@@ -59,25 +60,78 @@ function buildSemanticAction(rawButton, pageId, buttonIndex) {
                 targetPageId: target,
             };
         }
-        case 'Audio': {
-            // Audio buttons play a recorded .caf file named <pageId>-<buttonIndex>.caf
+        case 'Audio':
+        case 'Recorded': {
+            // Recorded audio: plays a .caf file named <pageId>-<buttonIndex>.caf.
+            // Recorded buttons may also have TrimStart/TrimEnd for audio trimming.
             const audioLocation = `${pageId}-${buttonIndex}.caf`;
             return {
                 semanticAction: {
                     category: treeStructure_1.AACSemanticCategory.MEDIA,
                     intent: treeStructure_1.AACSemanticIntent.PLAY_SOUND,
                     platformData: {
-                        gotalkNow: { buttonType: 'Audio', audioLocation },
+                        gotalkNow: {
+                            buttonType,
+                            audioLocation,
+                            trimStart: actionData.TrimStart,
+                            trimEnd: actionData.TrimEnd,
+                        },
                     },
                     fallback: { type: 'ACTION' },
                 },
-                message: label,
+                message: spoken,
+            };
+        }
+        case 'URL': {
+            return {
+                semanticAction: {
+                    category: treeStructure_1.AACSemanticCategory.SYSTEM_CONTROL,
+                    intent: treeStructure_1.AACSemanticIntent.WEB_NAVIGATE,
+                    text: actionData.URL,
+                    platformData: {
+                        gotalkNow: {
+                            buttonType: 'URL',
+                            url: actionData.URL,
+                            openInternally: actionData.OpenInternally,
+                        },
+                    },
+                    fallback: { type: 'ACTION' },
+                },
+                message: spoken,
+            };
+        }
+        case 'GoVisual': {
+            return {
+                semanticAction: {
+                    category: treeStructure_1.AACSemanticCategory.SYSTEM_CONTROL,
+                    intent: treeStructure_1.AACSemanticIntent.PLATFORM_SPECIFIC,
+                    platformData: {
+                        gotalkNow: {
+                            buttonType: 'GoVisual',
+                            goVisual: actionData.GoVisual,
+                            goVisualLink: actionData.GoVisualLink,
+                        },
+                    },
+                    fallback: { type: 'ACTION' },
+                },
+                message: spoken,
             };
         }
-        case 'Express':
-        case 'Bookmark':
-        case 'URL':
         case 'Video': {
+            return {
+                semanticAction: {
+                    category: treeStructure_1.AACSemanticCategory.MEDIA,
+                    intent: treeStructure_1.AACSemanticIntent.PLAY_VIDEO,
+                    platformData: {
+                        gotalkNow: { buttonType: 'Video' },
+                    },
+                    fallback: { type: 'ACTION' },
+                },
+                message: spoken,
+            };
+        }
+        case 'Express':
+        case 'Bookmark': {
             return {
                 semanticAction: {
                     category: treeStructure_1.AACSemanticCategory.SYSTEM_CONTROL,
@@ -87,20 +141,19 @@ function buildSemanticAction(rawButton, pageId, buttonIndex) {
                     },
                     fallback: { type: 'ACTION' },
                 },
-                message: ttsText && ttsText.length > 0 ? ttsText : label,
+                message: spoken,
             };
         }
         case 'TTS':
         default: {
-            // When TTSText is empty the visible ButtonText is spoken.
-            const spoken = ttsText && ttsText.length > 0 ? ttsText : label;
+            // Empty/placeholder cells (no ButtonType or no label) get a SPEAK with empty text.
             return {
                 semanticAction: {
                     category: treeStructure_1.AACSemanticCategory.COMMUNICATION,
                     intent: treeStructure_1.AACSemanticIntent.SPEAK_TEXT,
                     text: spoken,
                     platformData: {
-                        gotalkNow: { buttonType: 'TTS' },
+                        gotalkNow: { buttonType: buttonType === 'TTS' ? 'TTS' : 'Empty' },
                     },
                     fallback: { type: 'SPEAK', message: spoken },
                 },
@@ -308,17 +361,39 @@ class GotalkNowProcessor extends baseProcessor_1.BaseProcessor {
                     if (first?.SourceImageName)
                         button.symbolPath = first.SourceImageName;
                 }
-                // Visibility: GoTalk buttons can be disabled.
-                if (rawButton.Enabled === false) {
+                // Visibility: GoTalk buttons can be disabled via either field.
+                if (rawButton.Enabled === false || rawButton.Disabled === true) {
                     button.visibility = 'Disabled';
                 }
-                // Preserve raw style data opaquely for round-trip styling.
+                // Auditory cue (played when scanning/highlighting).
+                if (rawButton.CueType && rawButton.CueType !== 'None') {
+                    const cueText = rawButton.CueData?.TTSText;
+                    if (cueText && cueText.length > 0) {
+                        button.audioDescription = cueText;
+                    }
+                }
+                // Recorded audio reference.
+                const btnType = rawButton.ButtonType;
+                if (btnType === 'Audio' || btnType === 'Recorded') {
+                    button.audioRecording = {
+                        identifier: `${pageId}-${btnIndex}.caf`,
+                    };
+                }
+                // AfterAction: motor-planning "speak and return" behaviour.
+                // AfterAction is an enum (0=stay, 2=..., 50=jump-back) and
+                // AfterActionData has the same shape as ActionData (e.g. {JumpTo: 0}).
+                const afterActionJumpTo = rawButton.AfterActionData?.JumpTo;
+                // Preserve raw style + extended data opaquely for round-trip styling.
                 button.parameters = {
                     ...(button.parameters || {}),
                     __gotalkNow: {
                         buttonType: rawButton.ButtonType,
                         textShadow: rawButton.TextShadow,
                         textCenter: rawButton.TextCenter,
+                        cueType: rawButton.CueType,
+                        afterAction: rawButton.AfterAction,
+                        afterActionJumpTo: afterActionJumpTo !== undefined ? String(afterActionJumpTo) : undefined,
+                        jumpBook: rawButton.ActionData?.JumpBook,
                     },
                 };
                 page._loadButton(button);

package/dist/processors/gridsetProcessor.js

@@ -2963,8 +2963,8 @@ class GridsetProcessor extends baseProcessor_1.BaseProcessor {
                                         cellContent.CaptionAndImage = captionAndImage;
                                     }
                                     const cellData = {
-                                        '@_X': position.x + 1, // Grid3 uses 1-based X coordinates
-                                        '@_Y': position.y + yOffset + 1, // Grid3 uses 1-based Y coordinates with workspace offset
+                                        '@_X': position.x, // Grid 3 coordinates are 0-based (matching loader)
+                                        '@_Y': position.y + yOffset,
                                         '@_ColumnSpan': position.columnSpan,
                                         '@_RowSpan': position.rowSpan,
                                         Content: cellContent,

package/dist/processors/obfProcessor.js

@@ -147,14 +147,21 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
         const pageId = boardData?.id ? String(boardData.id) : _boardPath?.split(/[/\\]/).pop() || '';
         const images = boardData.images;
         const buttons = await Promise.all(sourceButtons.map(async (btn) => {
+            // Resolve load_board.path to a board ID (strip .obf suffix if present).
+            // The OBF spec says load_board.path is a file path, but internally we
+            // store the board ID as targetPageId.
+            const rawPath = btn.load_board?.path;
+            const boardRef = rawPath
+                ? rawPath.replace(/\.obf$/i, '').replace(/\.obz$/i, '')
+                : undefined;
             const semanticAction = btn.load_board
                 ? {
                     category: treeStructure_1.AACSemanticCategory.NAVIGATION,
                     intent: treeStructure_1.AACSemanticIntent.NAVIGATE_TO,
-                    targetId: btn.load_board.path,
+                    targetId: boardRef,
                     fallback: {
                         type: 'NAVIGATE',
-                        targetPageId: btn.load_board.path,
+                        targetPageId: boardRef,
                     },
                 }
                 : {
@@ -202,7 +209,7 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
                 resolvedImageEntry: resolvedImage,
                 parameters: Object.keys(buttonParameters).length > 0 ? buttonParameters : undefined,
                 semanticAction,
-                targetPageId: btn.load_board?.path,
+                targetPageId: boardRef,
                 semantic_id: btn.semantic_id, // Extract semantic_id if present
             });
         }));
@@ -621,7 +628,7 @@ class ObfProcessor extends baseProcessor_1.BaseProcessor {
                     vocalization: button.message || button.label,
                     load_board: button.semanticAction?.intent === treeStructure_1.AACSemanticIntent.NAVIGATE_TO && button.targetPageId
                         ? {
-                            path: button.targetPageId,
+                            path: this.getPageFilename(button.targetPageId, metadata),
                         }
                         : undefined,
                     background_color: button.style?.backgroundColor,

package/dist/utilities/analytics/competence.d.ts

@@ -0,0 +1,281 @@
+/**
+ * Linguistic Competence Metrics
+ *
+ * Privacy-preserving analysis of AAC *spoken output* (phrase history), based on:
+ *   - Niemeijer, Sheldon & Hillary Zisk (2025), "Measuring AAC user linguistic
+ *     competence: A novel approach", AssistiveWare (Communication Matters handout).
+ *   - Frisch, Wade et al. (2026), "It's Complicated: On the Design and Evaluation
+ *     of AI-Powered AAC Interfaces", arXiv:2606.24854.
+ *
+ * DESIGN (read me):
+ *   - **Source-agnostic.** The only input is `{ text, timestampMs }[]`. It does
+ *     not know or care whether the speech history came from Grid 3, Snap,
+ *     TouchChat, OBF/OBFL logs, or anything else. See `historyEntriesToCompetence*
+ *     Utterances` (in history.ts) to adapt any `HistoryEntry[]` source.
+ *   - **Language-agnostic core.** This module contains NO word lists. Language-
+ *     specific resources (a closed-class word set, an inflection classifier) are
+ *     INJECTED via `LanguageResources`. When a resource is missing for a
+ *     language, the affected measure is reported as `unavailable` with a reason
+ *     and a warning is raised — never silently wrong.
+ *   - **Pure / no I/O.** No filesystem, no platform APIs. Runs anywhere (browser
+ *     included) and emits only aggregate statistics (never the raw text).
+ *
+ * The four dimensions of linguistic competence (Light, 1989) and the measures we
+ * use for each, following the AssistiveWare findings:
+ *
+ *   Semantic      -> MATTR-30 lexical diversity             (always available)
+ *   Syntactic     -> preposition/conjunction diversity        (needs closedClassWords)
+ *   Morphological -> inflected-form diversity                 (needs classifyInflection)
+ *   Phonological  -> proportion of unique words in a dictionary (needs a dictionary)
+ *
+ * All diversity measures use 30-word moving-average windows (Covington & McFall,
+ * 2010), making them sample-length independent and usable for the tiny, highly
+ * variable samples typical of AAC. MLU is intentionally NOT a headline (it
+ * conflates linguistic/operational/strategic/social competence in AAC); it is
+ * reported only as a distribution.
+ */
+/** A single spoken utterance with a production timestamp (epoch ms). */
+export interface CompetenceUtterance {
+    text: string;
+    timestampMs: number;
+}
+/** A tokenised word stream produced in chronological order. */
+export type WordStream = string[];
+/** Coarse inflection category used by the (injected) morphology classifier. */
+export type InflectionCategory = 'base' | 'plural' | 'possessive' | 'past' | 'progressive' | 'comparative' | 'superlative' | 'adverb';
+/**
+ * Language-specific resources, injected by the caller. Providing none leaves the
+ * language-specific measures unavailable (with explicit warnings) — the semantic
+ * measure still works for any language.
+ */
+export interface LanguageResources {
+    /** Closed-class words (prepositions, conjunctions, ...) for syntactic diversity. */
+    closedClassWords?: Set<string>;
+    /** Maps a lowercased word to an inflection category for morphological diversity. */
+    classifyInflection?: (word: string) => InflectionCategory;
+}
+export interface DiversityOptions {
+    /** Moving-average window size in words. The papers use 30. */
+    windowSize?: number;
+    /** Closed-class word set (for the syntactic measure). */
+    closedClassWords?: Set<string>;
+    /** Inflection classifier (for the morphological measure). */
+    classifyInflection?: (word: string) => InflectionCategory;
+}
+export interface DiversityResult {
+    /** Median of the per-window values (the headline figure, per the paper). */
+    median: number | null;
+    mean: number | null;
+    /** Number of windows that contributed a value (after any skipping). */
+    nWindows: number;
+    /** The window size used. */
+    windowSize: number;
+    /** Present when the measure could not be computed (e.g. missing language data). */
+    unavailable?: string;
+}
+/**
+ * Tokenise raw text into a lowercased word stream.
+ * Keeps intra-word apostrophes (don't, children's) but drops leading/trailing
+ * punctuation and pure whitespace. Accented characters are preserved (\p{L}).
+ */
+export declare function tokenize(text: string): WordStream;
+/**
+ * Moving-Average Type-Token Ratio (Covington & McFall, 2010).
+ *
+ * Slides a fixed-size window across the word stream and computes the TTR for
+ * each window. The median across windows is sample-length independent, which is
+ * exactly why it is preferred over plain TTR for highly variable AAC samples.
+ */
+export declare function movingAverageTTR(words: WordStream, windowSize?: number): DiversityResult;
+/** Convenience: MATTR-30 lexical diversity (the semantic headline). */
+export declare function lexicalDiversity(words: WordStream, windowSize?: number): DiversityResult;
+/**
+ * Closed-class diversity (generalises AssistiveWare's MA-UPC-TWR-30).
+ *
+ * For each window, compute the type-token ratio restricted to the supplied
+ * closed-class words (prepositions + conjunctions in the original paper). Windows
+ * containing none are skipped. The caller supplies the set via
+ * `closedClassWords`, so this works for any language without hardcoding here.
+ */
+export declare function syntacticDiversity(words: WordStream, options?: DiversityOptions): DiversityResult;
+/**
+ * Morphological diversity (proxy for MA-UMORPH-TLWR-30).
+ *
+ * Within each window, words the supplied classifier marks as inflected (any
+ * category other than "base") contribute their surface forms to a type-token
+ * ratio. Windows with no inflected words are skipped. The classifier is injected
+ * (`classifyInflection`) so the heuristic lives with the caller, per language.
+ *
+ * Caveat (per AssistiveWare): for symbol-supported AAC, pre-stored morphology
+ * buttons ("finished", "is", ...) heavily affect this measure — interpret trends
+ * rather than absolutes.
+ */
+export declare function morphologicalDiversity(words: WordStream, options?: DiversityOptions): DiversityResult;
+/**
+ * Proportion of unique alphabetic words present in the supplied dictionary.
+ * Unique words only, so it is not skewed by repetition or repeated misspellings.
+ * Returns null (unavailable) if no dictionary is provided.
+ */
+export declare function spellingValidity(words: WordStream, dictionary?: Set<string>): number | null;
+export interface DistributionStats {
+    median: number | null;
+    mean: number | null;
+    p25: number | null;
+    p75: number | null;
+    n: number;
+}
+export interface ActivityStats {
+    utterances: number;
+    words: number;
+    /** Distinct tokens — vocabulary breadth (count only, never the words). */
+    uniqueWords: number;
+    activeDays: number;
+    wordsPerUtterance: DistributionStats;
+}
+/** Compute engagement/activity stats for a set of utterances. */
+export declare function summarizeActivity(utterances: CompetenceUtterance[]): ActivityStats;
+export interface MonthBin {
+    /** Calendar month in local time, "YYYY-MM". */
+    month: string;
+    utterances: number;
+    words: number;
+    uniqueWords: number;
+    activeDays: number;
+    wordsPerUtterance: DistributionStats;
+    /** Semantic — the headline measure. */
+    lexicalDiversity: DiversityResult;
+    /** Syntactic. null/unavailable when no closed-class data for the language. */
+    syntacticDiversity: DiversityResult;
+    /** Morphological (proxy). null/unavailable when no classifier for the language. */
+    morphologicalDiversity: DiversityResult;
+    /** Phonological — only when a dictionary is supplied. */
+    spellingValidity: number | null;
+    /** True when the month has too little data to trust the diversity figures. */
+    suppressed: boolean;
+    suppressReason: string | null;
+}
+export interface TrendResult {
+    metric: string;
+    /** Slope of the weighted linear regression, in metric units per month. */
+    slopePerMonth: number | null;
+    firstHalf: number | null;
+    secondHalf: number | null;
+    /** secondHalf - firstHalf. */
+    delta: number | null;
+    direction: 'up' | 'down' | 'flat' | 'unknown';
+}
+export interface DimensionSupport {
+    available: boolean;
+    reason?: string;
+}
+export interface PagesetSummary {
+    label: string;
+    gridsetIncluded: boolean;
+    analysisVersion?: string;
+    totalBoards: number;
+    totalButtons: number;
+    totalWords: number;
+    grid: {
+        rows: number;
+        columns: number;
+    };
+    effort: DistributionStats;
+    hasDynamicPrediction: boolean;
+    spellingEffort: {
+        base: number | null;
+        perLetter: number | null;
+    };
+    error?: string;
+}
+export interface UserSettingsSummary {
+    startupGridSet: string | null;
+    onlineAiToolsOptIn: boolean | null;
+    accessMethods: string[];
+    personalisation: {
+        pronunciations: number;
+        capitalisations: number;
+        abbreviationExpansions: number;
+        smallWords: number;
+    };
+}
+export interface CompetenceReport {
+    schema: string;
+    generatedAt: string;
+    privacy: {
+        rawUtterancesIncluded: boolean;
+        wordListsIncluded: boolean;
+        fringeWordFrequencyIncluded: boolean;
+        minAggregationWindowDays: number;
+        notes: string[];
+    };
+    source: {
+        platform: string;
+        langCode?: string;
+        userLabel?: string;
+        dbPathIncluded: boolean;
+    };
+    config: {
+        months: number;
+        windowSize: number;
+        lang: string;
+        minWordsPerMonth: number;
+        dictionaryProvided: boolean;
+    };
+    overall: {
+        windowStart: string;
+        windowEnd: string;
+        totalUtterances: number;
+        totalWords: number;
+        monthsCovered: number;
+        monthsSuppressed: number;
+    };
+    timeline: MonthBin[];
+    trend: TrendResult;
+    /** Per-dimension availability for the detected language (no silent degradation). */
+    support: {
+        lang: string;
+        semantic: DimensionSupport;
+        syntactic: DimensionSupport;
+        morphological: DimensionSupport;
+        phonological: DimensionSupport;
+    };
+    /** Human-readable notes about anything skipped or approximate. */
+    warnings: string[];
+    /** Structural metrics for the user's default gridset (null if unavailable). */
+    pageset?: PagesetSummary | null;
+    /** System-configuration context (access method, AI opt-in, startup gridset). */
+    userSettings?: UserSettingsSummary | null;
+}
+export interface TimelineOptions {
+    /** How many trailing months to analyse. Default 12. */
+    months?: number;
+    /** Moving-average window. Default 30. */
+    windowSize?: number;
+    /** Language code. Default "en". Used for reporting only. */
+    lang?: string;
+    /** Months with fewer than this many words are flagged suppressed. Default 150. */
+    minWordsPerMonth?: number;
+    /** Optional dictionary Set for the spelling measure. */
+    dictionary?: Set<string>;
+    /** Language-specific resources (closed-class words, inflection classifier). */
+    resources?: LanguageResources;
+    /** Epoch ms for "now". Defaults to Date.now(). Mainly for tests. */
+    now?: number;
+    /** Platform label for the report. Default "Grid3". */
+    platform?: string;
+    userLabel?: string;
+    langCode?: string;
+    dbPathIncluded?: boolean;
+}
+/**
+ * Analyse a corpus of utterances as a longitudinal competence report.
+ *
+ * Utterances are filtered to the trailing `months` window, binned by calendar
+ * month, and each bin is scored on the four competence dimensions plus activity.
+ * Language-specific measures require matching `resources`; missing resources are
+ * reported under `support` and `warnings` rather than silently dropped.
+ *
+ * No raw text, word list, or fringe-vocabulary frequency is included in the
+ * returned report — only aggregate statistics.
+ */
+export declare function analyzeTimeline(utterances: CompetenceUtterance[], options?: TimelineOptions): CompetenceReport;