Global

When true, pauses a running timer automatically when the browser tab becomes hidden (visibilitychange → document.hidden). The pause is silent; the event is recorded in the console log via wlLog.info but no UI notification appears. Set to false to disable. Override in 00-config.local.js.

Maps raw Outlook account keys (lowercase) to human-readable labels shown in the calendar strip. The PowerShell server sends the DisplayName field; this map handles display-name variants, email domains, and substring matches.

Add an entry for each calendar account you want labelled; unknown accounts are shown without a label badge.

localStorage key prefix for section open/collapsed state.

Daily tracking goal in milliseconds. The header pace bar fills proportionally as today's logged time approaches this value. Default: 7 hours 30 minutes. Override in 00-config.local.js.

Location id used for any day that has no stored value.

Activity-line SVG icon for the section header (Lucide-style, 24×24 viewBox, 1.5px stroke).

Base URL for Jira ticket links. Ticket keys found in task names are converted to <a href="${JIRA_BASE}/${key}"> anchors. Set to '' to disable link generation. Override in src/js/00-config.local.js (gitignored) — copy from src/js/00-config.local.example.js and set your real instance URL.

Signifier shortcode map for quick-capture inline tokens. Maps !<shortcode> tokens to signifier values used on entry objects. Unmapped tokens are left in the text unchanged.

localStorage key for the time-block array.

Maps each view to the DOM id of the pane that hosts it.

21:00 in minutes from midnight — right edge of the day-overview strip.

07:00 in minutes from midnight — left edge of the day-overview strip.

Ordered list of view ids — drives the segmented control and keyboard nav.

Display labels for the segmented control. Static so we avoid recomputing on every render.

Latitude of the work location (decimal degrees). Default used when the server is not running; normally set via config.local.ps1.

Longitude of the work location (decimal degrees). Default used when the server is not running; normally set via config.local.ps1.

Display name for the work location shown next to the weather widget. Default used when the server is not running; normally set via config.local.ps1.

Work-location presets keyed by their stored id. Each entry carries the emoji and human-readable label shown in the date-nav header. The first key is the default applied to any day with no stored location.

Shared drag-state for board column DnD (set by dragstart, read by drop).

The log entry that was just stopped. Kept so the Undo action can recover it and the stopped panel can display the correct task name / session range.

Active category chip selection. Serves two purposes:

• filters the task list to show only that category, and
• tags any ad-hoc log entry created via "Log without tracking". null means "All" (no filter; entry falls back to selectedTag).

Controls whether the epic manage row (rename/delete/add) is expanded.

Whether the Done column's older-history expander is open.

True while the focus/emergency overlay is visible.

Plan task list — each item: { id, text, status, tag, date, [billable], [notionUrl], [emoji], [checkpoints], [parentId], [priority] }

Whether the WIP-over warning banner has been dismissed this render cycle.

Binds open/close/select keyboard and pointer events on a .hero-cat-wrap element.

Cancels the auto-dismiss timer (called by Undo / Done buttons).

Updates the active entry's category, persists, and re-renders.

Updates the idle panel: logged-today total and last-session time.

Updates the paused panel with the frozen clock and task details.

Updates the running panel: category dot + task title + started-at sub-line.

Updates the stopped panel with the session summary.

Dismiss the stopped confirmation panel immediately (same as auto-dismiss).

Handles the "▶ Start tracking" button. Uses the composer input if it has text; otherwise focuses the plan input.

Undo the just-stopped entry: remove it from entries and optionally restart the timer if the entry had been running (i.e. it had no prior tsEnd).

Returns "↳ last note X ago" text for the most recent session-note on an entry, or an empty string when no session notes have been added yet.

Builds the recent-task chip strip in the idle panel. Shows up to 3 distinct recent entries with their category dot.

Returns the number of distinct time entries today for the same task text.

Fills a category display cell with the dot + label (and optional caret/picker).

Starts tracking from a recent-chip click. Re-uses the existing entry (no duplicate) and starts the timer.

Starts or switches to a task from the quick-capture list. If the row is already the active timer, just closes the modal. For plan-task rows a fresh time entry is created.

Attaches click listeners to task-row action buttons and their parent rows. Separated from rendering so each has a single responsibility.

Collects and deduplicates the three task groups for the current filter state. Pure data function — performs no DOM operations.

Handles the "Log without tracking" footer button and Enter keypress.

Parses inline shorthand tokens from the input before creating the entry: #<cat> overrides category, !<sig> sets the signifier, ><date> sets the entry date (today / tomorrow / YYYY-MM-DD / weekday).

• Non-empty text after token stripping → creates a log entry (no timer) and closes.
• Only tokens, no text → refocuses the input so the user adds a description.
• Completely empty input → closes and focuses the ad-hoc row in the time log.

Re-renders all dynamic regions of the quick-capture modal.

Renders the "All" chip plus one chip per category. The active chip is highlighted; clicking a chip filters the task list.

Shows or hides the running strip. When a timer is active the strip displays the current task and elapsed time. When idle the strip is hidden and the pulsing-dot class is removed.

Orchestrates data collection, rendering, and event binding for the task list. Delegates each concern to a single-purpose helper.

Renders colored pill badges below the search input for any recognised inline tokens in the current input value. Hides the preview container when no tokens are active (e.g. on modal open or after the field is cleared).

Starts a 1-second interval to update the elapsed-time label in the running strip.

Clears the running-strip interval.

Renders the task list HTML string from pre-built group data. Receives all inputs as parameters — performs no DOM or module-state reads.

Returns the HTML for one task row in the task list. The action button is opacity-0 and revealed on row hover via CSS.

Updates only the elapsed-time label; called every second by the ticker.

Returns the effective tracked duration (ms) of an active-timer entry, honouring pause state — matches the formula used by renderFlowHeader so the strip bar and Flow-view duration freeze while paused.

Creates a new log entry from the capture input's current value. Optionally starts the timer on the new entry (withTimer = true), in which case any running timer is stopped first and the matching plan task is auto-promoted to "in progress".

Reads the note input, appends a note to logNotes, persists, and re-renders.

Reads the plan-input field and adds a new "todo" task to today's plan. Inherits the currently selected tag and that category's billable default. No-ops if the input is empty.

Adds a work-log task to Notion as a child page under the matching project. The project is looked up server-side by matching the task's category label to a Notion project's Epic field. Uses /api/notion-add-task (Notion REST API, no AI).

Replaces the hours/minutes of a base timestamp with values parsed from a "HH:MM" string, returning the resulting timestamp in milliseconds.

Carries unfinished plan tasks from past days into today — runs once per day (guarded by a localStorage flag). Deduplicates by text, preserving the most recent past status and status-comment history. Checkpoints are carried forward with done reset to false for a fresh day.

Builds the billable toggle button HTML for a task row. Returns empty string for pending/blocked/upcoming tasks where billing is irrelevant.

Makes each rendered board card draggable and wires its dragstart/dragend. Called once per renderPlan() cycle after columns are populated. Static column drop-zone listeners are set up once in initBoardColumnDnD().

Binds all plan list event handlers after each render.

Attaches click and keyboard listeners to all .esig elements after a render.

Builds the parts of the pasteable billable summary from merged billable entries. Categorised tasks are grouped as Category (task1, task2); uncategorised tasks (no tag or other) are listed bare. Order of first appearance is preserved and duplicate task names are de-duplicated.

