feat(cap-alerting): add NWS text product parsing for improved readability

Add support for parsing NWS-formatted descriptions in CAP alerts to improve
readability on digital signage. The app now automatically detects and formats
National Weather Service text products that use legacy abbreviated markers.

Features:
- Parse period-based forecasts (.TODAY..., .TONIGHT..., .MON..., etc.)
- Parse Impact Based Warnings in WWWI format (* WHAT..., * WHERE..., * WHEN..., * IMPACTS...)
- Automatic detection based on NWS sender email (w-nws.webmaster@noaa.gov)
- Template-based rendering for consistent styling

Changes:
- Add NWS parser functions to parser.ts
- Add NWS render functions to render.ts
- Create nws.css for NWS-specific styling
- Add HTML templates for NWS content display
- Update README with NWS formatting documentation
- Add comprehensive test coverage (170 tests passing)

The formatted content displays structured information with proper spacing,
bullet points, and color-coded labels for better visibility on screens.

Author: nicomiguelino

edge-apps/cap-alerting/README.md

@@ -21,6 +21,52 @@ Display Common Alerting Protocol (CAP) emergency alerts on Screenly digital sign
 
 Add tags to your Screenly screens (e.g., `exit:North Lobby`) to provide location-aware exit directions. The app substitutes `{{closest_exit}}` or `[[closest_exit]]` placeholders in alert instructions.
 
+## NWS Text Product Formatting
+
+The app automatically detects and formats National Weather Service (NWS) CAP alerts that use legacy text formats. This improves readability by converting abbreviated markers into clean, readable text with proper spacing and line breaks.
+
+### Supported Formats
+
+**1. Period-based Forecasts** (marine forecasts, zone forecasts)
+
+Markers: `.TODAY...`, `.TONIGHT...`, `.MON...`, `.SUN NIGHT...`, etc.
+
+Example transformation:
+
+```
+.TODAY...E wind 20 kt. Seas 11 ft. .TONIGHT...E wind 20 kt.
+```
+
+becomes:
+
+```
+TODAY: E wind 20 kt. Seas 11 ft.
+
+TONIGHT: E wind 20 kt.
+```
+
+**2. Impact Based Warnings (WWWI format)**
+
+Markers: `* WHAT...`, `* WHERE...`, `* WHEN...`, `* IMPACTS...`
+
+Example transformation:
+
+```
+* WHAT...North winds 25 to 30 kt. * WHERE...Coastal waters. * WHEN...Until 3 AM.
+```
+
+becomes:
+
+```
+WHAT: North winds 25 to 30 kt.
+
+WHERE: Coastal waters.
+
+WHEN: Until 3 AM.
+```
+
+This formatting only applies to CAP alerts from the NWS sender (`w-nws.webmaster@noaa.gov`).
+
 ## Override Playlist Integration
 
 This app is designed to use Screenly's [Override Playlist API](https://developer.screenly.io/api-reference/v4/#tag/Playlists/operation/override_playlist) to automatically interrupt regular content when alerts are active. Configure your backend to call the API when new CAP alerts are detected.

edge-apps/cap-alerting/index.html

@@ -89,6 +89,39 @@
       </div>
     </template>
 
+    <!-- NWS Forecast Content Template (with preamble) -->
+    <template id="nws-forecast-template">
+      <div
+        class="nws-content font-semibold leading-snug body-text text-gray-800 mx-[5vw] mb-[2vh]"
+      >
+        <p class="nws-preamble"></p>
+        <ul class="nws-forecast-list"></ul>
+      </div>
+    </template>
+
+    <!-- NWS Forecast List Item Template -->
+    <template id="nws-forecast-item-template">
+      <li>
+        <strong class="period-label"></strong>
+        <span class="period-content"></span>
+      </li>
+    </template>
+
+    <!-- NWS WWWI Content Template -->
+    <template id="nws-wwwi-template">
+      <ul
+        class="nws-wwwi-list font-semibold leading-snug body-text text-gray-800 mx-[5vw] mb-[2vh]"
+      ></ul>
+    </template>
+
+    <!-- NWS WWWI List Item Template -->
+    <template id="nws-wwwi-item-template">
+      <li>
+        <strong class="wwwi-label"></strong>
+        <span class="wwwi-content"></span>
+      </li>
+    </template>
+
     <script src="screenly.js?version=1"></script>
     <script src="dist/js/main.js"></script>
   </body>

edge-apps/cap-alerting/src/input.css

@@ -1,4 +1,5 @@
 @import 'tailwindcss';
+@import './nws.css';
 
 /* Modern Digital Signage Design - Viewport-based sizing */
 

