CastConductor Changelog

All notable changes to CastConductor are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[vdefine('CASTCONDUCTOR_VERSION', '5.7.25-202601141142');] - 2026-01-14 (Build 279)

Branch: 2026-0112/roku-submission

[vdefine('CASTCONDUCTOR_VERSION', '5.7.25-202601131211');] - 2026-01-13 (Build 278)

Branch: 2026-0112/roku-submission

[vdefine('CASTCONDUCTOR_VERSION', '5.7.25-202601131111');] - 2026-01-13 (Build 277)

Branch: 2026-0112/roku-submission

[v5.7.25i] - 2026-01-13 (Build 276)

Branch: 2026-0112/roku-submission

[v5.7.25h] - 2026-01-13 (Build 275)

Branch: 2026-0112/roku-submission

[v5.7.25g] - 2026-01-13 (Build 274)

Branch: 2026-0112/roku-submission

[v5.7.25f] - 2026-01-13 (Build 273)

Branch: 2026-0112/roku-submission

[v5.7.25e] - 2026-01-13 (Build 272)

Branch: 2026-0112/roku-submission

[v5.7.25d] - 2026-01-13 (Build 271)

Branch: 2026-0112/roku-submission

[v5.7.25] - 2026-01-12 (Build 266)

Branch: 2026-0112/roku-submission

Added

CPT Visual Config Rendering: Roku app now uses custom visual_config from CPT posts (sponsors/promos/shoutouts)
End-to-End CPT Editing Flow: Admin edits CPT → saves to post meta → API serves visual_config → Roku renders it

Changed

BaseContentBlock.brs: Added visual_config override checks in both onWordPressContentReceived() and onRefreshTriggered()
CPT visual edits now flow through to Roku without requiring new Content Block creation

Technical Details

onWordPressContentReceived() (line 1172): Checks for currentItem.visual_config after fetching WordPress content
onRefreshTriggered() (line 96): Checks for visual_config during content rotation
Both functions override m.visualConfig with CPT's custom config when present
Enables full visual customization of sponsors, promos, and shoutouts directly from their original CPT posts

[v5.7.24] - 2026-01-08 (Build 240)

Branch: 2026-0104/isolated-wordpress-user-demo

Summary

Implement pre-warmed demo pool for instant provisioning

Changed

demo/mu-plugins/cc-demo-provisioner.php:
Added POOL_SIZE, META_KEY_IS_POOL, META_KEY_POOL_CLAIMED constants
Added pool replenishment cron hook (every_five_minutes)
Added claim_from_pool(), create_pool_site(), replenish_demo_pool()
Modified provision_demo_site() to try pool first
Added cleanup for stale pool sites (24h expiry)

[v5.7.23] - 2026-01-08 (Build 239)

Branch: 2026-0104/isolated-wordpress-user-demo

Summary

Clone CastConductor custom post types (shoutouts, sponsors, promos) to sub-sites

Changed

demo/mu-plugins/cc-demo-provisioner.php: Added clone_custom_post_types_to_subsite() and call in seed_demo_content()

[v5.7.22b] - 2026-01-08 (Build 238)

Branch: 2026-0104/isolated-wordpress-user-demo

Summary

Clone CastConductor custom post types (shoutouts, sponsors, promos) to sub-sites

Changed

demo/mu-plugins/cc-demo-provisioner.php: Added clone_custom_post_types_to_subsite() and call in seed_demo_content()

[v5.7.22] - 2026-01-08 (Build 237)

Branch: 2026-0104/isolated-wordpress-user-demo

Summary

Fix uploads not persisting - Docker volumes don't survive commit!

Changed

demo/commit-base.sh: Export uploads to demo/uploads-snapshot/ before commit
Dockerfile.demo: COPY uploads-snapshot into image at /usr/src/uploads-snapshot/
demo/demo-entrypoint.sh: Restore uploads from snapshot on startup
demo/uploads-snapshot/.gitkeep: Empty placeholder for git
.gitignore: Ignore uploads-snapshot contents (not tracked in git)

[v5.7.21e] - 2026-01-05 (Build 236)

Branch: 2026-0104/isolated-wordpress-user-demo

Summary

Reorganize demo scripts into /demo directory

Fixed

Fixed build-base.sh Docker context path issue (was using temp file directory instead of project root)
Changed context: . to context: ${PROJECT_ROOT} so Docker can find Dockerfile and source files
Added PROJECT_ROOT variable to both rebuild.sh and build-base.sh

Updated Aliases

Updated setup-prod.sh aliases to point to new locations: - cc-demo-rebuild → ./demo/rebuild.sh - cc-demo-rebuild-nocache → ./demo/rebuild.sh --no-cache - cc-demo-rebuild-wipe → ./demo/rebuild.sh --wipe --no-cache - cc-demo-build-base (NEW) → ./demo/build-base.sh

Changed

demo/rebuild.sh: Moved from root, added PROJECT_ROOT variable
demo/build-base.sh: Moved from root, fixed Docker context path
demo/Dockerfile.base: Moved from root
demo/deprecated/: New directory for deprecated scripts
setup-prod.sh: Updated demo aliases + added cc-demo-build-base

[v5.7.21d] - 2026-01-05 (Build 235)

Branch: 2026-0104/isolated-wordpress-user-demo

[v5.7.21c] - 2026-01-04 (Build 234)

Branch: 2026-0104/isolated-wordpress-user-demo

Summary

Complete Multisite demo setup with working database snapshot

Added

demo/demo-snapshot.sql: Complete WordPress Multisite database dump (171KB) containing:
wp_blogs, wp_blogmeta, wp_site, wp_sitemeta (Multisite tables)
All CastConductor tables (containers, content_blocks, scenes, menus, etc.)
Default containers, backgrounds, and content block seeds
Demo admin user credentials

Fixed

demo/demo-init.sh:
Replaced mysqladmin database check with PHP mysqli (avoids SSL/client compatibility issues)
Simplified init logic to detect existing tables vs fresh install
Removed premature multisite-convert call (done manually after single-site install)
docker-compose.demo.yml:
Added --skip-ssl to MySQL command to disable internal SSL requirement
Restored Multisite constants now that database snapshot matches config
demo/wp-config-demo.php:
Restored Multisite constants with if (!defined()) guards to prevent conflicts
Constants now match the exported database snapshot

Technical Details

SSL Issue: MySQL 8.0 enables SSL by default; MariaDB client in WordPress container requires --ssl-mode flag that doesn't exist. Fixed by disabling SSL on server side (internal Docker network doesn't need encryption).
Bootstrap Sequence: Multisite constants in wp-config before database has tables causes WordPress to query non-existent wp_blogs table. Solved by creating snapshot with tables first, then restoring constants.
Snapshot Export: Used docker exec demo-demo-db-1 mysqldump directly instead of WP-CLI to avoid client SSL issues.