Determines the next task to transition to and delegates to fetchBridge. If multiple tasks are in-flight the user picks from a list; a single in-progress task is auto-selected; the only remaining task is auto-selected.

Builds a chronologically sorted array of feed items for the Log view. Merges time entries, log notes, and task status comments for the given day.

Item types:

• 'entry' — a time-tracked entry; includes entryId.
• 'note' — a freeform log note; text is wrapped in <em>.
• 'session-note' — a note attached to a running/completed entry; includes parentEntryId. Renderers nest these inside their parent entry row rather than as standalone timeline rows.
• 'task' — a plan-task status comment.

Builds the HTML fragment for a list of session-notes nested under a parent entry row. Returns an empty string when there are no notes.

Resolves a human-readable account label for an Outlook calendar account. The PowerShell server sends the raw DisplayName which may be an email address, a display name, or free-form company text. Tries three strategies in order: exact match, email domain extraction, and substring match.

Computes monthly summary statistics from a flat entries array. Pure: takes its own data dependency, no DOM, no module globals. Excludes entries with no tsEnd (still running) or signifier === 'cancelled'.

Computes open / done / migrated task counts for a given month. Pure. _migrated (programmatic) and signifier === 'migrated' (BuJo marker) both count toward the migrated total.

Counts consecutive days with at least one logged entry, looking backwards from yesterday. Today is excluded so the streak only increments once the day has been completed.

Calls the Claude API with a Notion MCP server attached, via the local proxy at /api/notion-ai (API keys never exposed to the browser). Used for the URL-bookmarking form — task imports use addTaskToNotion instead.

Duplicates the task into next month (first day) and marks original as migrated.

Checks all of today's time blocks and acts on ones that have just become active:

• Meeting blocks: auto-starts a log entry and timer at the scheduled start time.
• Task blocks: prompts the user to switch/start within a 3-minute window. Each block is only acted on once (tracked in notifiedBlocks). No-ops when not viewing today.

Fires an audible chime if the elapsed time has crossed a configured interval boundary since the last chime. No-ops when the timer is paused.

Formerly showed a "new day" banner prompting the user to export yesterday's log. The banner was removed — end-of-day modal handles exports now. Kept as a no-op stub to avoid removing the call sites.

Clears the pomodoro log when a new ISO week begins. Compares the stored week key against the current ISO week; if they differ, the log is removed and the new week key is saved.

Clears the persisted FSA directory handle from both IndexedDB and the in-memory cache so future exports fall back to browser downloads.

Closes every open inline time-editor panel and restores the display spans.

Closes the migration overlay.

Hides the quick-capture overlay and stops the elapsed ticker.

Hides the new-tracker form and resets the open-state flag.

Saves a timestamped note attached to the currently-active timer entry. The note is stored in logNotes (type: 'session-note') and rendered nested under its parent entry in the flow/log views, rather than as a standalone time-tracked entry. No-ops when there is no active timer or the note is empty.

Computes the day's start and end timestamps for the plaintext export header.

Start: the supplied day start (today only) or, failing that, the earliest entry start. End: the latest tracked end among timed entries, extended by the active timer's effective end so "Ended:" reflects work still in progress.

Pure: all environmental inputs (day start, the active timer, the current time) are injected via opts so the function can be unit-tested without globals.

Logs a snapshot of runtime configuration at startup in a collapsed group. Called once by 07-lifecycle.js after state is loaded.

Advances an entry's signifier one step through SIG_CYCLE and persists the change. Wraps from the last value back to null (no signifier).

Emits a debug-level message, visible only when DevTools verbose level is on.

Formats a Date as YYYY-MM-DD using local calendar date. Uses local date components (getFullYear / getMonth / getDate) so the returned string always matches the date the user sees on their clock, regardless of timezone.

Redraws all pomodoro SVG segments to reflect the current remaining time. Each minute is a sector; filled sectors fade as time elapses.

Archives (drops) the task by marking it done and migrated.

Builds an HTML <span class="etime-dur"> containing the human-readable duration between two timestamps. Returns an empty string if the duration is zero or negative.

Records start-of-day silently (no backup-restore dialog) if the day has not already been started. Called automatically when the first task timer begins.

Activates focus/emergency mode: hides the main UI, shows the overlay, moves the pomodoro section into the overlay, and focuses the next-action input. The previously saved next-action note is restored if one exists for the active entry.

Returns the localStorage key for a given day's end-of-day timestamp.

Emits an error — something that broke or produced an incorrect result.

Escapes a string for safe insertion as HTML text content.

Deactivates focus/emergency mode: restores the main UI, saves the next-action note, moves the pomodoro section back to its normal position, and auto-expands the active task's checkpoint list so the user can pick up where they left off.

Exports a full JSON backup of all application state: entries, categories, plan tasks, time blocks, pomodoro log, dev log, distractions, and hidden quick-pick items. Triggers a file download or writes to the save folder.

Exports the currently viewed day's log as a plaintext file. Groups entries by category and task, includes a header with day start/end times and tracked time totals, and appends a pasteable billable summary. Writes to the user's chosen save folder via the File System Access API, or falls back to a browser download.

Fetches today's meetings from the local PowerShell proxy (/api/calendar), caches the result, filters out user-hidden meetings, and calls renderCalStrip. Logs a warning and shows a fallback message on error.

Calls the Claude API via /api/ai to generate 3 concrete physical steps for transitioning from the ended meeting to the next task. Displays the result in expandedEl; falls back to copying the prompt to the clipboard on API error.

Fetches today's Finnish flag days, public holidays, and notable days from the Nimipäivärajapinta Typesense API, displaying the first match in #liveFlagDay. If today has no event, shows the next upcoming one. Falls back to the hardcoded FLAG_DAYS_FIXED list if the API is unreachable.

Fetches today's Finnish and Swedish name days from the Nimipäivärajapinta API and renders them in #liveNameday. Falls back to an "API unavailable" note on error.

Fetches current weather, hourly precipitation probability, and sunrise/sunset data from the Open-Meteo API for the configured location (WEATHER_LAT, WEATHER_LON) and populates #liveWeather, #liveRain, and #liveSunrise. No-ops gracefully on file: protocol or network error.

Finds the largest untracked gap (≥ 15 min) today, including gaps between consecutive completed entries AND the trailing gap from the most recent entry's end to now (which is often the most actionable). Returns null for past days — only actionable today.

Sorts a flat list of plan tasks by status order and priority, inserting child tasks immediately after their parent. Tasks matching the currently running timer text are sorted first. Orphaned children (whose parent has been deleted or moved) are appended at the end.

Formats a past timestamp as a relative "ago" string for the last-note reference line. Uses an injected now parameter so it is fully unit-testable without mocking Date.now.

Formats a duration in milliseconds as a compact human-readable string ("Xh Ym"). Used throughout the UI for tracked-time display in the timeline, chart, and plan.

Formats a duration in milliseconds as a human-readable string using the long "min" suffix. Used in plaintext exports where readability matters more than compactness.

Formats a duration in milliseconds as a compact time string.

Formats a Unix timestamp (ms) as HH:MM in local time.

Returns a human-readable day label: 'today', 'yesterday', or a short locale date string.