edge-apps/cap-alerting/src/main.ts

@@ -9,10 +9,14 @@ import {
 } from '@screenly/edge-apps'
 
 import { CAPAlert, CAPInfo, CAPMode } from './types/cap'
-import { parseCap } from './parser'
+import { parseCap, isNwsAlert, parseNwsTextProduct } from './parser'
 import { CAPFetcher } from './fetcher'
 import { getNearestExit, splitIntoSentences, proxyUrl } from './utils'
-import { highlightKeywords } from './render'
+import {
+  highlightKeywords,
+  renderNwsWwwiContent,
+  renderNwsPeriodContent,
+} from './render'
 
 function getTemplate(id: string): HTMLTemplateElement {
   const template = document.getElementById(id) as HTMLTemplateElement | null
@@ -144,7 +148,22 @@ function renderAlertCard(
     '#description',
   ) as HTMLParagraphElement
   if (info.description) {
-    descriptionEl.textContent = info.description
+    // Try to parse and render NWS formatted content
+    if (isNwsAlert(alert.sender)) {
+      const nwsResult = parseNwsTextProduct(info.description)
+      if (nwsResult) {
+        // Replace the paragraph with the rendered NWS content
+        const nwsContent =
+          nwsResult.type === 'wwwi'
+            ? renderNwsWwwiContent(nwsResult)
+            : renderNwsPeriodContent(nwsResult)
+        descriptionEl.replaceWith(nwsContent)
+      } else {
+        descriptionEl.textContent = info.description
+      }
+    } else {
+      descriptionEl.textContent = info.description
+    }
   } else {
     descriptionEl.style.display = 'none'
   }

edge-apps/cap-alerting/src/nws.css

@@ -0,0 +1,34 @@
+/* NWS formatted content styling */
+.nws-preamble {
+  margin-bottom: 1.5vh;
+  line-height: 1.4;
+}
+
+.nws-forecast-list,
+.nws-wwwi-list {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+
+.nws-forecast-list li,
+.nws-wwwi-list li {
+  position: relative;
+  padding-left: 3vw;
+  margin-bottom: 1vh;
+}
+
+.nws-forecast-list li::before,
+.nws-wwwi-list li::before {
+  content: '•';
+  position: absolute;
+  left: 0;
+  color: rgb(234, 88, 12);
+  font-weight: 900;
+}
+
+.nws-forecast-list li strong,
+.nws-wwwi-list li strong {
+  color: rgb(30, 64, 175);
+  font-weight: 800;
+}

edge-apps/cap-alerting/src/parser.ts

@@ -121,3 +121,184 @@ export function parseCap(xml: string): CAPAlert[] {
 
   return alertsJson.map(parseAlert)
 }
+
+/** Represents a single section in NWS formatted content */
+export interface NwsSection {
+  label: string
+  content: string
+}
+
+/** Result of parsing NWS WWWI format (What/Where/When/Impacts) */
+export interface NwsWwwiResult {
+  type: 'wwwi'
+  sections: NwsSection[]
+}
+
+/** Result of parsing NWS period-based forecast format */
+export interface NwsPeriodResult {
+  type: 'period'
+  preamble: string
+  periods: NwsSection[]
+}
+
+/** Result of parsing NWS text - either WWWI, period format, or plain text */
+export type NwsParseResult = NwsWwwiResult | NwsPeriodResult | null
+
+/**
+ * Checks if the CAP alert is from the National Weather Service (NWS).
+ * NWS alerts use the sender email: w-nws.webmaster@noaa.gov
+ *
+ * @param sender - The sender field from the CAP alert
+ * @returns true if the alert is from NWS
+ */
+export function isNwsAlert(sender: string): boolean {
+  return sender === 'w-nws.webmaster@noaa.gov'
+}
+
+/**
+ * Parses NWS "What/Where/When/Impacts" (WWWI) format used in Impact Based Warnings.
+ * Returns structured data with sections for rendering.
+ *
+ * Example input:
+ *   "* WHAT...North winds 25 to 30 kt. * WHERE...Pt St George to Cape Mendocino."
+ *
+ * @param text - The NWS text product description
+ * @returns Parsed WWWI result or null if format not detected
+ */
+export function parseNwsWwwiProduct(text: string): NwsWwwiResult | null {
+  if (!text) return null
+
+  // Check if this looks like an NWS WWWI format
+  const wwwiPattern =
+    /\*\s*(WHAT|WHERE|WHEN|IMPACTS?|ADDITIONAL DETAILS?)\.{3}/i
+  if (!wwwiPattern.test(text)) {
+    return null
+  }
+
+  // Split into sections
+  const sections: NwsSection[] = []
+  const sectionRegex =
+    /\*\s*(WHAT|WHERE|WHEN|IMPACTS?|ADDITIONAL DETAILS?)\.{3}\s*/gi
+  let match: RegExpExecArray | null
+
+  // Find all section markers and their positions
+  const matches: { label: string; index: number; length: number }[] = []
+  while ((match = sectionRegex.exec(text)) !== null) {
+    matches.push({
+      label: match[1],
+      index: match.index,
+      length: match[0].length,
+    })
+  }
+
+  // Extract content for each section
+  for (let i = 0; i < matches.length; i++) {
+    const current = matches[i]
+    const contentStart = current.index + current.length
+    const contentEnd =
+      i < matches.length - 1 ? matches[i + 1].index : text.length
+    const content = text.slice(contentStart, contentEnd).trim()
+
+    if (content) {
+      sections.push({ label: current.label, content })
+    }
+  }
+
+  if (sections.length === 0) {
+    return null
+  }
+
+  return { type: 'wwwi', sections }
+}
+
+/**
+ * Parses NWS text products that use the legacy .PERIOD... format
+ * commonly found in marine forecasts, zone forecasts, and CAP descriptions.
+ * Returns structured data with preamble and periods for rendering.
+ *
+ * Example input:
+ *   "Coastal Waters Forecast... .TODAY...E wind 20 kt. .TONIGHT...E wind 20 kt."
+ *
+ * @param text - The NWS text product description
+ * @returns Parsed period result or null if format not detected
+ */
+export function parseNwsPeriodProduct(text: string): NwsPeriodResult | null {
+  if (!text) return null
+
+  // Pattern to match period markers including "AND" combinations like ".SUN AND SUN NIGHT..."
+  const periodPattern =
+    /\.(TODAY|TONIGHT|TOMORROW|(?:MON|TUES|WEDNES|THURS|FRI|SATUR|SUN)(?:DAY)?|(?:MON|TUE|WED|THU|FRI|SAT|SUN))(\s+(?:AND\s+)?(?:NIGHT|MORNING|AFTERNOON|(?:MON|TUE|WED|THU|FRI|SAT|SUN)(?:\s+NIGHT)?|THROUGH\s+\w+))?\.{3}/gi
+
+  // Check if this looks like an NWS text product with .PERIOD... format
+  if (!periodPattern.test(text)) {
+    return null
+  }
+
+  // Reset regex lastIndex after test
+  periodPattern.lastIndex = 0
+
+  // Find the first period marker to split preamble from forecasts
+  const firstMatch = periodPattern.exec(text)
+  if (!firstMatch) {
+    return null
+  }
+
+  const preamble = text.slice(0, firstMatch.index).trim()
+
+  // Reset and find all period markers
+  periodPattern.lastIndex = 0
+  const periods: NwsSection[] = []
+  const matches: { label: string; index: number; length: number }[] = []
+  let match: RegExpExecArray | null
+
+  while ((match = periodPattern.exec(text)) !== null) {
+    const day = match[1]
+    const modifier = match[2] || ''
+    matches.push({
+      label: `${day}${modifier}`.trim(),
+      index: match.index,
+      length: match[0].length,
+    })
+  }
+
+  // Extract content for each period
+  for (let i = 0; i < matches.length; i++) {
+    const current = matches[i]
+    const contentStart = current.index + current.length
+    const contentEnd =
+      i < matches.length - 1 ? matches[i + 1].index : text.length
+    const content = text.slice(contentStart, contentEnd).trim()
+
+    if (content) {
+      periods.push({ label: current.label, content })
+    }
+  }
+
+  if (periods.length === 0) {
+    return null
+  }
+
+  return { type: 'period', preamble, periods }
+}
+
+/**
+ * Parses NWS text products for improved readability on digital signage.
+ * Detects format type and returns structured data:
+ * - Period-based forecasts: .TODAY..., .TONIGHT..., .MON..., etc.
+ * - Impact Based Warnings (WWWI): * WHAT..., * WHERE..., * WHEN..., * IMPACTS...
+ *
+ * @param text - The NWS text product description
+ * @returns Parsed result or null if no NWS format detected
+ */
+export function parseNwsTextProduct(text: string): NwsParseResult {
+  if (!text) return null
+
+  // Try WWWI format first (Impact Based Warnings)
+  const wwwiResult = parseNwsWwwiProduct(text)
+  if (wwwiResult) {
+    return wwwiResult
+  }
+
+  // Try period-based format (marine forecasts, etc.)
+  return parseNwsPeriodProduct(text)
+}