[v5.7.21b] - 2026-01-04 (Build 233)

Branch: 2026-0104/isolated-wordpress-user-demo

Summary

Complete Multisite demo setup with working database snapshot

Added

demo/demo-snapshot.sql: Complete WordPress Multisite database dump (171KB) containing:
wp_blogs, wp_blogmeta, wp_site, wp_sitemeta (Multisite tables)
All CastConductor tables (containers, content_blocks, scenes, menus, etc.)
Default containers, backgrounds, and content block seeds
Demo admin user credentials

Fixed

demo/demo-init.sh:
Replaced mysqladmin database check with PHP mysqli (avoids SSL/client compatibility issues)
Simplified init logic to detect existing tables vs fresh install
Removed premature multisite-convert call (done manually after single-site install)
docker-compose.demo.yml:
Added --skip-ssl to MySQL command to disable internal SSL requirement
Restored Multisite constants now that database snapshot matches config
demo/wp-config-demo.php:
Restored Multisite constants with if (!defined()) guards to prevent conflicts
Constants now match the exported database snapshot

Technical Details

SSL Issue: MySQL 8.0 enables SSL by default; MariaDB client in WordPress container requires --ssl-mode flag that doesn't exist. Fixed by disabling SSL on server side (internal Docker network doesn't need encryption).
Bootstrap Sequence: Multisite constants in wp-config before database has tables causes WordPress to query non-existent wp_blogs table. Solved by creating snapshot with tables first, then restoring constants.
Snapshot Export: Used docker exec demo-demo-db-1 mysqldump directly instead of WP-CLI to avoid client SSL issues.

[v5.7.21] - 2026-01-04 (Build 232)

Branch: 2026-0104/isolated-wordpress-user-demo

Summary

Complete Multisite demo setup with working database snapshot

Added

demo/demo-snapshot.sql: Complete WordPress Multisite database dump (171KB) containing:
wp_blogs, wp_blogmeta, wp_site, wp_sitemeta (Multisite tables)
All CastConductor tables (containers, content_blocks, scenes, menus, etc.)
Default containers, backgrounds, and content block seeds
Demo admin user credentials

Fixed

demo/demo-init.sh:
Replaced mysqladmin database check with PHP mysqli (avoids SSL/client compatibility issues)
Simplified init logic to detect existing tables vs fresh install
Removed premature multisite-convert call (done manually after single-site install)
docker-compose.demo.yml:
Added --skip-ssl to MySQL command to disable internal SSL requirement
Restored Multisite constants now that database snapshot matches config
demo/wp-config-demo.php:
Restored Multisite constants with if (!defined()) guards to prevent conflicts
Constants now match the exported database snapshot

Technical Details

SSL Issue: MySQL 8.0 enables SSL by default; MariaDB client in WordPress container requires --ssl-mode flag that doesn't exist. Fixed by disabling SSL on server side (internal Docker network doesn't need encryption).
Bootstrap Sequence: Multisite constants in wp-config before database has tables causes WordPress to query non-existent wp_blogs table. Solved by creating snapshot with tables first, then restoring constants.
Snapshot Export: Used docker exec demo-demo-db-1 mysqldump directly instead of WP-CLI to avoid client SSL issues.

[v5.7.20c] - 2026-01-04 (Build 230)

Branch: 2026-0104/isolated-wordpress-user-demo

Summary

Track plugin ZIP in git for production demo deployment

Added

app-builds/wp/castconductor-plugin.zip: Now tracked in git (1.9MB). Will be updated whenever wp-package.sh runs.

Changed

.gitignore: Added negation rules to track app-builds/wp/castconductor-plugin.zip in git. This file is required by Dockerfile.demo to bake the CastConductor plugin into the demo container. Previously ignored, causing demo build to fail on production.

[v5.7.20b] - 2026-01-04 (Build 229)

Branch: 2026-0104/isolated-wordpress-user-demo

Summary

Fix sync-changelog.sh set -e failures and bump version to 5.7.20

Fixed

mkdocs/sync-changelog.sh: Fixed two set -e issues causing script to exit prematurely:
grep -q returns exit code 1 when not found, triggering set -e. Added || : pattern to catch exit code.
((entry_count++)) returns exit code 1 when pre-increment value is 0 (bash arithmetic treats 0 as false). Added || : to prevent exit.

Changed

plugins/castconductor-v5/castconductor.php: Bumped to v5.7.20 (Build 228)
package.json: Updated version to 5.7.20
roku-app/manifest: Updated version to 5.7.20, build 228
provisioning-api/server.js: Updated version to 5.7.20
CHANGELOG.md: Added v5.7.20 entry from handoff doc
mkdocs/docs/changelog.md: Synced from CHANGELOG.md

[v5.7.20] - 2026-01-04 (Build 228)

Branch: 2026-0104/isolated-wordpress-user-demo

Summary

Fix PHP syntax error in demo-cleanup.php

Fixed

demo/demo-cleanup.php: Fixed PHP parse error caused by */15 cron syntax in docblock comment. PHP interpreted */ as closing the multi-line comment. Changed to 0,15,30,45 (equivalent cron expression).

[v5.7.19j] - 2026-01-02 (Build 224)

Branch: 2025-1230/plugin-updates

Summary

Theme pack documentation polish - Toaster font upload, Featured+Grid presets, starter template download, FAQ section; Complete theme pack SDK documentation with JSON schema, container presets reference, and backlog update for Theme Pack Import UI; Major plugin update UX improvements, MKDocs enhancements, legal page updates, and documentation polish; Expanded doc sync to mirror additional legal/contributing pages; added privacy and terms drafts; Fixed changelog extractor to properly parse full handoff entries with all sections; Integrated changelog sync into bump-version.sh with automatic handoff doc extraction

Added

mkdocs/docs/assets/downloads/theme-pack-starter.zip: Downloadable theme pack starter template with theme.json, README.md, and folder structure for assets/backgrounds, assets/overlays, preview
mkdocs/docs/assets/downloads/theme-pack-starter/: Source files for starter template (gitignored, only ZIP committed)
mkdocs/docs/contributing.md: Added FAQ section covering token layer styling, layer count limits, custom container geometry
schemas/theme-pack.schema.json: Complete JSON Schema (draft-07) for validating theme packs. Includes: required fields (name, version, author, description), color palette with hex validation, typography with Roku system font enums, container styling overrides, widget configuration, Roku-specific rendering hints. Supports theme inheritance via extends key.
docs/EXTENSION-SPEC.md: 3rd party extension specification covering Theme Packs (JSON schema), Content Block Types (PHP API), Integrations (webhooks/sync), REST API extensions, Roku rendering output format.
mkdocs/overrides/partials/copyright.html: Dynamic copyright year using {{ now().year }} - auto-updates annually
mkdocs/overrides/partials/footer.html: Custom footer partial for Material theme
class-castconductor-update-checker.php: "Check for Updates" button in admin notice with spinning refresh icon
mkdocs/mkdocs.yml: Main website link (globe icon) added to footer social links
mkdocs/docs/privacy.md: Draft Privacy Policy page with sections for data collection, usage, Roku app data, GDPR rights
mkdocs/docs/terms.md: Draft Terms of Service page with acceptable use, IP, liability disclaimers
mkdocs/mkdocs.yml: Added "Legal" nav section with Terms, Privacy, License, Third Party Notices; Contributing page