Formats a Date as a zero-padded "MM-DD" string used as flag-day map keys.

Formats a Unix timestamp as HH:MM in 24-hour local time.

Selects the view at index nextIndex in TF_VIEWS, focuses its tab button, and re-renders. Shared by the keyboard handler in initTodayFlow().

Renders the grouped-by-category structure into indented text lines: one line per category (with its total), each followed by its indented task lines.

Pure: the duration formatter and category-label resolver are injected so this function has no dependency on global state and can be unit-tested directly.

Returns the category object for id, falling back to 'other' if not found. The returned colour is always sanitised through safeCssColor.

Retrieves a given day's recorded start-of-day timestamp from localStorage.

Returns the total elapsed milliseconds for the active timer. Accounts for accumulated time from previous pause/resume cycles. Returns 0 if no timer is active.

Retrieves a given day's recorded end-of-day timestamp from localStorage.

Returns an object mapping "MM-DD" strings to Finnish flag-day names for the given year. Combines fixed dates with computed moveable feasts.

Returns the persisted view preference, defaulting to 'flow'.

Retrieves the stored handoff note for a given entry text. The lookup is case-insensitive and trims whitespace.

Returns the ISO 8601 week number for a given date.

Returns the first iteration expiry date that is strictly later than completedDay, or null if none is configured beyond that date.

Returns a stable string key for a meeting used to deduplicate bridge banners.

Returns the migration completion record (map of YYYY-MM → boolean).

Calculates moon phase, illumination percentage, and zodiac sign for a date using a simplified version of the Meeus algorithm.

Returns the stored reflection record for a given day, or null if none exists.

Retrieves the previously granted File System Access directory handle from IndexedDB (with an in-memory cache).

Returns the set of meeting keys (subject|start) that have already triggered a bridge banner in this session, loaded from localStorage.

Resolves the work location for the currently viewed day.

Groups a day's log entries by category and, within each category, by task (case-insensitively), preserving first-seen order. Accumulates tracked time (where tsEnd > ts) per task and per category.

Pure data transform — reads only entry fields and performs no formatting, so the caller decides how to render the durations and labels.

Partitions today's plan tasks into the three kanban column groups.

Handles a mood selection from the banner dropdown. Records a distraction or parked thought as an entry (for distracted/parked moods), triggers the hook panel for 'interesting', and sets focus mode for 'focus'. Closes the panel afterwards.

Called by stopTimer() just before activeTimer is cleared. Shows the stopped confirmation panel and arms the 6s auto-dismiss.

Derives the current hero state from module-level timer variables.

Updates the running-state elapsed clock without a full render. Only touches the clock element so the DOM churn stays minimal.

Hides and clears the handoff-note text field.

Restores application state from a JSON backup file previously created by exportBackup. Reads the file, validates its structure via validateBackupFile, asks the user to confirm, writes all arrays to their localStorage keys, then reloads the page so state is re-initialised cleanly from the restored data.

Assumption: import is a full replace, not a merge. All data currently in the affected localStorage keys is overwritten after the user confirms. If selective-date merging is ever needed, add a merge mode option here and update the confirmation dialog accordingly.

Emits an informational message.

Binds all interactive controls on the V5 timer banner: mood dropdown, quick-note input, and Break / Lunch / Meeting utility pills. Called once from 07-lifecycle.js after DOMContentLoaded is guaranteed.

Registers dragover, dragleave, and drop listeners on the three static board column lists. Called exactly once on DOMContentLoaded from 07-lifecycle.js. Card draggable wiring (re-rendered each cycle) stays in bindBoardColumnDnD().

Binds all Hero Card button events. Called once from DOMContentLoaded in 07-lifecycle.js.

Binds the location toggle button. Called exactly once from the boot sequence in 07-lifecycle.js; there is no re-invocation path, so the click listener is attached without a guard. If a future caller invokes this more than once, add a removeEventListener (or an "already bound" flag) first to avoid duplicate handlers. Safe to call when the button is missing.

Initialises the migration overlay: wires close button and optionally shows a last-day-of-month banner once per month.

Bootstraps the Monthly Log feature. The Monthly Log is now the "Month" tab in Today's Flow; its visibility and rendering are driven by renderTodayFlow(). Month sync happens in initTodayFlow() when the Month tab is clicked. This function is kept as a no-op so the call site in 07-lifecycle.js does not need to change.

Initialises (or re-initialises) the pomodoro timer for the given duration. Clears any running interval, resets state, and highlights the matching duration button.

Registers all event listeners for the quick-capture overlay. Called once on DOMContentLoaded.

Registers all sprint UI event listeners: the sprint mode button, start, cancel, and Enter-key shortcut on the intention input. Called once on DOMContentLoaded.

Binds the static listeners exactly once on DOMContentLoaded:

• Log-note input/button (static HTML, never recreated)
• Segmented-control click + keyboard nav, delegated off the stable #tfHeader container so we survive its innerHTML being rewritten by every renderFlowHeader() call. Avoids the listener-accumulation bug that occurred when binding happened inside render functions.

Bootstraps the Trackers feature: performs the initial render and wires up the "+ New" button to toggle the tracker form open/closed. Called once on DOMContentLoaded.

Determines whether a log entry is billable, using a three-tier lookup:

1. The entry's own billable flag (if explicitly set).
2. The matching plan task's billable flag.
3. The category default.

Assumption: entries and tasks where billable is undefined are treated as billable by default. This preserves backward compatibility with data created before the billable flag was introduced — older entries must not silently disappear from billing reports after an upgrade. If the default should change to non-billable, a migration of existing localStorage data is required (see DATA.md § wl_entries).

Returns true if d falls on today's calendar date (UTC).

Returns HTML for a task text string, converting any leading Jira ticket key (e.g. AITO-1234) into a clickable link. The remainder of the text is HTML-escaped and appended.

Returns the date of the last occurrence of a weekday in the given month.

Loads all persistent state from localStorage into module-level variables. Invalid records are dropped per-item (rather than rejecting entire arrays) and any drops are reported via wlLog.warn so data-quality issues are visible in DevTools rather than silently disappearing. Falls back to the last snapshot if entries are missing from primary storage.

Loads time blocks from localStorage into blocks, filtering invalid entries. Drops are reported via wlLog.warn so data-quality issues are visible in DevTools. Applies a one-time migration to shift existing block slots by +2 when the time-block grid start time changed from 08:00 to 07:00.

Loads iteration expiry dates from localStorage into _expiryDates. Seeds localStorage with EXPIRY_SEED on first run.

Reads the stored location map from localStorage. Returns an empty map (and logs a warning) if the value is missing or corrupt, so a single bad write can never break the header render.

Loads plan tasks from localStorage into planTasks, filtering out invalid entries via validPlanTask. Drops are reported via wlLog.warn so data-quality issues are visible in DevTools. Resets to empty array on parse error.

Loads reflection data from localStorage into _reflData.

Loads sprint history from localStorage into the module-level sprintLog array. Falls back to an empty array and logs a warning on parse failure.

Loads the trackers array from localStorage into the module-level trackers variable. Falls back to an empty array and logs a warning on parse failure.

Resolves the stored work location for a given day, falling back to the default when the day is unset or holds an unknown value.

Logs a short well-known activity (break / lunch / meeting) as a new entry while keeping the active timer running. The active timer is NOT stopped so the user can resume without friction.

