feat(PE-987): refactor examples by node version

.github/workflows/run-tests.yml

@@ -5,18 +5,22 @@ on: [push]
 jobs:
   install_and_test:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: ['14.17.6', '18']
     steps:
       - uses: actions/checkout@v4
         with:
             fetch-depth: 1
       - name: Fetch latest main branch commit
         run: git fetch --no-tags --depth=1 origin +refs/heads/main:refs/remotes/origin/main
-      - name: Use Node.js
+      - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v4
         with:
-          node-version: '14.17.6'
+          node-version: ${{ matrix.node-version }}
           cache: 'yarn'
-      - run: yarn --frozen-lockfile
+      - name: Install dependencies
+        run: yarn --frozen-lockfile --ignore-engines ${{ matrix.node-version == '14.17.6' && '--ignore-scripts' || '' }}
       - run: node ./scripts/workspace_actions.js test
 
   format_all:
@@ -31,12 +35,12 @@ jobs:
       - name: Use Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '14.17.6'
+          node-version: '18'
           cache: 'yarn'
-      - run: yarn --frozen-lockfile
+      - run: yarn --frozen-lockfile --ignore-engines
       - run: node ./scripts/workspace_actions.js format
       - name: Commit formatting changes
         uses: stefanzweifel/git-auto-commit-action@v5
         with:
             commit_message: Applied automatic formatting changes
-            branch: ${{ github.head_ref }}
+            branch: ${{ github.head_ref }}

.gitignore

@@ -4,4 +4,8 @@ dist
 package-lock.json
 .DS_Store
 prettiercache
-.npmrc
+.npmrc
+
+# Claude Code
+.claude/
+CLAUDE.md

CONTRIBUTING.md

@@ -11,6 +11,32 @@ Thank you for contributing to the BrightSign Dev Cookbook!
 We look forward to your contributions and suggestions!
 
 
+# Adding new examples
+
+When adding a new example, follow these conventions:
+
+1. **Place it in the correct subdirectory** based on its Node.js requirement:
+   - `examples/browser/` for HTML/BrightScript examples with no Node.js dependency
+   - `examples/node-14/` for examples targeting BrightSign OS 8.x (Node 14.17.6)
+   - `examples/node-18/` for examples requiring BrightSign OS 9.x (Node 18+)
+
+2. **Include an `.nvmrc` file** in every Node.js example declaring the minimum required version (e.g., `14.17.6` or `18`).
+
+3. **Add an `engines` field** in `package.json` (if the example has one):
+   ```json
+   "engines": {
+       "node": ">=18"
+   }
+   ```
+
+4. **Add version badges** at the top of the example's README, right after the title:
+   - Browser: `![Runtime: Browser](https://img.shields.io/badge/runtime-browser-blue)` and `![BrightSign OS: 8.x | 9.x](https://img.shields.io/badge/BrightSign_OS-8.x_%7C_9.x-purple)`
+   - Node on player: `![Node.js: >=18](https://img.shields.io/badge/node.js-%3E%3D18-green)` and `![BrightSign OS: 9.x](https://img.shields.io/badge/BrightSign_OS-9.x-purple)`
+   - Dev machine tool: `![Node.js: >=18](https://img.shields.io/badge/node.js-%3E%3D18-green)` and `![Runs on: Dev Machine](https://img.shields.io/badge/runs_on-dev_machine-orange)`
+
+5. **Update the compatibility matrix** in `examples/README.md` with the new example.
+
+
 # How to submit changes
 
 To contribute enhancements or fixes to `dev-cookbook`, please follow these steps:

README.md

@@ -55,11 +55,11 @@ The examples in this repository are designed to help you get started with develo
 
 ### Learning the basics with examples
 
-If you've never worked with a BrightSign before, we recommend starting with a [barebones example](examples/README.md#1-starter-html-example).
+If you've never worked with a BrightSign before, we recommend starting with the [HTML starter example](examples/browser/html-starter/README.md).
 
-After this, we recommend integrating Node.js into the application on the BrightSign player. An example of this can be found in [html_node_example](examples/node-simple-server-example/README.md).
+After this, we recommend integrating Node.js into the application on the BrightSign player. An example of this can be found in [node-simple-server](examples/node-14/node-simple-server/README.md).
 