Fixed

mkdocs/sync-changelog.sh: Rewrote extract_from_handoff() function to properly parse handoff doc structure
Now correctly detects ### Added, ### Fixed, ### Changed, ### Removed, ### Technical section headers
Accumulates content under each section until next section or entry boundary
Skips ### Commit Bullets section (not relevant for public changelog)
Properly handles multi-entry handoff docs by merging summaries
Checks for version duplicates BEFORE parsing (faster failure)
Removed old line-by-line keyword matching that was too simplistic

Changed

mkdocs/docs/contributing.md:
Replaced generic "Contact CastConductor" font workaround with Toaster font upload explanation (upload TTF/OTF in Settings → Roku App, fonts bundled at build time)
Added Featured + Grid layout presets (Featured Hero 1280×480 + 4 Grid Items 320×240)
Added featured_grid_* container keys to JSON example
Replaced vague "widgets" terminology with "defaults" (content block type defaults)
Updated download button to link to actual theme-pack-starter.zip
schemas/theme-pack.schema.json: Renamed "widgets" to "defaults" with proper descriptions for clock/weather content block defaults
.gitignore: Added mkdocs/docs/assets/downloads/theme-pack-starter/ to exclude unzipped folder
mkdocs/docs/contributing.md: Complete rewrite with full theme pack development guide including:
Theme Pack Licensing model (devs keep 100%, link to own stores like Gumroad)
Theme directory concept (free listings at themes.castconductor.com)
Full theme.json specification with all fields documented
All 16 container presets with dimensions, positions, and use cases
Roku font limitations (system fonts only) with workarounds
Theme inheritance via extends key
Asset guidelines with size recommendations
Versioning strategy (manual re-import now, auto-notify later)
Publishing process (email submission workflow)
docs/BACKLOG.md: Added "Theme Pack Import UI" as new high priority item with detailed spec (upload ZIP, validate against schema, theme gallery with preview thumbnails, activate/delete functionality). Marked "Theme Pack JSON Spec" as Complete.
class-castconductor-update-checker.php: Enabled one-click install from WordPress Plugins page ($item->package now contains download URL)
castconductor.php: Fixed Plugin URI to point to https://castconductor.com instead of direct ZIP download
mkdocs/docs/privacy.md: Updated to clarify we don't collect channel content or analytics (stored in user's installation); added GDPR and CCPA sections
mkdocs/docs/terms.md: Rewrote to reflect we don't host content; added Roku disclaimers, copyright responsibility, non-refundable setup fees, trademark attribution
mkdocs/docs/contributing.md: Replaced internal AI guidance doc with public-facing theme pack development guide
mkdocs/sync-changelog.sh: Removed sync of DEVELOPMENT-GUIDELINES.md (internal doc); contributing.md now maintained directly
mkdocs/mkdocs.yml: Copyright now dynamic via override partial (removed hardcoded 2025)
docs/BACKLOG.md: Added "Theme Pack JSON Spec" to high priority items
mkdocs/sync-changelog.sh: Expanded to sync multiple docs from repo to mkdocs:
CHANGELOG.md → docs/changelog.md
docs/DEVELOPMENT-GUIDELINES.md → docs/contributing.md
LICENSE-HEADER.txt → docs/license.md (wrapped in code block)
THIRD-PARTY-NOTICES.md → docs/third-party-notices.md
mkdocs/sync-changelog.sh: Enhanced to support --from-handoff flag that extracts changelog entries from handoff docs
Auto-detects today's date in YYYY-MMDD format to find matching handoff file
Parses entries and categorizes into Added/Fixed/Changed/Removed/Technical sections
Checks for duplicate versions before inserting to prevent overwrites
Syncs main CHANGELOG.md to mkdocs/docs/changelog.md
scripts/bump-version.sh: Added Step 2 (Sync Changelog) to the deployment pipeline
Now 5 steps: (1) Update versions → (2) Sync changelog → (3) Commit/push → (4) Deploy plugin → (5) Update prod API
Automatically runs sync-changelog.sh with --from-handoff flag during version bump
Uses dynamic date detection to find current day's handoff doc

Technical Details

Schema validates: semantic versioning pattern, hex colors with optional alpha, font enum restricted to Roku system fonts, container/widget configurations
All 16 container presets documented: Full Screen, Upper/Center/Lower Third, Left/Right Half, Horizontal Upper/Lower Half, 4 Quarters, 4 Horizontal Quarters
Contributing guide now public-facing for 3rd party theme developers
Tagged v5.7.19h as stable checkpoint before GitHub tag pruning
Plugin update checker now clears WP transient and reloads page on refresh button click
Footer social links order: Website → Community Forum

[v5.7.19i] - 2026-01-02 (Build 222)

Branch: 2025-1230/plugin-updates

Summary

Major plugin update UX improvements, MKDocs enhancements, legal page updates, and documentation polish; Expanded doc sync to mirror additional legal/contributing pages; added privacy and terms drafts; Fixed changelog extractor to properly parse full handoff entries with all sections; Integrated changelog sync into bump-version.sh with automatic handoff doc extraction

Added

mkdocs/overrides/partials/copyright.html: Dynamic copyright year using {{ now().year }} - auto-updates annually
mkdocs/overrides/partials/footer.html: Custom footer partial for Material theme
class-castconductor-update-checker.php: "Check for Updates" button in admin notice with spinning refresh icon
mkdocs/mkdocs.yml: Main website link (globe icon) added to footer social links
mkdocs/docs/privacy.md: Draft Privacy Policy page with sections for data collection, usage, Roku app data, GDPR rights
mkdocs/docs/terms.md: Draft Terms of Service page with acceptable use, IP, liability disclaimers
mkdocs/mkdocs.yml: Added "Legal" nav section with Terms, Privacy, License, Third Party Notices; Contributing page

Fixed