Merges same-task entries that are separated by no more than gapMs into a single block, carrying the merged end time on a _end property.

Two entries merge only when they share the same task text and the same category (tag, with a missing tag normalised to other). Category is part of the key so that two adjacent entries with the same label but different categories are not collapsed — otherwise the later category would be lost from the exported billable summary, which reads tag from the merged block.

Rationale for the gap: the default 30-minute window matches the billing rounding unit — splitting a task at a gap shorter than one slot would produce two entries that each round to the same half-hour anyway, while making the summary harder to read. Input is not mutated; entries are sorted by start time first.

Merges the hardcoded DEV_CHANGES array into the persisted dev log in localStorage, adding only entries whose id is not already stored. Maintains chronological sort order by id.

Fixes entry date fields that were stored using UTC midnight instead of the user's local calendar date.

Background: dk() previously called toISOString() (UTC). For UTC+ users (e.g., Finland, UTC+2/+3), entries logged between local midnight and 02:00–03:00 were stored under the previous day's UTC date. This migration re-derives date from the entry's ts timestamp using the now-correct local dk().

Safe to run multiple times — entries already on the correct local date are untouched.

Runs all pending schema migrations. Safe to call multiple times — migrations are skipped if the source key is absent or the destination key already has data.

Returns the number of days in a given month.

Maps a logged-hours value to a CSS colour for the heatmap grid. Thresholds: 0h → bg3 (empty), <2h → faint blue, <5h → mid blue, <7h → strong blue, ≥7h → solid blue.

Sums tracked milliseconds for all non-cancelled entries on a given day.

Moves a task to a new board column, updating its status and timer state. Dropping into In Progress stops any running timer, creates a new time entry, and starts tracking. Dropping into Done or To Do stops the active timer.

Returns the first date on or after from that falls on the given weekday.

Returns the next visually distinct colour from the palette for a new category. Falls back to golden-angle HSL generation once all palette colours are in use.

Returns the next location id when toggling, cycling through the keys of WORK_LOCATIONS. With the two presets this flips Remote ↔ Office. An unrecognised loc (indexOf → -1) is treated as "before the first" and wraps to the first location, so the toggle always recovers to a valid state.

Called from pomoDone() when the Pomodoro ring reaches zero. Fires the registered _onSprintEnd callback if one is set, then clears it so it cannot fire twice.

Builds the Notion send/link button HTML for a task row. Shows a link icon if already sent; send icon otherwise.

Returns the date of the nth occurrence of a weekday in the given month.

Opens a floating emoji picker anchored below anchor for a time block. Identical behaviour to openEmojiPicker but operates on blocks instead of planTasks. Calling again for the same block ID closes the picker.

Opens a floating emoji picker anchored below the given element. Includes a free-text input for custom emoji and a grid of common choices. Calling again for the same task ID closes the picker.

Opens the end-of-day modal: auto-exports the time log and JSON backup, saves the EOD timestamp, populates handoff notes for unfinished tasks, renders today's dev changelog entries, and lists the test areas to review.

Opens the iteration-expiry editor modal, pre-filling the textarea with the current expiry dates (one per line).

Opens (or creates) the IndexedDB database used to persist the FSA directory handle.

Opens the migration modal and populates it with open (unresolved) tasks for the current month. Alerts if there is nothing to migrate.

Opens the quick-capture overlay and focuses the search input.

Opens the end-of-day reflection overlay. Resets star ratings to 0, attaches Save/Skip handlers that call onComplete when dismissed.

Shows the sprint setup panel, clears the intention input, resets the duration selection to 25 minutes, and focuses the intention field.

Shows and populates the new-tracker form inside #trackerNewForm. Pre-fills the colour picker with the first category's colour. Attaches Save / Cancel / keyboard listeners.

Parses inline shorthand tokens from a raw quick-capture input string and returns a clean text plus structured token values.

Supported tokens (each stripped from the returned text):

• #<cat> — Category: matched against category ids and labels (case-insensitive; prefix match as fallback). Last occurrence wins.
• !<sig> — Signifier shortcode (see RAPID_SIG_SHORTCUTS). Last occurrence wins.
• ><date> — Date pointer: today, tomorrow, YYYY-MM-DD, or weekday mon–sun (next occurrence). Last occurrence wins.

Unrecognised tokens are left in the text unchanged so the user sees them and can correct them without data being silently discarded.

Partitions a flat item list from buildDailyLogItems into two structures: non-session-note items (the main timeline rows) and a lookup of session-note items keyed by their parentEntryId. Session-notes render nested inside their parent entry row rather than as standalone timeline entries.

Applies data migrations and status patches to today's plan tasks after carry-over:

• Stamps billable: true on tasks/categories that predate the feature.
• Stamps completedAt on done tasks missing a timestamp.
• Promotes today's task status to match the most recent past version when that version was pending/blocked/upcoming or in-progress.

Pauses the pomodoro timer without resetting the remaining time.

Pauses the running timer, accumulating elapsed time so it can be resumed. No-ops if no timer is active or it is already paused.

Prompts the user to select a save folder via the File System Access API and persists the resulting directory handle. Shows a fallback alert in browsers that do not support the API.

Plays two soft sine-wave tones (528 Hz then 660 Hz) using the Web Audio API to signal an elapsed-time milestone. Silently skips if Web Audio is unavailable (e.g. browser privacy settings).

Plays three short 660 Hz beeps spaced 350 ms apart using the Web Audio API to signal pomodoro completion. Silently skips if Web Audio is unavailable.

Adds 120 seconds to the current running session without resetting segments. No-op if the timer is not running.

Returns a progress-aware affirmation string based on elapsed time. Default parameters let callers pass explicit values (useful for testing).

Builds an array of POMO_SPARKLINE_DAYS date strings ending today, oldest first.

Called when the pomodoro timer reaches zero. Plays the completion beep, briefly animates the time display, and appends a session record to the pomodoro log in localStorage.

Returns the angular gap (in radians) between pomodoro timer segments. Smaller gaps are used for higher segment counts to keep them visually distinct.

Reads and validates the pomodoro session log from localStorage. Invalid records are dropped and reported via wlLog.warn.

Returns the number of completed pomodoro sessions on the given date.

Reads the --pomo-spark-fill and --pomo-spark-empty CSS variables for the active colour scheme. Falls back to hardcoded values when CSS vars are unavailable (e.g. headless test environments).

Ends the session early, logs a partial session, and transitions to done state. Records the elapsed minutes (minimum 1) so the session appears in the log.

Positions the "now" indicator line in the time-block grid to reflect the current time. Hides the line when outside the grid's time range (TB_START–TB_END).

Builds the priority toggle button HTML for a task row. Click cycles: normal (0) → high (1) → low (-1) → normal.

Reads the stored collapsed state for a section from localStorage.

Reads and parses an optional JSON-array log from localStorage for inclusion in a backup. If the stored value is present but not valid JSON, the failure is logged via wlLog (so the data loss is diagnosable rather than silent) and an empty array is returned so the rest of the backup still succeeds. Absent keys legitimately yield an empty array.

Full Pomodoro dashboard refresh: redraws the 28-day sparkline, ribbon footer, and composer task label. Called on module load and after every session completion.