-Once this seems familiar, we recommend adding auxiliary tools to make the development experience smoother. This includes introducing a script to copy files to the player's SD card, defining multiple environments to develop locally rather than needing to only rely on the player for visibility, and a mock library for populating values when running the example locally. This can be found [here](robust_example).
+Once this seems familiar, explore more advanced examples like the [self-updater](examples/node-18/bs-self-updater/README.md) or [provisioning server](examples/node-18/provisioning-server/README.md) to learn about deployment and fleet management.
 
 From here, we recommend using one of the templates to start developing your own project!
 
@@ -73,14 +73,19 @@ The templates in this repository are starter projects that you can use to begin
 
 The templates in this repository are intended for developers who are familiar with Node.js, React, and running scripts that connect to devices over a local network.
 
-We recommend managing your Node.js version using [nvm](https://github.com/nvm-sh/nvm/blob/master/README.md). The preferred version is `14.17.6` since this is the version currently pre-installed on most BrightSign devices.
+We recommend managing your Node.js version using [nvm](https://github.com/nvm-sh/nvm/blob/master/README.md). BrightSign devices ship with different Node.js versions depending on the OS:
+
+- **BrightSign OS 8.x**: Node.js `14.17.6`
+- **BrightSign OS 9.x**: Node.js `18`
+
+Each Node.js example includes an `.nvmrc` file. Run `nvm use` in the example directory to automatically switch to the correct version. See the [examples README](examples/README.md) for a full compatibility matrix.
 
 ## Project structure
 
 Here's an overview of the project structure and what each part is responsible for:
 
 - `templates/`         : React templates for new projects with custom configurations tailored for BrightSign development.
-- `examples/`          : A collection of examples demonstrating different capabilities and how to implement them on your BrightSign device.
+- `examples/`          : A collection of examples organized by runtime: `browser/` (HTML/BrightScript), `node-14/` (OS 8.x), and `node-18/` (OS 9.x).
 - `.github/`          : Contains GitHub Actions configurations for automated build and deployment processes.
 - `scripts/`          : Utility scripts to facilitate build, deployment, and development workflows.
 - `.eslintrc`         : Lint configuration to ensure code quality and consistency across the project.
@@ -100,7 +105,7 @@ Feel free to open an issue or submit a PR; see `CONTRIBUTING.MD` for further inf
 
 ## Building on M1 Mac
 
-You might see an error like `npm ERR! Error: Cannot find module 'node-bin-darwin-arm64/package.json'`
+When using Node 14.17.6 on Apple Silicon, you might see an error like `npm ERR! Error: Cannot find module 'node-bin-darwin-arm64/package.json'`
 
 Run the following commands:
 
@@ -113,7 +118,7 @@ arm64
 > nvm uninstall 14.17.6 && nvm install 14.17.6
 ```
 
-You might need to do this each time you restart your terminal.
+You might need to do this each time you restart your terminal. This issue does not affect Node 18+.
 
 For more details, see this [Stack Overflow thread](https://stackoverflow.com/questions/68896696/having-trouble-installing-npm-on-mac-m1).
 

examples/README.md

@@ -1,83 +1,57 @@
 # Examples
 
-Welcome to the examples directory! This guide will help you get started with the provided examples. Each example is independent and can be used based on your specific needs.
+Welcome to the examples directory! Each example is independent and can be used based on your specific needs.
 
-## Available Examples
+## Node Version Compatibility
 
-Note that some starter examples include the creation of a `brightsign-dumps` folder, which is used by the BrightSign OS to store crash information and is very useful to BrightSign Support when troubleshooting. The creation of this folder is an optional but recommended step to help with diagnosing application issues.
-
-### HTML & Web Storage Examples
-
-#### HTML Starter Example
-
--   **Location**: `examples/html-starter`
--   **Features**: Simple HTML application for BrightSign, demonstrates running HTML and displaying images using a static directory. Great for getting started with HTML on BrightSign.
-
-#### IndexedDB Caching Example
-
--   **Location**: `examples/indexeddb-caching`
--   **Features**: Demonstrates video caching using IndexedDB in a BrightSign HTML5 app. Implements a smart playlist and background caching for smooth video playback.
-
-#### Local Storage Example
-
--   **Location**: `examples/local-storage`
--   **Features**: Image slideshow that caches images in browser localStorage for persistent, smooth playback and looping.
-
-#### Large File Download Example
-
--   **Location**: `examples/large-file-download`
--   **Features**: Downloads large files (multi-GB) to SD card on memory-constrained players without OOM or UI blocking. Uses Node.js streams with TCP-level backpressure via `roHtmlWidget`.
+BrightSign players ship with different Node.js versions depending on the OS:
 
-### Node.js Examples
+- **BrightSign OS 8.x**: Node.js 14.17.6
+- **BrightSign OS 9.x**: Node.js 18
 
-#### Node Starter Example
+Examples are organized into subdirectories based on their runtime requirements:
 
--   **Location**: `examples/node-starter`
--   **Features**: Minimal Node.js HTTP server for BrightSign. Boots a simple server and responds to requests at the root endpoint.
+- **`browser/`** - HTML and BrightScript examples that run in the player's browser. No Node.js dependency.
+- **`node-14/`** - Node.js examples compatible with BrightSign OS 8.x (Node 14.17.6).
+- **`node-18/`** - Node.js examples requiring BrightSign OS 9.x (Node 18) or a dev machine with Node 18+.
 
-#### Node Simple Server Example
+Each Node.js example includes an `.nvmrc` file. Run `nvm use` in the example directory to switch to the correct version.
 
--   **Location**: `examples/node-simple-server`
--   **Features**: Advanced Node.js server with static file serving, device info REST API, Jest tests, and webpack config. Good for learning about full-featured Node.js deployments on BrightSign.
-
-### Deployment & Provisioning Examples
-
-#### autorun.zip Package Example
-
--   **Location**: `examples/autorun-zip-package`
--   **Features**: Complete example of creating and deploying an `autorun.zip` package for BrightSign players. Includes the `autozip.brs` unpacking script, sample application files, build script, and comprehensive documentation for Partner Gallery integration. Essential for CMS providers and partners deploying applications to fleets of BrightSign players.
-
-#### Provisioning Server Example
-
--   **Location**: `examples/provisioning-server`
--   **Features**: Docker-based provisioning server implementing BrightSign's provisioning protocol. Demonstrates automated content delivery to players on a local network with player tracking and deployment management.
-
-### Device & Plugin Integration Examples
-
-#### Bluetooth Scan Example
-
--   **Location**: `examples/bluetooth-scan`
--   **Features**: HTML+JS app for scanning Bluetooth devices on BrightSign. Requires a compatible Bluetooth adapter and uses BrightSign's proprietary JS API.
+Note that some starter examples include the creation of a `brightsign-dumps` folder, which is used by the BrightSign OS to store crash information and is very useful to BrightSign Support when troubleshooting. The creation of this folder is an optional but recommended step to help with diagnosing application issues.
 
-#### BS Self Updater Example
+## Compatibility Matrix
 
--   **Location**: `examples/bs-self-updater`
--   **Features**: TypeScript utility for self-updating BrightSign apps by downloading and applying new `autorun.zip` packages from a server. Works in conjunction with the autorun.zip package example.
+### Browser Examples (`browser/`)
 
-#### BS SQLite DB Example
+| Example | Description | BrightSign OS |
+|---------|-------------|---------------|
+| [html-starter](browser/html-starter) | Simple HTML app, displays images using a static directory | 8.x, 9.x |
+| [indexeddb-caching](browser/indexeddb-caching) | Video caching using IndexedDB with smart playlist and background caching | 8.x, 9.x |
+| [local-storage](browser/local-storage) | Image slideshow with localStorage caching for persistent playback | 8.x, 9.x |
+| [bluetooth-scan](browser/bluetooth-scan) | Bluetooth device scanning using BrightSign's JS API | 8.x, 9.x |
+| [bs-sqlite-db](browser/bs-sqlite-db) | SQLite database usage with BrightScript/JavaScript communication | 8.x, 9.x |
+| [cec-interface](browser/cec-interface) | CEC commands via BrightScript and JavaScript implementations | 8.x, 9.x |
+| [enable-ldws](browser/enable-ldws) | Enable Local Diagnostic Web Server with multiple approaches | 8.x, 9.x |
+| [htmlwidget-iframes](browser/htmlwidget-iframes) | HTML widgets with iframes and security configuration | 8.x, 9.x |
+| [send-plugin-message](browser/send-plugin-message) | Plugin message communication between BrightScript and HTML/JS | 8.x, 9.x |
+| [syncmanager-js](browser/syncmanager-js) | Multi-player content synchronization using SyncManager JS API | 8.x, 9.x |
+| [large-file-download](browser/large-file-download) | Memory-bounded multi-GB download using Node streams in roHtmlWidget | 8.x, 9.x |
 
--   **Location**: `examples/bs-sqlite-db`
--   **Features**: Demonstrates SQLite database usage on BrightSign, including table creation, data insertion, querying, and cleanup via BrightScript and JavaScript communication.
 
-#### Send Plugin Message Example
+### Node.js 14 Examples (`node-14/`)
 
--   **Location**: `examples/send-plugin-message`
--   **Features**: Shows how to send plugin messages between BrightScript and HTML/JavaScript apps, useful for integrating BrightAuthor:connected presentations with custom logic.   
+| Example | Description | Node Version | Runs On |
+|---------|-------------|-------------|---------|
+| [node-starter](node-14/node-starter) | Minimal Node.js HTTP server for BrightSign | 14.17.6 | Player |
+| [node-simple-server](node-14/node-simple-server) | Advanced Node.js server with REST API, Jest tests, and webpack | 14.17.6 | Player |
 
-#### Syncmanager Example
+### Node.js 18 Examples (`node-18/`)
 
--   **Location**: `examples/syncmanager`
--   **Features**: Demonstrates using BrightSign's `@brightsign/syncmanager` JS API for synchronizing content across multiple players.
+| Example | Description | Node Version | Runs On |
+|---------|-------------|-------------|---------|
+| [bs-self-updater](node-18/bs-self-updater) | TypeScript self-updating app that downloads and applies new autorun.zip packages | >=18 | Player |
+| [provisioning-server](node-18/provisioning-server) | Docker-based provisioning server implementing BrightSign's provisioning protocol | >=18 | Dev Machine |
+| [self-signed-certs](node-18/self-signed-certs) | Self-signed certificate handling using native fetch and undici | >=18 | Dev Machine |
 
 ## Next Steps
 
@@ -86,3 +60,4 @@ After exploring these examples, you can:
 1. Combine concepts from different examples to build more complex applications
 2. Add testing to your applications following the `node-simple-server` example
 3. Implement plugin message communication for advanced BrightScript integration
+4. Use one of the [templates](../templates) to start a production project

examples/bluetooth-scan/README.md → examples/browser/bluetooth-scan/README.md

@@ -1,5 +1,8 @@
 # Bluetooth scan example on BrightSign players
 
+![Runtime: Browser](https://img.shields.io/badge/runtime-browser-blue)
+![BrightSign OS: 8.x | 9.x](https://img.shields.io/badge/BrightSign_OS-8.x_%7C_9.x-purple)
+
 ## Introduction
 
 The intention of this example is to show how to get a Bluetooth scanning application (HTML+JS) running on your BrightSign player.

examples/bs-sqlite-db/README.md → examples/browser/bs-sqlite-db/README.md

@@ -1,5 +1,8 @@
 # BrightSign SQLite Database Example
 
+![Runtime: Browser](https://img.shields.io/badge/runtime-browser-blue)
+![BrightSign OS: 8.x | 9.x](https://img.shields.io/badge/BrightSign_OS-8.x_%7C_9.x-purple)
+
 This example demonstrates how to use SQLite database functionality in a BrightSign application, showing the communication between BrightScript and JavaScript for database operations.
 
 ## Overview

examples/browser/cec-interface/README.md

@@ -0,0 +1,9 @@
+# CEC Interface Examples
+
+![Runtime: Browser](https://img.shields.io/badge/runtime-browser-blue)
+![BrightSign OS: 8.x | 9.x](https://img.shields.io/badge/BrightSign_OS-8.x_%7C_9.x-purple)
+
+Examples demonstrating CEC (Consumer Electronics Control) on BrightSign devices. Two implementations are provided:
+
+- [BrightScript implementation](brightscript/README.md)
+- [JavaScript implementation](javascript/README.md)

examples/cec-interface/brightscript/README.md → examples/browser/cec-interface/brightscript/README.md

@@ -1,5 +1,8 @@
 # BrightScript CEC Example
 
+![Runtime: Browser](https://img.shields.io/badge/runtime-browser-blue)
+![BrightSign OS: 8.x | 9.x](https://img.shields.io/badge/BrightSign_OS-8.x_%7C_9.x-purple)
+
 This example demonstrates how to send CEC (Consumer Electronics Control) commands using BrightScript on BrightSign devices.
 
 ## What it does

examples/cec-interface/javascript/README.md → examples/browser/cec-interface/javascript/README.md

@@ -1,5 +1,8 @@
 # JavaScript CEC Example
 
+![Runtime: Browser](https://img.shields.io/badge/runtime-browser-blue)
+![BrightSign OS: 8.x | 9.x](https://img.shields.io/badge/BrightSign_OS-8.x_%7C_9.x-purple)
+
 This example demonstrates how to send and receive CEC (Consumer Electronics Control) commands using JavaScript on BrightSign devices.
 
 ## What it does

examples/enable-ldws/README.md → examples/browser/enable-ldws/README.md

@@ -1,5 +1,8 @@
 # Enable Local Diagnostic Web Server (LDWS) Example
 
+![Runtime: Browser](https://img.shields.io/badge/runtime-browser-blue)
+![BrightSign OS: 8.x | 9.x](https://img.shields.io/badge/BrightSign_OS-8.x_%7C_9.x-purple)
+
 ## Introduction
 
 This example demonstrates three different methods to enable and configure the Local Diagnostic Web Server (LDWS) on a BrightSign device. The LDWS provides a web interface for device diagnostics, monitoring, and configuration that can be accessed from a web browser on the same network.

examples/html-starter/README.md → examples/browser/html-starter/README.md

@@ -1,5 +1,8 @@
 # Example HTML App
 
+![Runtime: Browser](https://img.shields.io/badge/runtime-browser-blue)
+![BrightSign OS: 8.x | 9.x](https://img.shields.io/badge/BrightSign_OS-8.x_%7C_9.x-purple)
+
 ## Introduction
 
 This example is the first stepping stone of the starter examples to get familiar with developing with a BrightSign. The intention of this example is to show how to get a simple HTML application running on your player.

examples/htmlwidget-iframes/README.md → examples/browser/htmlwidget-iframes/README.md

@@ -1,5 +1,8 @@
 # HTML Widget Iframes Example
 
+![Runtime: Browser](https://img.shields.io/badge/runtime-browser-blue)
+![BrightSign OS: 8.x | 9.x](https://img.shields.io/badge/BrightSign_OS-8.x_%7C_9.x-purple)
+
 To enhance security, the BrightSign OS has disabled the access to JavaScript APIs, BS-JS objects, and Node.js within iframes in BOS v9.1. However, a security parameter `trusted_iframes_enabled` has been added to the `roHtmlWidget` configuration, which will enable iframes to have access to that functionality. We DO NOT recommend this configuration as the content in these iframes can gain access to core player APIs, and this content is not always under the application's control.
 
 See the following pages for details:

examples/indexeddb-caching/README.md → examples/browser/indexeddb-caching/README.md

@@ -1,5 +1,8 @@
 # IndexedDB Video Caching Example
 
+![Runtime: Browser](https://img.shields.io/badge/runtime-browser-blue)
+![BrightSign OS: 8.x | 9.x](https://img.shields.io/badge/BrightSign_OS-8.x_%7C_9.x-purple)
+
 This example demonstrates how to use IndexedDB for caching video content in a BrightSign HTML5 application. The application creates a video playlist that intelligently caches videos in the background for smooth playback.
 
 ## File Structure

examples/large-file-download/README.md → examples/browser/large-file-download/README.md

@@ -1,5 +1,8 @@
 # Large File Download Example
 
+![Runtime: Browser](https://img.shields.io/badge/runtime-browser-blue)
+![BrightSign OS: 8.x | 9.x](https://img.shields.io/badge/BrightSign_OS-8.x_%7C_9.x-purple)
+
 ## Introduction
 
 This example demonstrates how to download a large file (multi-GB) to an SD card on a memory-constrained BrightSign player without running out of memory or blocking the UI.