mkdocs/sync-changelog.sh: Rewrote extract_from_handoff() function to properly parse handoff doc structure
Now correctly detects ### Added, ### Fixed, ### Changed, ### Removed, ### Technical section headers
Accumulates content under each section until next section or entry boundary
Skips ### Commit Bullets section (not relevant for public changelog)
Properly handles multi-entry handoff docs by merging summaries
Checks for version duplicates BEFORE parsing (faster failure)
Removed old line-by-line keyword matching that was too simplistic

Changed

class-castconductor-update-checker.php: Enabled one-click install from WordPress Plugins page ($item->package now contains download URL)
castconductor.php: Fixed Plugin URI to point to https://castconductor.com instead of direct ZIP download
mkdocs/docs/privacy.md: Updated to clarify we don't collect channel content or analytics (stored in user's installation); added GDPR and CCPA sections
mkdocs/docs/terms.md: Rewrote to reflect we don't host content; added Roku disclaimers, copyright responsibility, non-refundable setup fees, trademark attribution
mkdocs/docs/contributing.md: Replaced internal AI guidance doc with public-facing theme pack development guide
mkdocs/sync-changelog.sh: Removed sync of DEVELOPMENT-GUIDELINES.md (internal doc); contributing.md now maintained directly
mkdocs/mkdocs.yml: Copyright now dynamic via override partial (removed hardcoded 2025)
docs/BACKLOG.md: Added "Theme Pack JSON Spec" to high priority items
mkdocs/sync-changelog.sh: Expanded to sync multiple docs from repo to mkdocs:
CHANGELOG.md → docs/changelog.md
docs/DEVELOPMENT-GUIDELINES.md → docs/contributing.md
LICENSE-HEADER.txt → docs/license.md (wrapped in code block)
THIRD-PARTY-NOTICES.md → docs/third-party-notices.md
mkdocs/sync-changelog.sh: Enhanced to support --from-handoff flag that extracts changelog entries from handoff docs
Auto-detects today's date in YYYY-MMDD format to find matching handoff file
Parses entries and categorizes into Added/Fixed/Changed/Removed/Technical sections
Checks for duplicate versions before inserting to prevent overwrites
Syncs main CHANGELOG.md to mkdocs/docs/changelog.md
scripts/bump-version.sh: Added Step 2 (Sync Changelog) to the deployment pipeline
Now 5 steps: (1) Update versions → (2) Sync changelog → (3) Commit/push → (4) Deploy plugin → (5) Update prod API
Automatically runs sync-changelog.sh with --from-handoff flag during version bump
Uses dynamic date detection to find current day's handoff doc

Technical Details

Tagged v5.7.19h as stable checkpoint before GitHub tag pruning
Plugin update checker now clears WP transient and reloads page on refresh button click
Footer social links order: Website → Community Forum

[v5.7.19c] - 2026-01-02 (Build 216)

Branch: 2025-1230/plugin-updates

Summary

Expanded doc sync to mirror additional legal/contributing pages; added privacy and terms drafts; Fixed changelog extractor to properly parse full handoff entries with all sections; Integrated changelog sync into bump-version.sh with automatic handoff doc extraction

Added

mkdocs/docs/privacy.md: Draft Privacy Policy page with sections for data collection, usage, Roku app data, GDPR rights
mkdocs/docs/terms.md: Draft Terms of Service page with acceptable use, IP, liability disclaimers
mkdocs/mkdocs.yml: Added "Legal" nav section with Terms, Privacy, License, Third Party Notices; Contributing page

Fixed

mkdocs/sync-changelog.sh: Rewrote extract_from_handoff() function to properly parse handoff doc structure
Now correctly detects ### Added, ### Fixed, ### Changed, ### Removed, ### Technical section headers
Accumulates content under each section until next section or entry boundary
Skips ### Commit Bullets section (not relevant for public changelog)
Properly handles multi-entry handoff docs by merging summaries
Checks for version duplicates BEFORE parsing (faster failure)
Removed old line-by-line keyword matching that was too simplistic

Changed

mkdocs/sync-changelog.sh: Expanded to sync multiple docs from repo to mkdocs:
CHANGELOG.md → docs/changelog.md
docs/DEVELOPMENT-GUIDELINES.md → docs/contributing.md
LICENSE-HEADER.txt → docs/license.md (wrapped in code block)
THIRD-PARTY-NOTICES.md → docs/third-party-notices.md
mkdocs/sync-changelog.sh: Enhanced to support --from-handoff flag that extracts changelog entries from handoff docs
Auto-detects today's date in YYYY-MMDD format to find matching handoff file
Parses entries and categorizes into Added/Fixed/Changed/Removed/Technical sections
Checks for duplicate versions before inserting to prevent overwrites
Syncs main CHANGELOG.md to mkdocs/docs/changelog.md
scripts/bump-version.sh: Added Step 2 (Sync Changelog) to the deployment pipeline
Now 5 steps: (1) Update versions → (2) Sync changelog → (3) Commit/push → (4) Deploy plugin → (5) Update prod API
Automatically runs sync-changelog.sh with --from-handoff flag during version bump
Uses dynamic date detection to find current day's handoff doc

[v5.7.19b] - 2026-01-02 (Build 215)

Branch: 2025-1230/plugin-updates

Summary

Fixed changelog extractor to properly parse full handoff entries with all sections; Integrated changelog sync into bump-version.sh with automatic handoff doc extraction

Fixed

mkdocs/sync-changelog.sh: Rewrote extract_from_handoff() function to properly parse handoff doc structure
Now correctly detects ### Added, ### Fixed, ### Changed, ### Removed, ### Technical section headers
Accumulates content under each section until next section or entry boundary
Skips ### Commit Bullets section (not relevant for public changelog)
Properly handles multi-entry handoff docs by merging summaries
Checks for version duplicates BEFORE parsing (faster failure)
Removed old line-by-line keyword matching that was too simplistic

Changed

mkdocs/sync-changelog.sh: Enhanced to support --from-handoff flag that extracts changelog entries from handoff docs
Auto-detects today's date in YYYY-MMDD format to find matching handoff file
Parses entries and categorizes into Added/Fixed/Changed/Removed/Technical sections
Checks for duplicate versions before inserting to prevent overwrites
Syncs main CHANGELOG.md to mkdocs/docs/changelog.md
scripts/bump-version.sh: Added Step 2 (Sync Changelog) to the deployment pipeline
Now 5 steps: (1) Update versions → (2) Sync changelog → (3) Commit/push → (4) Deploy plugin → (5) Update prod API
Automatically runs sync-changelog.sh with --from-handoff flag during version bump
Uses dynamic date detection to find current day's handoff doc

[v5.7.19] - 2026-01-02 (Build 214)

Branch: 2025-1230/plugin-updates

Summary

Integrated changelog sync into bump-version.sh with automatic handoff doc extraction

Changed

