The Interface Codex

Opens the operating system's native multi-file selection picker filtered to .md documents, reads selected files asynchronously, and populates the workspace buffer.

1. Clicking #fileInputLabel triggers the hidden <input type="file" multiple accept=".md"> element.
2. On change, files are mapped to an array of Promises reading text via file.text().
3. addFilesAndDisplay() receives {name, content} objects, rejects duplicates already existing in state.loadedFiles, and selects an initial document to render.
4. Clears the input's value so selecting the same file again triggers a fresh change event.

Standard HTML5 file inputs provide universal cross-browser compatibility across all desktop and mobile platforms without requiring experimental browser permissions.

Prompts the user to select an entire directory tree, traverses all nested subdirectories, and loads every .md document found.

1. Feature-detects window.showDirectoryPicker; if unsupported, alerts the user to use the file picker or switch to Chromium.
2. Calls window.showDirectoryPicker(), obtaining a root FileSystemDirectoryHandle.
3. An asynchronous recursive generator scan(dirHandle) traverses directory entries using for await (const entry of dirHandle.values()).
4. For each file ending in .md, reads content via await entry.getFile().text() and streams the file into addFilesAndDisplay().

Allows instant exploration of large Obsidian vaults, documentation repositories, and note collections with a single click, skipping non-markdown assets automatically.

Renders the total count of loaded Markdown documents in the retro status footer (e.g. FILES: 42).

Whenever files are added, restored, or restarted, updateUI() executes elements.fileCountDisplay.textContent = `FILES: ${state.loadedFiles.length}`.

Provides immediate peripheral feedback to the user on the scale of their active workspace corpus.

Prevents duplicate documents from cluttering the workspace and ensures only valid markdown files enter the buffer.

1. Filters incoming file objects by comparing filename and text content against existing entries in state.loadedFiles.
2. If a file matches both name and content, it is skipped.
3. Updates the status log with counts of added files and skipped duplicates (e.g. "Loaded 5 files (2 duplicates skipped).").

Prevents memory waste and duplicate search results when users scan overlapping folders or re-select files.

Displays the previous document visited in the navigation history stack. Automatically disabled when at the beginning of the history.

Decrements state.historyIndex, retrieves the file index from state.history, and invokes displayFile(fileIndex). updateUI() sets #prevBtn.disabled = (state.historyIndex <= 0).

Maintains intuitive browser-like back navigation without altering the underlying document array order.

Navigates forward through viewed documents. If already at the tip of history, randomly picks a new unread file from the loaded collection.

If state.historyIndex < state.history.length - 1, increments historyIndex. Otherwise, randomly picks an index from state.loadedFiles, appends it to state.history, and renders the document.

Combines predictable forward history navigation with serendipitous serendipity-driven reading exploration.

Selects a random document from the workspace to initiate the reading experience when files are freshly imported.

Generates a random integer index between 0 and state.loadedFiles.length - 1, seeds the history stack with that index, and displays the document.

Avoids the monotony of always opening the first alphabetical document (often an index or license file) when ingesting large vaults.

The central terminal reading viewport where rendered Markdown documents and subsequent AI dialogue responses appear.

Constructed as an accessible <main> element styled with custom monospace typography. On file change, its inner HTML is replaced with the newly sanitized document content, followed by initial chat history seeding.

Provides a clean, scrollable, high-contrast reading environment that isolates document presentation from application controls.

Prompts the local model to distill the current document into a high-level summary highlighting key themes and arguments.

1. Locks UI controls and activates the header loader spinner.
2. Dispatches the file text paired with the prompt: "Provide a concise summary of the following document. Highlight key points and main ideas."
3. Captures the model response, verifies view invariance (isStale()), parses Markdown via DOMPurify, and appends the result to the display viewport.

Allows rapid comprehension of long technical articles, transcripts, or notes without leaving the document context.

Generates 3 to 5 probing questions regarding the document's content and formats each question as an interactive button.

Asks the model to suggest questions a curious reader might ask. Parses lines beginning with numbers (e.g. 1. Why...) into interactive <button class="suggested-question-btn"> elements with bound click listeners.

Promotes deeper engagement with texts by highlighting nuances or unexplored ramifications of the author's arguments.

Captures Enter keypresses or button clicks to trigger follow-up questions without reloading the page.