Full application re-render: updates the date label, timer bar, stat counters, sub-stats, time-log list, chart, quick-pick, plan, completed section, and time-block view. Call whenever persistent state changes.

Design trade-off: full DOM re-render on every change rather than targeted updates. Keeps state reasoning simple for a single-user personal tool where the entry list is small (typically < 50 items per day). If performance becomes a concern, the innermost timelineEl.querySelectorAll event-binding loop is the first candidate for optimisation (see phase 6 below).

Appends the collapsible "older history" expander to the Done column list. Shows completed tasks from prior dates, grouped by day, within the active iteration.

Renders the calendar meetings strip for today. Sorts meetings by start time, marks past meetings grey/italic, pulses ongoing meetings, and provides ▶ start and ✕ hide buttons per meeting.

Renders the time-tracking bar chart for the currently viewed day. Decorates the active timer's entry with a synthetic tsEnd so live time appears in real-time. Respects chartMode ('task' | 'category').

Renders the completed-tasks section for the currently viewed date. Shows tasks that were completed on or before the view date and whose iteration expiry date has not yet passed. Deduplicates by task text, keeping only the most recently completed version. Hides the section when there are no matching tasks.

Renders the compact day-overview strip: hour-tick labels, entry footprints, and (today only) a live "now" cursor.

Renders the checkpoint list inside the focus-mode overlay for the currently active task. Hides the wrapper if the task has no checkpoints. Each checkpoint cycles through three states on click: false → 'partial' → true.

Updates the "end the day" button to show the end time recorded for the day in view (if any) or its default label, and dims the button once a time is set.

No longer actively used — fetchCalendarEvents handles flag-day display. Kept as a no-op stub so call sites don't need to be removed.

Renders the section header: icon, title, tracked/billable totals, and the Flow / Log / Blocks segmented control.

Renders the Flow view: a vertical list where each entry's accent strip height is proportional to its duration (height = max(64, 0.6 × minutes) px), giving longer tasks more visual weight.

Updates the #folderStatus element to show the currently selected save folder name (green) or a "pick save folder" prompt (default colour).

Renders or hides the gap-reminder banner.

Switches the root card's state-modifier class and makes the matching inner panel visible. Updates all dynamic content for the current state.

Updates the date-nav location button to reflect the viewed day's location. No-ops when the button is absent (e.g. in a reduced test DOM).

Renders the current migration step (or the "done" screen when all resolved).

Renders the heatmap calendar grid: navigation header, day labels, day cells, and the colour legend. Binds cell-click (navigate to that day) and prev/next month buttons. Writes its full HTML to calEl.

Implicit dependency: the prev/next handlers mutate module-level _mlYear / _mlMonth and then call renderMonthlyLog() to re-render the whole view. Both globals must therefore be in scope when this function is called.

Orchestrates the Monthly Log view: resolves DOM targets and delegates each panel to a single-purpose renderer.

Renders the time-totals summary panel: total logged, billable, top category. Writes its full HTML to sumEl. No event binding. Early-returns if sumEl is absent so a partial DOM doesn't throw on innerHTML assignment.

Renders the task-inventory panel: open / done / migrated counts plus a "Run Migration" button. Writes its full HTML to taskEl and binds the button to openMigration() if that helper is loaded. Early-returns if taskEl is absent so a partial DOM doesn't throw on innerHTML.

Renders today's moon phase, illumination, and zodiac sign into #liveMoon. No-ops if the element is absent.

Re-renders the entire plan UI as a 3-column kanban board (To Do / In Progress / Done). Pending and blocked tasks absorb into the To Do column with their existing badge treatment. The Done column shows today's completed tasks and a collapsible history expander for older ones.

Design trade-off: full DOM re-render on every state change rather than targeted updates. Acceptable for a personal tool where the task list is small (< 20 items).

Renders the pomodoro session history list inside #pomoLog. Shows date/time, duration, and the task that was active during each session.

Renders the ribbon footer below the 4-column grid:

• #pomoRibbonDots: last-5-session dot sequence (● filled, · empty slot)
• #pomoRibbonPill: "Peak Focus" pill when today matches the all-time high, otherwise "N sessions today", hidden when no sessions today
• #pomoRibbonLink: "View all N sessions ↓" button that scrolls #pomoLog

Each element is individually guarded — no-op when absent from the DOM.

Draws a 28-day focus density bar chart on the #pomoSparkline canvas. Each bar represents one calendar day; bar height is proportional to the number of completed pomodoro sessions on that day. No-op when the canvas element is absent or the 2D context is unavailable.

Renders the "recent tasks" quick-pick bar below the capture input. Deduplicates entries by text, hides manually-dismissed tasks and tasks past their iteration expiry, and caps the list at 16 items.

Renders a 1–5 star row inside elId, marking stars up to current as active.

Builds the HTML string for a single plan task row. Handles two layout branches: pending/blocked (compact) and normal (full). Reads module-level state variables for edit mode, checkpoint open state, and pending comment state so re-renders are always consistent.

Updates the session chip to show the start time recorded for the day in view (with a green dot), or the default "start the day" label when that day has no recorded start. The button's text content is its accessible name; no static aria-label is used so screen readers announce the current state ("started HH:MM" or "start the day").

Renders the duration chip row inside #sprintDurations, marking the currently selected duration active. Attaches click listeners to each chip.

Renders the full time-block grid for the currently viewed date: time labels, grid rows, planned blocks (with drag-to-move), live timer block, a "now" line, and the plan-task drag targets. Also handles drag-and-drop wiring for moving existing blocks and dropping tasks from the plan list.

Renders the Today's Flow section: header, day-overview strip, gap reminder, and the active view pane (Flow / Log / Blocks / Month). Called from render() on every state change and when the view toggle fires.

Renders the "+ TRACK RECENT" strip inside #planTrackRecent. Shows chips for the most recent unique time-log entries from today so the user can restart a timer with a single click without re-typing. Limits to 5 entries; hidden when no entries exist for today.

Renders all tracker cards into #trackerList. Each card shows a 28-day hit/partial/miss grid, current streak, and total hit count. Attaches delete-button listeners after render.

Resets the pomodoro timer to the full configured duration without starting it.

Determines the carry-forward status a today-task should adopt based on its most recent past peer, implementing the following rules:

• pending or blocked prev overrides todo or inprogress today — the task is still blocked so the blocking state wins.
• upcoming prev overrides only a todo today — a todo placeholder created from an even-older copy should reflect the more recent intent to defer. It must NOT override inprogress, because the user explicitly started the task and a reload must not undo that.
• inprogress prev promotes a todo today — the task was already being worked on and the carry placeholder should show that.

Returns null when no change is needed.

Resolves a >date shorthand token to a YYYY-MM-DD date key. Supported tokens: 'today', 'tomorrow', exact 'YYYY-MM-DD', and weekday abbreviations 'mon'–'sun' (resolves to the next occurrence, never today).

Resumes a paused timer from where it left off. No-ops if no timer is active or it is not paused.

Called at startup to reconnect the tick interval when the app is reloaded with an active timer persisted in localStorage. If the entry the timer was tracking no longer exists the timer is cleared. No-ops if no timer is active.

Rounds a timestamp to the nearest 30-minute clock mark.

Tie-breaking rule (at exactly 15 min into a 30-min slot): rounds DOWN. Rationale: conservative for billing — a task must exceed the midpoint of the slot before the next slot is claimed.