mkdocs/sync-changelog.sh: Enhanced to support --from-handoff flag that extracts changelog entries from handoff docs
Auto-detects today's date in YYYY-MMDD format to find matching handoff file
Parses entries and categorizes into Added/Fixed/Changed/Removed/Technical sections
Checks for duplicate versions before inserting to prevent overwrites
Syncs main CHANGELOG.md to mkdocs/docs/changelog.md
scripts/bump-version.sh: Added Step 2 (Sync Changelog) to the deployment pipeline
Now 5 steps: (1) Update versions → (2) Sync changelog → (3) Commit/push → (4) Deploy plugin → (5) Update prod API
Automatically runs sync-changelog.sh with --from-handoff flag during version bump
Uses dynamic date detection to find current day's handoff doc

[v5.7.18d] - 2026-01-01 (Build 213)

Branch: 2025-1230/plugin-updates

Summary

Stable release with audio-only mode fixes, podcast continuation UX, and legacy branding API cleanup. All pre-roll and mid-roll ads verified working in both muxed HLS and audio-only modes.

Fixed

Background Image Stripping: Removed legacy v4 branding API call that was clearing background images after 5 minutes in audio-only mode
Mid-roll Ads During Podcast: Fixed RAF "only one playing instance supported" error when mid-roll triggers during podcast playback
App Crash on Menu Back: Fixed playVideoWithConfig() being called with 4 params instead of 1 (now uses playBackgroundVideo())
Podcast Continues on Menu Exit: Episodes no longer stop when backing out to main scene; audio continues in background
Mid-roll Ads in Audio-Only Mode: Wait for audio player to confirm stopped state before signaling RAF
Episode Playback in Audio-Only Mode: Stop liveAudioPlayer before PlaybackManager starts episode

Removed

Legacy v4 Branding API: Removed deprecated /wp-json/castconductor/v4/settings/branding call from settings timer

Technical Details

Added m.stoppedPodcastForAd, m.podcastUrlBeforeAd, m.podcastPositionBeforeAd tracking for podcast resume after mid-roll
Added m.waitingForAudioStopForAd flag for audio-only mode ad preparation
Resume podcast at saved position after mid-roll instead of restarting live stream

[v5.7.17c] - 2026-01-01 (Build 198)

Branch: 2025-1230/plugin-updates

Summary

Toaster artwork fix and episode playback reliability improvements.

Fixed

Toaster Artwork Fetching: Provisioning API now correctly downloads custom artwork from WordPress URLs (Node.js 16 compatibility fix using axios instead of fetch)
Episode Playback Race Condition: Set videoPlayerMode="idle" BEFORE stopping video to prevent loop restart
State-Based Video Detection: Check m.videoPlayer.state="playing" instead of unreliable muxed HLS flags
Fallback Image Display: Show scene's fallback image when stopping video for podcast
Memory Monitoring Compatibility: Restored try/catch wrappers for firmware compatibility with EnableMemoryWarningEvent

Technical Details

Added m.stoppedVideoForPodcast tracking for future video restart logic
Set m.isMuxedHLSMode in playBackgroundVideo() based on mute state

[v5.7.16] - 2026-01-01 (Build 185)

Branch: 2025-1230/plugin-updates

Summary

Overlay ad Phase 1 implementation and playback mode override.

Added

Overlay Image URL Support: Static image URL for banner overlay ads at configurable intervals
IAB Standard Sizes: 728x90 leaderboard, 300x250 medium rectangle
Playback Mode Override: When WordPress Settings has playback_mode set to audio_only, Roku respects this and uses static image background even if Scene has video URL configured

Technical Details

New WordPress setting castconductor_overlay_image_url with URL sanitization
image_url field added to overlay placement in advertising config API
MainScene checks m.currentPlaybackMode = "audio_only" before setting up video background

[v5.7.15] - 2025-12-31 (Build 180)

Branch: 2025-1230/plugin-updates

Summary

Scene Manager UI cleanup and license management improvements.

Added

Branding Enabled Toggle: Checkbox in Scene Appearance tab to disable scene-level branding
Admin Column Toggles: Show/hide columns in license management with localStorage persistence
New License Columns: Renews At, Ends At, Watermark Starts, Sub Status, Card Brand/Last4, Last Check
Essential/Show All Presets: Quick toggle buttons for column visibility

Fixed

Watermark Config Polling: License config now updates on every config poll (not just scene changes)
Watermark Timer Cleanup: stopWatermark() properly stops all 3 timers when license becomes active
Watermark Warning Logic: Don't show warning for valid+active licenses

Changed

Removed Overlays Tab: Menu building now on dedicated Menu page
Removed Video Mute/Loop Options: Roku requires muxed HLS (cannot play separate audio/video sources)
Watermark Visibility: Increased from 5s to 10s every 60 seconds (16% vs 8% of time)
Simplified License UI: Removed confusing feature checkboxes, added clear watermark warning

Technical Details

LemonSqueezy data expansion: 12 new columns in licenses table, 9 new columns in customers table
Correct watermark timing: trials=immediate, cancelled=end of billing, unpaid=30-day grace
Scene branding toggle saves branding.enabled field within scene's branding JSON

[v5.7.14] - 2025-12-30 (Build 160)

Branch: 2025-1230/plugin-updates

Summary

Complete RAF (Roku Advertising Framework) integration with pre-roll and mid-roll ads working in all playback modes.

Added