Binds a submit listener that prevents default navigation, checks if an answer is already in flight (state.isAsking), extracts trimmed text, and initiates the query.

Semantic form markup provides native keyboard submission handling (Enter to submit) while preserving single-page execution.

Receives arbitrary user questions concerning the currently displayed file.

Disabled when no files are loaded or while an inference request is in progress. Clears value on submit and automatically re-focuses when the model response completes.

Enables natural language follow-up conversations directly within the console without requiring modal dialogs.

Visual button to submit the question typed into the Ask Input field.

Configured with type="submit" inside #askForm. Synchronously disabled whenever #askInput is disabled.

Provides an explicit touch- and mouse-accessible target alongside keyboard Enter submission.

Clicking any generated suggestion immediately dispatches that exact question to the model.

Constructed dynamically by suggestQuestionsBtn. Each button has a click listener invoking askAboutCurrentFile(questionText), adding the query to the conversation stack.

Eliminates the friction of manually copying and pasting suggested questions into the input bar.

Synthesizes an answer to a single question across all loaded documents simultaneously, citing sources across files.

1. Calls showInputModal() to capture the query text.
2. Concatenates all documents in state.loadedFiles with clear delimiters (File: <name>).
3. Dispatches the prompt to the local model, captures the response, verifies that the view hasn't been reset (isStale()), and displays the answer under an "Ask All Files" heading.

Acts as an ambient knowledge synthesis engine across disparate personal notes without requiring an external vector database.

Displays an overlay dialog requesting string input from the user with full keyboard navigation (Enter/Escape).

Returns a Promise that unhides #inputModal, sets labels, focuses the input field, and resolves with the entered string on Confirm/Enter or null on Cancel/Escape.

Replaces blocking browser prompt() dialogs with a styled, non-blocking asynchronous interaction that matches the console aesthetic.

Opens the Model Settings modal dialog, pre-populating existing settings and querying available models.

Initializes form fields from state.modelSettings (or defaults), clears error messages, unhides #modelSettingsModal, and invokes fetchAndFillModels().

Gives users immediate visual access to local server configuration without editing text configuration files.

Switches between Ollama's native protocol and the OpenAI-compatible completions format.

Changing selection updates the URL placeholder to the protocol's default (http://localhost:11434 for Ollama, http://localhost:8080/v1 for OpenAI) and refreshes model capability queries.

Provides transparent protocol switching across popular local inference runtimes without manual header configuration.

Specifies the network address of the local model daemon.

Accepts loopback URLs. Validated by isLocalUrl() to ensure requests never leave the machine.

Allows users to bind custom ports (e.g. LM Studio on 1234, vLLM on 8000) while strictly maintaining the Zero-Key localhost perimeter.

Lists available models with disabled states for non-chat embedding models (Roadmap P2-04).

Populated by fillModelSelect(). Capable models are listed first; embedding-only models are disabled and appended at the bottom with visual notices.

Prevents model selection errors and avoids failures caused by calling embedding models for text generation.

Actively queries the configured server URL to fetch newly pulled or loaded models.

Validates the URL with isLocalUrl(), fetches model listings, executes capability probing, and updates the select options.

Users can pull new models in another terminal (e.g. ollama pull phi4) and refresh the list without reloading the web page.

Validates inputs, commits configuration to application state, persists settings to localStorage, and closes the modal.

1. Enforces non-empty URL and selected model.
2. Verifies isLocalUrl(baseUrl); displays an inline error if external.
3. Assigns state.modelSettings = {apiStyle, baseUrl, model}, calls saveSession(), and hides the modal.

Atomic validation ensures that invalid or unsafe configurations can never be committed to runtime state.

Closes the Model Settings modal without modifying existing configuration.

Adds the hidden class to #modelSettingsModal, discarding uncommitted form adjustments.

Provides a safe escape route from configuration dialogs without side effects.

Serializes all loaded files, navigation history, active conversations, and model configurations into localStorage.

Packages {loadedFiles, history, historyIndex, chatHistory, modelSettings} into a JSON string and writes to chidiMdSession. Updates the status log with "Session saved."

Users can close their browser or shut down their workstation and return directly to their exact reading and conversation state.

Wipes all in-memory files, conversations, and history, removes the saved session from localStorage, and resets the console.