Assumption: rounding ties (exactly 15 min past a slot start) are resolved in favour of the earlier slot to avoid inflating billable time. This matches the intent documented in DATA.md under wl_entries.ts.

Rounds ts to the nearest 30-minute mark only when entry is billable. Non-billable entries keep their exact timestamps for accurate reporting.

Rounds a duration up to the nearest 30-minute slot, with a minimum of 30 min. Used for billing time estimates — even a 1-second task costs one half-hour slot.

Assumption: billing granularity is 30 minutes and the minimum billable unit is 30 minutes. Changing this assumption requires updating both this function and any UI that displays billable totals (e.g. the billable-time section in exports).

Returns c if it is a safe CSS colour (hex or hsl()), otherwise returns a neutral fallback. Prevents malformed user-supplied colour values from breaking layout or injecting CSS.

Returns a rounded start timestamp that does not overlap any existing entry for today. Prevents new entries from appearing to start before a prior entry's end time.

Persists entries, active timer, and categories to localStorage. Refuses to overwrite existing non-empty data with an empty array to guard against accidental data loss if save() is called before load() completes.

Assumption: an empty entries array in memory while localStorage still holds data means save() was called before load() finished (e.g. a race during init), not that the user intentionally deleted everything. Intentional clearing goes through a dedicated wipe path that bypasses this guard.

Persists the current blocks array to localStorage.

Reads all handoff-note inputs in the EOD modal and persists their values to the wl_handoff localStorage key. Empty values are removed from the map.

Reads the expiry-date textarea, validates each line against YYYY-MM-DD format, deduplicates and sorts the valid dates, persists them to localStorage, and closes the modal. Invalid lines are surfaced in the feedback element but not saved.

Persists a handoff note for a given entry text. Pass an empty string or falsy value to delete the stored note. The key is stored case-insensitively.

Persists the location map to localStorage.

Persists the migration completion record to localStorage.

Persists the current planTasks array to localStorage.

Persists the current _reflData map to localStorage.

Writes a recoverable snapshot of today's log entries to localStorage every 30 minutes. The snapshot contains both a human-readable plaintext summary and the raw entry/category arrays so data can be recovered after accidental clearing. No-ops when there are no entries for today.

Assumption: 30 minutes is an acceptable data-loss window for a personal work log used in a single browser tab. Browser crashes, accidental page reloads, and mis-clicks on "clear data" are the main risks; all are adequately covered by a 30-minute recovery point. If higher durability is needed, reduce the interval in the setInterval call in 07-lifecycle.js.

Persists the current sprintLog array to localStorage.

Persists the Notion page URL on a plan task so the per-task button changes to an "open in Notion" link on next render.

Reads the new-tracker form, validates inputs, pushes the tracker to the trackers array, persists it, and re-renders. Shows an alert if no category is selected; focuses the name field if the name is empty.

Persists the current trackers array to localStorage.

Reschedules the task to the given date and marks it as migrated.

Builds an SVG path string for a pie-chart sector (filled segment).

Saves an emoji to a time block and closes the picker. Pass null or an empty string to remove the block's emoji.

Updates the browser favicon to a coloured dot reflecting the timer state. Skips redundant redraws by tracking the last rendered state.

Persists the active view selection.

Redraws the browser favicon as a depleting wedge mirroring the remaining pomodoro time. Silently skips when the canvas API is unavailable.

Persists the set of seen-ended meeting keys to localStorage.

Saves an emoji to a plan task and closes the picker. Pass null or an empty string to remove the task's emoji.

Shows the post-meeting bridge banner for the given meeting. Queues the meeting if another banner is already visible.

Shows the handoff-note text field in the timer bar so the user can record what a future self (or colleague) should know before picking this task up again.

Stops the main timer and renders the sprint review panel inside #sprintReview. Populates the intention label, wires outcome buttons (yes / partly / no), and on save: appends the sprint to sprintLog, tags the entry with the outcome, persists both, hides the panel, and triggers a full render.

Returns the HTML string for the clickable signifier widget on one entry row.

Returns the display symbol for an entry's signifier.

Returns the accessible title string for an entry's signifier.

Converts a 0-based half-hour slot index to an "HH:MM" label. Slot 0 = TB_START:00, slot 2 = TB_START+1:00, etc.

Returns the localStorage key for a given day's start-of-day timestamp.

Starts the pomodoro countdown. Resets to full duration if already at zero. Fires pomoDone and clears the interval when time runs out.

Commits a new sprint: reads the intention from the input, creates a time-log entry, starts the main timer, starts the Pomodoro for _sprintDuration minutes, and sets _onSprintEnd so the review panel is shown when the ring reaches zero. No-ops with a focus call if the intention field is empty.

Starts (or restarts) the timer for the given entry. Clears any existing interval, resets the chime state, and begins a 1-second tick. Persists state and updates the UI immediately.

Builds the list for a task's status .

Parameters:

Name	Type	Description
cur	string	The task's current status value.

Source:

• 10a-tasks-render.js, line 8

Returns:

HTML option elements.

Type

string

stopTimer()

Stops the active timer, stamps the log entry with an end time (rounded to the nearest 30 min for billable entries), clears activeTimer, and triggers a full render. Resets the timer bar colour and closes the park capture input if open. No-ops if no timer is active.

Source:

• 03-timer.js, line 69

(async) storeDirHandle(handle) → {Promise.<void>}

Persists a File System Access directory handle to IndexedDB for reuse across sessions, and updates the in-memory cache.

Parameters:

Name	Type	Description
handle	FileSystemDirectoryHandle	The directory handle to store.

Source:

• 05b-filesystem.js, line 50

Returns:

Type

Promise.<void>

stripJiraPrefix(text) → {string}

Removes a leading Jira issue key (e.g. ABC-123: or ABC-123 ) from a task label, leaving the human-readable summary. Used when building the pasteable billable summary so issue keys do not clutter the client-facing line.

Parameters:

Name	Type	Description
text	string	The raw task label.

Source:

• pure-fns.js, line 605

Returns:

The label with any leading Jira key stripped and trimmed.

Type

string

Example

stripJiraPrefix('PROJ-42: Fix login')  // → 'Fix login'
stripJiraPrefix('Write tests')         // → 'Write tests'

stripPct(mins) → {number}

Converts a minutes-from-midnight value to a percentage across the strip range. Clamped to [0, 100].

Parameters:

Name	Type	Description
mins	number

Source:

• 11-timeflow.js, line 57

Returns:

Type

number

tbOverlaps(newStartMins, newEndMins, dateKey, excludeIdopt) → {string}

Returns a comma-separated string of task names that overlap a proposed time range, checking both planned blocks and logged time entries. Returns an empty string if there are no overlaps.

Parameters:

Name	Type	Attributes	Description
newStartMins	number		Proposed start time in minutes from midnight.
newEndMins	number		Proposed end time in minutes from midnight.
dateKey	string		Date string in YYYY-MM-DD format.
excludeId	string	<optional>	Block ID to exclude from the check (when moving).

Source:

• 11-timeblock.js, line 407

Returns:

Overlapping task names, or '' if none.

Type

string

tbStartBlock(blockId, overrideTsopt)