RAF Pre-roll Ads: Working in both muxed HLS video and audio-only modes
RAF Mid-roll Ads: Configurable interval with smooth transitions
Audio Fade Transitions: 0.5s fade out before ad, fade in after (video mode only - Audio nodes don't support volume)
AdPlaybackTask Component: Task node for RAF workflow to avoid render thread blocking
Domain Validation: Server-side validation ensures users can only build apps for their licensed domain
Clean Menu Dismiss: Skip nuclear reset when user just peeks at menu without selecting content

Fixed

RAF Render Thread Error: Moved all RAF operations to Task thread (was crashing with "RAF call in wrong environment")
Only One Playing Instance: Defer video/audio start until pre-roll ad completes
Double AdPlaybackTask Bug: Triple guard against creating duplicate ad tasks
Logo During Ads: Added m.adPlaybackActive flag to block all branding visibility during ad playback
Focus After Ads: Restore focus to MainScene after RAF ad playback so menu button works
Video Background Clearing: Fixed stale video URL persisting after user clears it in scene settings

Technical Details

RAF v3.2021 in production
Pass Scene node (not Video node) to showAds() - RAF creates its own video player
AdManager receives config from WordPress, Task does full RAF workflow
prepareForAd and contentStopped fields for proper mid-roll content stopping
Ad pod validation prevents crashes from malformed VAST responses

[v5.7.13j] - 2025-12-29 (Build 138)

Branch: 2025-1229/layer-grouping, 2025-1229/new-content-block-creation

Summary

Analytics overhaul with geographic tracking, database backup/restore system, and container rotation fixes.

Added

Analytics Dashboard: Interactive Leaflet.js map with geographic distribution and city pins
Item-Level Tracking: Individual sponsor/promo tracking by name
Database Backup/Restore: Full SQL backup system for CastConductor tables
Session Management: Auto-cleanup of duplicate active sessions
Search Functionality: Content performance table filtering

Fixed

Container Rotation: Equal percentages now use round-robin (33/33/33 works correctly)

Changed

Database v1.4.0: New tables (cc_analytics_content_daily, cc_analytics_devices)

[v5.7.12o] - 2025-12-28 (Build 125)

Branch: 2025-1228/album-artwork-override

Summary

Album artwork override system with live metadata matching and UI cleanup.

Added

Live Now Playing Panel: Real-time track display with auto-refresh (30s)
Match Key System: "Use as Match Key" button auto-fills exact metadata strings
Fuzzy Matching: Fallback for near-matches when exact MD5 fails
Raw Metadata Display: Shows exact AzuraCast JSON for debugging

Fixed

Live Now Playing Parsing: Properly parse raw AzuraCast metadata format (now_playing.song.artist/title)
Artwork Override Matching: Solved mismatch problem (e.g., "Jason Nevins p/ Holly" vs "Jason Nevins presents Holly")

Removed

Discovery Statistics Section: Legacy code that never loaded
Test Artwork Search Form: Caused white page on submit
Run Test Suite Section: Never implemented, served no purpose

Changed

Page Title: "Enhanced Album Artwork Discovery" → "Album Artwork Management"

[v5.7.12n] - 2025-12-27

Branch: 2025-1221/native-video-support

Summary

Analytics dashboard architecture finalized with comprehensive specification.

Added

SPEC-ANALYTICS-DASHBOARD-v2.md: Complete architecture specification
Database Schema: All 7 tables defined upfront
PHP Architecture: 6 modular classes designed
Plan Tiers: creator, pro, business, agency, enterprise

Decided

Session Filtering: Skip restorations, log separately (Option C)
API Authentication: Auto-generated key via /channel-config (Invisible B)
QR Code UTM Generation: Generated at QR creation time (Option A)
Aggregation Strategy: WP-Cron + real cron + manual trigger
API Version: v5 (all endpoints at /castconductor/v5/*)
Dashboard UI: Vanilla ES6 + Chart.js
Tier Gating: Built-in from start

[v5.7.12] - 2025-12-24

Branch: 2025-1221/native-video-support

Summary

Full muxed HLS video support implementation.

Added

Muxed HLS Video: Video plays on app startup
Graceful Fallback: Falls back to audio + static image when HLS unavailable
Stream Recovery: Picks up muxed stream when restored

Fixed

"Play Live Stream" Restart: Now properly restarts muxed HLS after podcast playback
Podcast→Live Transition: Clears error flags and stops all audio before restart

Test Results

✅ App startup → muxed HLS video+audio
✅ Podcast playback → back to main
✅ Play Live Stream (HLS up) → immediately loads muxed video
✅ Play Live Stream (HLS down) → falls back to audio + static image
✅ HLS restored → picks up muxed stream

Known Polish Items

Fallback transition could use loading indicator
Transport player styling mismatch in episode detail panel

[v5.6.8a] - 2025-12-20

Branch: 2025-1217/extended-features

Summary

Hero Content Block implementation with Smart Token Inference.

Added

Track Info Hero: Fully rendering on Roku
Smart Token Inference: Auto-configures data sources
V5 Mode Gate Fix: dataSource can be null/inferred
Album Artwork in Custom Blocks: Rendering support
Audio Stream Config Enhancement

Fixed

Keyboard Shortcuts: L/V conflict resolved
Layer Name Persistence: Now saves to database

Changed

UI Cleanup: Hidden redundant elements
QR Code Button: Restyled
Container Preset Button: Restyled

Session 2025-12-17

Branch: 2025-1217/extended-features

Summary

Custom API token work with reverts due to breakage.

Reverted

Custom API Token Changes: Broke content block stage, reverted to stable commit c0c2c7b

Identified Issues for Next Session

Save Button Trigger Bug: Dragging layers doesn't enable save button
Ticker Controls Missing: Not present in precision modal
Data Flow Documentation Needed: Trace through all 3 stages
Custom API Token Resolution: Needs careful re-attempt

Session 2025-12-16

Branch: 2025-1214/production-website

Added

Production website work continued

Session 2025-12-12

Branch: 2025-1212/lemon-squeezy

Summary

LemonSqueezy integration with Postmark email notifications.

Added

Purchase Flow Integration: Post-purchase customer onboarding
License Storage: Database persistence for customer licenses
Welcome Email System: Using Postmark via native Node.js HTTPS module
Product ID Mapping: mapProductIdToPlan() for creator/pro/business plans
Customer Licenses Admin Tab: First tab in admin panel with search capability
License Management API: /api/licenses GET and /api/licenses/:id PATCH endpoints
Pricing Page: Domain input passes to LemonSqueezy via checkout[custom][domain]
Thank You Page: 4-step setup instructions (plugin download, license activation, Toaster, scene creation)

Configured

LemonSqueezy Dashboard: All 6 product variants with button link to /thank-you
Postmark Server: CastConductor ([email protected])
Email Template: HTML template with license key, domain, setup instructions

Blocked

Postmark Account Approval: Emails to external domains pending approval (24-48 hours)

Session 2025-12-11

Branch: 2025-1211/branding-animations

Added

Branding animations work continued

Session 2025-12-10

Branch: feature/scenes-containers-wiring

Summary

Scene Manager enhancements with editing workflow improvements.

Added

Edit Without Activation: editingScene concept for safer editing
Edit Button: Per-scene editing in list view
Scheduling Tab: New 4th tab implemented
Active Scene Warning System

Fixed

Idempotent API: Returns existing scene instead of error
Scene Data Persistence: Proper saving and loading

Changed

Containers Tab Redesign: Added remove buttons
API Behavior: More predictable and safer

Session 2025-12-03

Branch: feature/v5-content-block-canvas-refactor

Added

Content block canvas refactoring continued

Session 2025-12-01

Branch: feature/v5-content-block-canvas-refactor

Summary

Infrastructure and security enhancements.

Added

Discourse Forum: Installed at kb.castconductor.com
Postmark SMTP: Email configuration
Docker Compose Production Stack: Production deployment setup
Security Protocol: SECURITY-PROTOCOL.md documentation
2GB Swap File: For Discourse requirements
Cloudflare Tunnel Routing: Production infrastructure

[v5.2.0] - 2025-11-26

Branch: feature/v5-content-block-canvas-refactor

Summary

Preset geometry fixes and container preset UI.

Fixed

PRESET_GEOMETRY Coordinates: Updated from 1920×1080 to 1280×720 authoring space
Quarter Presets Too Large: All four quarter presets now render correctly

Added

Container Preset Dropdown: Quick preset selection button next to "Add Layer"
Visual Preset Indicators: Icons and descriptions in dropdown

Technical Details

Canvas Editor operates in 1280×720 authoring space (Roku's native resolution)
Roku devices upscale 1.5× to FHD (1920×1080) at playback time
All 14 presets now use correct coordinate system

Session 2025-11-22 - 2025-11-23

Branch: feature/v5-roku-migration

Summary

V5 content rendering with token replacement and artwork display.

Fixed

Wrong Function Being Called: Two renderV5Layers() functions existed; changes were being made to wrong file
Missing Shoutout Message: WordPress sends message/name/location as top-level fields, not in meta object
Artwork URL Mismatch: WordPress sends featured_media_url, code was checking wrong field name
Track Info Refresh Timer: V5 used 300s for ALL blocks; restored 30s for track_info
No Debug Logging: Added deployment markers and layer count logging
Roku Bytecode Caching: Required incrementing build_version to force fresh compilation

Added

Token Replacement Logging: Visibility into token processing
Layer Rendering Diagnostics: Clear debug output

Technical Details

V4 behavior: track_info refreshed every 30 seconds for near-real-time updates
V5 migration initially lost this special case timing
Proper file: /roku-app/components/framework/BaseContentBlock.brs (line 1098)
Wrong file (not used): /roku-app/source/V5LayerRenderer.brs (line 192)

Session 2025-09-18

Branch: castconductor-v5-phase3

Summary

Content Block Visual Editor with legacy layer management.

Added

Legacy Layer Editing: Move, resize, precision dialog for static-text/static-image layers
Non-Destructive Overrides: legacy_overrides system preserves edits
Convert to Token: One-click migration from legacy to token layers with geometry preservation
Rulers Toggle: Outside-edge rulers with no-reflow guarantee

Fixed

Legacy Hydration: Now honors legacy_overrides for text/image
Empty Content Guard: Skip DOM render for empty legacy layers, but show in panel
Rulers Reflow: Toggle via host-only class prevents layout expansion

Changed

Panel Rename: "Container Layers" → "Block Layers"
Save Includes Overrides: visual_config.legacy_overrides persisted

Quality

Legacy layers: 90% complete
Export save-first gating: 100%
Rulers overlay: 90%
Empty-content gating: 100%
Overall shipped feature set: ~88%

Session 2025-08-18

Branch: castconductor-v5-phase3

Summary

Phase 3 progress with canvas editor improvements.

Added

Interactive Drag/Resize: Block preview with corner handles and snapping
Per-Zone Previews: Load with clear inline diagnostics
Keyboard Shortcuts: G (grid), +/- (snap size), arrows (nudge), Alt+arrows (resize)
Grid Toggle: Reapplies after render
Cache-Busting: Plugin header version matches CASTCONDUCTOR_VERSION (5.0.1)

Fixed

Container Hydration: Always fetch + render before loading assignments
Lower Third OOTB: Apply 50/30/10/10 defaults when empty
Preview Stability: Deterministic schedule with optional per-container shuffle
Pointer Events: Overlay/preview don't intercept mouse events

Changed

Scale-Aware Deltas: Proper handling between 1920×1080 logical and preview pixels
Enqueue Uses File Mtime: For CSS/JS cache busting

[v5.0.0] - 2025-08-05

Branch: castconductor-v5-clean-architecture

Summary

V5 Phase 1 implementation with "NO DUMMY DATA BY DEFAULT" philosophy.

Added

Clean Plugin Architecture: Singleton pattern implementation
3-Table Database: containers, content_blocks, container_blocks
Master Roku API Controller: Real data sources only
Activation Wizard: Realistic test data seeding
Data Protection System: Preserves user content on uninstall
Custom Post Types: castconductor_shoutout, castconductor_sponsor, castconductor_promo

Changed

Philosophy Shift: No dummy/placeholder data by default
Architecture: Clean, maintainable codebase with proper separation

Session 2025-08-14 - 2025-08-15

Branch: castconductor-v5-phase3

Summary

V5 Phase 3 with zones model implementation.

Added

Zones Model: Container layout with layout.zones and activeZoneIds
Per-Zone Assignments: GET/PUT endpoints
1920×1080 Macro Canvas: Drag/resize with grid snapping
Zone-Aware Preview: Deterministic weighted schedules
Setup Wizard: Seeds Upper Third L/R zones out-of-the-box

Technical Details

Reference Geometry:
Upper Left: (60, 0, 600, 200)
Upper Right: (1260, 0, 600, 200)

Session 2025-08-02 - 2025-08-03

Branch: castconductor-v5-validation

Summary

System analysis and comprehensive plugin validation.

Identified Issues

Terminology Inconsistency: Widgets vs content blocks confusion
Dummy vs Real Data: Architectural conflict in data pipeline
WordPress→Roku Pipeline: Incomplete data flow
API Endpoint Mismatch: v1/v4 confusion

Resolution Strategy

Complete v4 migration
Wrapped API responses for consistency
Dynamic URL configuration
Terminology standardization

[v4.0.0] - 2025-07-25

Branch: Phase 2 WordPress Plugin Complete

Summary

Canvas Editor with multi-container management.

Added

Enhanced Visual Builder: 400+ lines modular JavaScript
Multi-Container Selection: Ctrl+Click bulk operations
Toolbar: Alignment, distribution, layer management tools
Database Schema: 4 core tables with proper relationships
REST API v4: 15+ endpoints implemented
Container Types:
LowerThirdContainerEnhanced
VerticalLeftContainer
BottomRightContainer
TopBannerContainer

Files

SESSION-HANDOFF-20250725-CONTAINER-BREAKTHROUGH.md
SESSION-HANDOFF-20250725-SHOUTOUT-BREAKTHROUGH.md
PHASE-2-WP-PLUGIN-REFACTOR-COMPLETE-HANDOFF-20250725.md

Session 2025-07-26 - 2025-07-27

Branch: Canvas Editor Phase 2-3

Summary

8 Content Block Designers completed.

Added

Track Info Designer: 5 layouts, album artwork controls, typography, progress bar
Shoutout Designer: Scrolling system (1x-10x speeds), message modes
Sponsor Designer: Logo management, brand color integration
Promo Designer: Multi-layout, CTA styling
Weather Designer: Environmental data display
Location/Time Designer: Temporal display with multiple formats
Custom API Designer: Extensible integration platform
Custom Designer: Flexible content management

Technical

Real-Time Preview Engine: AJAX-powered updates
JSON Config Storage: Structured data persistence
Container Canvas: Drag-and-drop from palette
Shadow DOM Injection: Clean component isolation

Files

2025-07-26-CANVAS-EDITOR-PHASE-2-HANDOFF.md
2025-07-27-CANVAS-EDITOR-PHASE-3-HANDOFF.md

Session 2025-07-23

Branch: Container & Artwork Systems

Summary

Album Artwork Discovery and Container System implementation.

Added

Album Artwork Discovery: 412-line AlbumArtTask with iTunes/MusicBrainz/Deezer APIs
Smart Search Framework: Complex title handling
Container System: LowerThirdContainer with 4-widget rotation
Semi-Transparent Overlay: 1280×360px covering full lower-third
Widget Positioning: [420, 800] for lower third placement

Critical Discovery

Shoutout/Promo need separate architecture (not competing widgets)

Files

SESSION-HANDOFF-20250723-ARTWORK-API-IMPLEMENTATION.md
SESSION-HANDOFF-20250723-WIDGET-BREAKTHROUGH.md
SESSION-HANDOFF-20250723-CONTAINER-SYSTEM-COMPLETE.md

[v3.0.0] - 2025-07-22

Branch: architecture-refactor

Summary

Architecture transformation to widget-first system.

Major Changes

Widget-First Architecture: Legacy dual-system elimination
Real-Time Updates: 60-second polling with hot configuration swapping
WordPress Controls:
Rotation interval (5-60s)
Content percentages (Track 50%, Shoutout 30%, Sponsor 15%, Promo 5%)

Added

Tabbed Admin Interface: 4 tabs
Streaming & Content
Appearance & Branding
Widget Controls
Integration & APIs

Color System

Track Info: #ffff00 (Yellow)
Shoutout: #77f3ff (Cyan)
Sponsor: #00ff26 (Green)
Promo: #ff00fa (Magenta)

Version Bumps

WordPress Plugin: v2.1.0 → v3.0.0
Roku App: v2.1.0 → v3.0.0

Files

SESSION-HANDOFF-20250722.md
SESSION-HANDOFF-20250722-EVENING.md
SESSION-HANDOFF-20250722-FINAL.md
SESSION-HANDOFF-20250722-V3-COMPLETION.md
SESSION-HANDOFF-20250722-PATTERN-ANALYSIS.md
SESSION-HANDOFF-20250722-SHOUTOUT-DEBUGGING.md
SESSION-HANDOFF-20250722-TRACK-INFO-POSITIONING-AND-COLORS.md

Session 2025-07-20 - 2025-07-21

Branch: Widget System Integration

Summary

Widget system stability and live data integration.

Added

Weather Data: Live with IP geolocation + OpenMeteo API
Glass Bubble Widget: Styling implementation
Animation System: Implemented then removed for performance
Track Info Visibility: Conditional legacy system hiding

Fixed

Widget System Crashes: createAllEnabledWidgets → createActiveWidgets
Runtime Errors: Proper error handling and recovery

Discovered

BrightScript Rectangle Node Limitations: Documented constraints

Files

SESSION-HANDOFF-20250720.md
SESSION-HANDOFF-20250720-WIDGET-RUNTIME-FIX.md
SESSION-HANDOFF-20250721.md

[v2.0.0] - 2025-07-19

Branch: Initial Roku App Work

Summary

Brand transformation and foundational app development.

Brand Transformation

ACiD877 → CastConductor: Complete Rebrand
Domain Acquired: castconductor.com
Version Synchronized: v2.0.0 across WordPress plugin and Roku app

Added

Album Artwork System: Multi-API fallback (iTunes, MusicBrainz, Deezer)
Full-Screen Splash: 1920x1080 with Lorem Picsum
Dynamic Configuration: GetAppConfig() helper
Progress Band: Visibility improvements

Fixed

DateTime Bug: GetSecondsSinceEpoch → AsSeconds
Splash Screen: Progress band visibility

Files

SESSION-HANDOFF-20250719.md
SESSION-HANDOFF-CASTCONDUCTOR-20250719.md

[v1.0.0] - Initial Release (July 2025)

Summary

Initial CastConductor system architecture and Roku app foundation.

Core Features

Basic Roku app framework
WordPress plugin integration
Streaming configuration
Content management foundation

Development Philosophy & Best Practices

Version Numbering

Major (X.0.0): Architectural changes, breaking API changes
Minor (0.X.0): New features, non-breaking enhancements
Patch (0.0.X): Bug fixes, polish, small improvements
Build Letter (X.X.Xa): Session-level iterations within a patch

Branch Naming Convention (Since Nov 2025)

Format: yyyy-mmdd/feature-name
Example: 2025-1229/layer-grouping
Benefits: Chronological sorting, clear context

Changelog Practices

Session Entries: For work without formal version bumps
Date Headings: "Session YYYY-MM-DD" or "Branch: branch-name"
Comprehensive: All significant changes documented
LIFO Order: Newest entries at top
Context Rich: Include branch, version, files, rationale

Documentation Standards

Handoff Protocol: CCVE_PROTOCOL_SENTINEL_v1
Entry Format: Timestamp, branch, files changed, problem/solution
No Future Tense: Only document completed work
Reverse Chronological: Newest entry below line 21 (in handoff docs)

Key Architectural Milestones Timeline

v1.0 → v2.0: Initial Roku app + Brand transformation to CastConductor
v3.0: Widget-first architecture with real-time WordPress controls
v4.0: Professional Canvas Editor with 8 content block designers
v5.0: "NO DUMMY DATA" philosophy, zones model, hierarchical architecture
v5.2: Roku V5 migration, Smart Token Inference
v5.6-5.7: Hero blocks, Analytics, Production-ready features

Current Development Status (Dec 29, 2025)

Active Components

WordPress Plugin: v5.7.13j (Build 138)
Roku App: Advanced V5 parser with Smart Token Inference
Database: v1.4.0 with analytics and device tracking
Infrastructure: Production server with Discourse forum, Cloudflare tunnel

Production Features

Full Server-Side Layer Rendering (SSLR)
Layer grouping capability
Analytics dashboard with geographic tracking
Database backup/restore system
LemonSqueezy integration with Postmark emails
Muxed HLS video support with graceful fallback

Active Development Areas

Layer grouping enhancements
Analytics dashboard UI implementation
Production website refinements
Native video support optimization

Repository Information

Primary Branch: main
Development Workflow: Feature branches with date prefixes
Documentation: /docs/HANDOFFS/ contains detailed session logs
Database Schemas: /schemas/ directory
Build Scripts: /scripts/ directory

Contributing

See DEVELOPMENT-GUIDELINES.md for coding standards and contribution guidelines.

License

See LICENSE-HEADER.txt for licensing information.