Removes chidiMdSession from localStorage, resets state.loadedFiles = [], state.history = [], state.chatHistory = [], increments state.viewId to invalidate pending requests, and resets the UI.

Provides a clean slate for starting a new document reading session without lingering state from previous vaults.

Restores previously saved workspace files and conversation threads on application startup.

Parses the stored JSON payload, re-populates state arrays, restores the last viewed file, purges any legacy secrets, and updates the status log.

Gives the user explicit control over whether to resume prior work or begin fresh.

Rejects restoring the saved session, clears the stored record, and presents a clean start.

Removes chidiMdSession from localStorage, hides the modal, and leaves the console in its default ready state.

Allows users to cleanly discard stale sessions without manually navigating browser developer tools.

Traps browser storage quota exceptions when saving sessions that exceed ~5 MB and alerts the user while leaving prior saves intact.

Wraps localStorage.setItem in a try/catch block. On exception, calculates payload megabytes and logs: "Error: Session is ~X MB; browser storage is full. Your previous save is still kept."

Prevents unhandled crashes and data loss when loading large corpora, preserving previous saves safely.

Sanitizes all HTML generated from Markdown files and model responses before it touches the DOM.

Filters AST HTML output via pinned DOMPurify 3.4.16, stripping inline event handlers (onerror), script elements, and javascript: URI schemes.

Guarantees that untrusted or hostile Markdown documents cannot execute arbitrary code in the user's browser.

Ensures that outbound model requests are only sent to the user's local machine.

Parses the hostname via the standard URL constructor and validates that it matches localhost, 127.0.0.1, [::1], or ends with .localhost.

Prevents data exfiltration and accidental requests to third-party cloud APIs.

Drops responses that arrive after the user has navigated to another document or restarted the session.

Increments state.viewId on document change. When a response resolves, verifies that the active view ID matches the captured view ID. If mismatched, drops output and logs a notice.

Protects conversation integrity from race conditions caused by slow model generation.

Detects and scrubs legacy cloud API keys from sessions created by older versions of the app.

During session restoration, checks for apiKey or geminiChatHistory properties, removes them from state, and re-saves the clean session.

Ensures user secrets are completely evicted from persistent storage in compliance with the Zero-Key Mandate.

Renders real-time feedback on user actions, model generation progress, and system alerts.

Displays standardized status messages (e.g. "SYSTEM LOG: Standby.", "SYSTEM LOG: Answering question...", "SYSTEM LOG: Error: ...").

Provides a consistent, non-intrusive status readout that avoids distracting popup notifications.

Displays an animated spinner in the console header during active model inference or file loading.

Controlled by setLoading(true/false). Unhides the CSS animation when an operation begins and hides it upon completion.

Informs users that the system is processing their request, especially during longer model generations.

Displays the application title and active document filename in retro terminal styling.

Updates on document navigation to display chidi.md // <filename>, resetting to default when no file is active.

Gives users clear, persistent context on which document they are currently viewing.

Serves the application locally with strict Cache-Control: no-cache headers and opens the page in Google Chrome.

Extends Python's http.server.SimpleHTTPRequestHandler to send no-cache headers on all responses, preventing stale browser caching during local development.

Ensures developers always test the latest code modifications without aggressive browser caching issues.

Scans documentation for broken links, duplicate decisions, invalid roadmap checkboxes, and unfulfilled placeholders.

Uses regular expressions to validate relative paths, decision references (D-NNN), roadmap IDs (P#-##), and handoff session logs across all documentation files.

Maintains absolute consistency between codebase changes and documentation records across development sessions.

Audits index.html and main.js to confirm that all DOM element references match and sanitization rules are respected.

Extracts all IDs from index.html and verifies that every document.getElementById() call targets a valid, uniquely defined ID. Rejects un-sanitized innerHTML assignments and unpinned CDN scripts.

Catches missing elements, typos, and security regressions before code reaches staging or production.

Runs 34 automated smoke tests in headless Chromium and Firefox, validating all key user flows offline.

Uses Playwright to boot the app with local SRI-pinned libraries, mock model servers, test XSS sanitization, verify storage quota handling, and exercise concurrent request guards.

Provides conclusive, observed proof of feature correctness and security enforcement across multiple browser engines.