Starts a timer for the given time block: creates (or promotes) the matching plan task to "in progress", stops any running timer, creates a new log entry, and starts the tick interval. Uses overrideTs as the entry start time so elapsed time is counted from the scheduled start, not wall-clock now.

Parameters:

Name	Type	Attributes	Description
blockId	string		ID of the time block to start.
overrideTs	number	<optional>	Optional explicit start timestamp (ms). Defaults to safeRoundedStart().

Source:

• 11-timeblock.js, line 628

tickClock()

Updates the live clock display (date, time, ISO week), the time-block "now" line, and block notifications. Also detects midnight rollover: carries unfinished plan tasks to the new day and re-renders the UI.

Source:

• 09-clock-weather.js, line 34

tickTimer()

Called every second by the timer interval. Updates the timer bar text, the live time-block element, the tab title/favicon, the bar colour, and checks whether a chime should fire. Also refreshes the focus-mode overlay when it is open. Errors are caught and logged so a single bad tick cannot stop the interval.

Source:

• 03-timer.js, line 288

timeToSlot(hhmm, m2opt) → {number}

Converts a time value to a 0-based slot index relative to TB_START. Accepts either an "HH:MM" string or two separate (hours, minutes) arguments.

Parameters:

Name	Type	Attributes	Description
hhmm	string | number		"HH:MM" string, or hours when m2 is provided.
m2	number	<optional>	Minutes (only when hhmm is a number).

Source:

• 11-timeblock.js, line 71

Returns:

0-based slot index.

Type

number

toTimeInput(ts) → {string}

Converts a Unix timestamp (ms) to an HH:MM string suitable for an <input type="time"> value.

Parameters:

Name	Type	Description
ts	number	Unix timestamp in milliseconds.

Source:

• 04-render.js, line 659

Returns:

Local time formatted as "HH:MM".

Type

string

toggleViewLocation() → {void}

Toggles the currently viewed day to the next location (Remote ↔ Office), persists it, logs the decision, and re-renders the header button.

Source:

• 24-location.js, line 58

Returns:

Type

void

totalISOWeeks(year) → {number}

Returns the total number of ISO weeks in a given year (52 or 53). Uses the fact that Dec 28 is always in the last ISO week.

Parameters:

Name	Type	Description
year	number	The full 4-digit year.

Source:

• 09-clock-weather.js, line 20

Returns:

52 or 53.

Type

number

trackerDayStatus(tracker, dateKey) → {'hit'|'partial'|'miss'}

Returns 'hit' | 'partial' | 'miss' for a given tracker on a given day.

Parameters:

Name	Type	Description
tracker	Object	Tracker object with tags and targetMinutes.
dateKey	string	YYYY-MM-DD date key.

Source:

• 22-trackers.js, line 32

Returns:

Type

'hit' | 'partial' | 'miss'

trackerStreak(tracker) → {number}

Calculates the current consecutive "hit" streak for a tracker, ending today. Walks backwards day-by-day (up to 60 days) and stops at the first non-hit day.

Parameters:

Name	Type	Description
tracker	Object	Tracker object with tags and targetMinutes.

Source:

• 22-trackers.js, line 51

Returns:

Number of consecutive hit days ending today.

Type

number

triggerPortableDeploy()

Fire-and-forget portable deploy: calls POST /api/portable-deploy to trigger the PowerShell build script, then displays a transient top-right toast with the result (success, failure, or server unreachable). Never throws.

Source:

• 12a-changelog.js, line 829

tsToMins(ts) → {number}

Converts a Unix timestamp (ms) to minutes-from-midnight in local time.

Parameters:

Name	Type	Description
ts	number

Source:

• 11-timeflow.js, line 69

Returns:

Type

number

updateHeaderTracking()

No-op: the header tracked-total and pace bar were removed in the top-zone redesign (ITEM 1). Kept so tickClock() and tickTimer() call sites remain unchanged.

Source:

• 09-clock-weather.js, line 68

updateLiveBlock()

Updates the live time-block element in the time-block view to reflect the current elapsed time of the active timer. No-ops if the live block element or the active timer's entry cannot be found.

Source:

• 03-timer.js, line 99

updatePomoDisplay()

Refreshes the pomodoro timer display: updates the countdown text, redraws segments, sets the state-modifier class on the pomo-body, and updates button labels and status text to reflect the current state.

Source:

• 08-pomodoro.js, line 251

updatePomoTaskLabel()

Updates #pomoTaskLabel (composer column) with the text of the currently running timer entry. Clears the label when no timer is active.

Source:

• 08a-pomo-dashboard.js, line 172

updateTabAndFavicon()

Synchronises the browser tab title and favicon with the current timer state. Adds a ▶/⏸/🔴 prefix and shows the elapsed time and task name in the title. Switches to hyperfocus state (red) after HYPERFOCUS_MINS minutes for non-meeting tasks.

Source:

• 03-timer.js, line 165

updateTimerArc(elapsedMs)

Updates the SVG arc on the timer circle to reflect elapsed time relative to the hyperfocus threshold. The arc fills 0→100% of the circle circumference (2πr ≈ 150.8 px for r=24) as elapsed time goes from 0 to HYPERFOCUS_MINS.

Parameters:

Name	Type	Description
elapsedMs	number	Elapsed time in milliseconds.

Source:

• 03-timer.js, line 266

updateTimerBar()

Shows or hides the timer bar and updates the pause/resume button label. Also enables or disables the "make it interesting" hook button.

Source:

• 03-timer.js, line 317

updateTimerBarColor()

No-op: #timerBar was replaced by the Hero Card whose colour is driven by CSS state-modifier classes (hero-card--running, --paused, etc.). Kept so existing call-sites in tickTimer compile without changes.

Source:

• 03-timer.js, line 256

updateTimerBtn(running)

Updates the main start-timer button's label and disabled state.

Parameters:

Name	Type	Description
running	boolean	True if a timer is currently active.

Source:

• 03-timer.js, line 333

validBlock(b) → {boolean}

Returns true if b is a well-formed timeblock record.

Parameters:

Name	Type	Description
b	*	Candidate value parsed from JSON.

Source:

• pure-fns.js, line 278

Returns:

True if the timeblock is well-formed.

Type

boolean

validCalendarMeeting(meeting) → {boolean}

Returns true if meeting is a well-formed Outlook calendar event object as returned by the PowerShell /api/calendar endpoint.

Required fields: subject (string), start (string), end (string). Optional fields (joinUrl, account) are not validated here — their absence is handled gracefully by renderCalStrip.

Parameters:

Name	Type	Description
meeting	*	Candidate meeting object from the calendar API response.

Source:

• pure-fns.js, line 418

Returns:

True if the meeting object is well-formed.

Type

boolean

Example

validCalendarMeeting({ subject: 'Standup', start: '2026-05-28T09:00', end: '2026-05-28T09:30' })
  // → true
validCalendarMeeting(null)                   // → false
validCalendarMeeting({ subject: 'x' })       // → false  (missing start/end)
validCalendarMeeting({ subject: 42, start: '2026-05-28T09:00', end: '2026-05-28T09:30' })
  // → false  (subject not a string)

validCategory(c) → {boolean}

Returns true if c is a well-formed category object.

Parameters:

Name	Type	Description
c	*	Candidate value parsed from JSON.

Source:

• pure-fns.js, line 244

Returns:

True if the category is well-formed.

Type

boolean

validEntry(e) → {boolean}

Returns true if e is a well-formed work-log entry safe to load from localStorage.

Parameters:

Name	Type	Description
e	*	Candidate value parsed from JSON.

Source:

• pure-fns.js, line 228

Returns:

True if the entry is well-formed.

Type

boolean

Example

validEntry({ id: '1', text: 'Write report', ts: 1234567890, date: '2026-05-25' }) // → true
validEntry(null)                           // → false
validEntry({ id: 1, text: 'x', ts: 0, date: '2026-05-25' }) // → false (numeric id)
validEntry({ id: '1', text: 'x', ts: 0, date: '25-05-2026' }) // → false (wrong date format)

validJiraCsvRow(row) → {boolean}

Returns true if row — a single object produced by parseCSV() — contains at least the key and summary columns that jiraParseAndRender() expects.

The Jira CSV export uses several possible column names for the same field (matching the lenient lookup in jiraParseAndRender):

• Key column: Issue key, Key, or Issue Key
• Summary column: Summary or summary

A row that has neither column set (e.g. from a semicolon-delimited file parsed as single-column rows) fails validation and triggers a warning.

Parameters:

Name	Type	Description
row	*	Single row object from parseCSV().

Source:

• pure-fns.js, line 451

Returns:

True if the row has the key and summary fields Jira import needs.

Type

boolean

Example

validJiraCsvRow({ 'Issue key': 'AITO-1', Summary: 'Fix login bug', Status: 'Open' })
  // → true
validJiraCsvRow({ Key: 'PROJ-2', Summary: 'Add dark mode', Status: 'To Do' })
  // → true
validJiraCsvRow({})                           // → false  (no key or summary)
validJiraCsvRow({ 'Issue key': 'AITO-1' })    // → false  (missing summary)
validJiraCsvRow({ Summary: 'Fix login bug' }) // → false  (missing key)

validPlanTask(t) → {boolean}

Returns true if t is a well-formed plan task with a recognised status value.

Parameters:

Name	Type	Description
t	*	Candidate value parsed from JSON.

Source:

• pure-fns.js, line 262

Returns:

True if the plan task is well-formed.

Type

boolean

Example

validPlanTask({ id: 'pk1', text: 'Build form', date: '2026-05-25', status: 'todo' }) // → true
validPlanTask({ id: 'pk1', text: 'x', date: '2026-05-25', status: 'finished' }) // → false (unknown status)
validPlanTask(null) // → false

validPomoEntry(e) → {boolean}

Returns true if e is a valid Pomodoro session log entry.

Parameters:

Name	Type	Description
e	*	Candidate value.

Source:

• pure-fns.js, line 313

Returns:

True if the Pomodoro entry is well-formed.

Type

boolean

validTimer(t) → {boolean}

Returns true if t is a resumable timer state. Handles both running (startTs is set) and paused (paused=true, accumulatedMs is set) forms.

Parameters:

Name	Type	Description
t	*	Candidate value parsed from JSON.

Source:

• pure-fns.js, line 300

Returns:

True if the timer state is well-formed.

Type

boolean

Example

validTimer({ entryId: 'e1', startTs: 1234567890 })              // → true  (running)
validTimer({ entryId: 'e1', paused: true, accumulatedMs: 900000 }) // → true  (paused)
validTimer({ entryId: 'e1' })                                   // → false (neither running nor paused)
validTimer(null)                                                 // → false

validWeatherResponse(data) → {boolean}

Returns true if data is a well-formed Open-Meteo forecast response containing the fields that fetchWeather() reads.

Required shape:

• data.current.temperature_2m — number
• data.current.weather_code — number
• data.hourly.time — array
• data.hourly.precipitation_probability — array

The daily block is optional (used only when present).

Parameters:

Name	Type	Description
data	*	Value parsed from the Open-Meteo JSON response.

Source:

• pure-fns.js, line 387

Returns:

True if the response is a usable forecast object.

Type

boolean

Example

validWeatherResponse({
  current: { temperature_2m: 15, weather_code: 3 },
  hourly: { time: ['2026-05-28T00:00'], precipitation_probability: [10] },
}) // → true
validWeatherResponse(null)                  // → false
validWeatherResponse({ current: {} })       // → false  (missing hourly)
validWeatherResponse({ hourly: { time: [], precipitation_probability: [] } })
  // → false  (missing current)

validateBackupFile(backup) → {Object}

Validates a parsed JSON backup object created by exportBackup().

Separated from the import flow so the validation logic can be unit-tested without any browser APIs. importBackup() calls this before writing to localStorage.

Parameters:

Name	Type	Description
backup	*	Parsed backup object (typically from JSON.parse).

Source:

• pure-fns.js, line 340

Returns:

{ valid: true } when the backup is usable; { valid: false, error: string } with a human-readable reason otherwise.

Type

Object

Example

validateBackupFile({ version: '1', entries: [], categories: [], planTasks: [] })
  // → { valid: true }
validateBackupFile(null)
  // → { valid: false, error: 'Not a valid backup object.' }
validateBackupFile({ version: '2', entries: [], categories: [], planTasks: [] })
  // → { valid: false, error: 'Unrecognised backup version "2"...' }
validateBackupFile({ version: '1', entries: [], categories: [] })
  // → { valid: false, error: '...missing required field "planTasks".' }

viewEntries() → {Array.<object>}

Returns entries for the currently viewed date, sorted newest-first.

Source:

• 02-utils.js, line 318

Returns:

Type

Array.<object>

warn(msg, dataopt)

Emits a warning — something unexpected but non-fatal.

Parameters:

Name	Type	Attributes	Description
msg	string		Human-readable message.
data	*	<optional>	Optional value to attach to the log line.

Source:

• logger.js, line 33

weatherEmoji(code) → {string}

Maps a WMO weather interpretation code to a representative emoji.

Parameters:

Name	Type	Description
code	number	WMO weather code (0 = clear sky, 95+ = thunderstorm).

Source:

• 09-clock-weather.js, line 97

Returns:

A single weather emoji character.

Type

string

writeCollapseState(sectionId, collapsed) → {void}

Writes the collapsed state for a section to localStorage.

Parameters:

Name	Type	Description
sectionId	string	The section element's id.
collapsed	boolean	Whether the section is now collapsed.

Source:

• 07-lifecycle.js, line 181

Returns:

Type

void

(async) writeExportFile(subfolder, filename, blob) → {Promise.<void>}

Writes a Blob to subfolder/filename inside the user's chosen FSA directory. Creates the subfolder if it does not exist. Falls back to a browser <a> download if the FSA handle is missing or permission is not granted.

Parameters:

Name	Type	Description
subfolder	string	Name of the subfolder to write into.
filename	string	Name of the file to create or overwrite.
blob	Blob	File content.

Source:

• 05b-filesystem.js, line 98

Returns:

Type

Promise.<void>

Type Definitions

Migration

Describes one key-rename migration.

Type:

• Object

Source:

• 01b-migrate.js, line 17

PomoSessionEntry

Type:

• Object

Properties:

Name	Type	Description
ts	number	Unix timestamp ms when the session was logged.
mins	number	Duration of the session in minutes.
task	string | null	Task name linked to the session, or null if none.

Source:

• 08a-pomo-dashboard.js, line 12