@mxtommy/kip 3.12.0 → 4.0.1

package/.github/copilot-instructions.md

@@ -10,25 +10,97 @@ Use this quick-start map to be productive in this repo. Prefer these concrete pa
 
 ## Daily workflows
 - Dev: npm run dev, then open http://localhost:4200/@mxtommy/kip/ (needs a running Signal K server).
-- Build: npm run build-dev | npm run build-prod (outputs to public/ and respects baseHref).
+- Build KIP app: npm run build:dev | npm run build:prod (outputs KIP to public/ and respects baseHref).
+- Build KIP app and KIP plugin: npm run build:all (outputs KIP to public/ and respects baseHref. Outputs plugin to kip-plugin).
 - Quality: npm run lint, npm test (Karma). E2E (Protractor) is legacy/optional.
 
-## Widget contract (critical)
-- Extend BaseWidgetComponent (src/app/core/utils/base-widget.component.ts) for every widget.
-- Implement startWidget() and updateConfig(config: IWidgetSvcConfig).
-- defaultConfig defines initial config; call validateConfig() to merge new properties into saved configs safely.
-- Subscriptions: observeDataStream('pathKey', next => ...) for values; observeMetaStream() for zones. Cleanup: destroyDataStreams() in ngOnDestroy.
-- Multiple streams: Call observeDataStream once per needed config.paths key. BaseWidget aggregates all under one Subscription; destroyDataStreams() unsubscribes all data and meta streams at once.
-- Units: Always go through UnitsService (convertToUnit, formatWidgetNumberValue). Don’t hardcode conversions/formatting.
-- Define config.paths[pathKey] with: path, pathType ('number' | 'string' | 'Date' | 'boolean'), sampleTime, convertUnitTo, source.
-
-### observeDataStream features (applied automatically)
-- Auto-creates per-path observables from config.paths via createDataObservable() when first used.
-- Applies sampleTime from the path config consistently to reduce churn.
-- For pathType 'number': performs UnitsService.convertToUnit(convertUnitTo) and optionally timeout+retry.
-- For 'string' | 'Date': applies sampleTime and optional timeout/retry (no unit conversion).
-- For 'boolean': applies sampleTime (no timeout/retry).
-- Global timeouts: enableTimeout + dataTimeout (seconds) at widgetProperties.config level control timeout behavior.
+## Host2 widget contract (critical)
+All widgets now follow the Host2 architecture (legacy BaseWidgetComponent removed).
+
+1. Standalone component with required functional inputs:
+	 ```ts
+	 id = input.required<string>();
+	 type = input.required<string>();
+	 theme = input.required<ITheme | null>();
+	 ```
+2. Provide a static `DEFAULT_CONFIG: IWidgetSvcConfig` fully describing initial config (paths + options).
+3. Inject directives for runtime + streams (and optionally metadata):
+	 ```ts
+	 private runtime = inject(WidgetRuntimeDirective);
+	 private streams = inject(WidgetStreamsDirective);
+	 // optional
+	 // private meta = inject(WidgetMetadataDirective);
+	 ```
+4. Register data observers in a single effect:
+	 ```ts
+	 effect(() => {
+		 const cfg = this.runtime.options();
+		 if (!cfg) return;
+		 untracked(() => {
+			 if (cfg.paths?.numericPath?.path) {
+				 this.streams.observe('numericPath', pkt => this.value.set(pkt?.data?.value ?? null));
+			 }
+			 // repeat for other path keys
+		 });
+	 });
+	 ```
+5. Always guard for missing config or optional paths (check `cfg?.paths?.key?.path`).
+6. Avoid mutating the merged config object; store transient UI state in signals.
+7. Use UnitsService and existing formatting helpers; do not hardcode conversions. Using streams directive handles path unit conversion settings automatically for number types.
+8. Timeout settings honored automatically (`enableTimeout`, `dataTimeout`)—`WidgetStreamsDirective`.
+9. Provide meaningful path keys (e.g. `numericPath`, `headingTrue`, `windSpeed`) and keep them stable.
+10. Destroy logic is usually implicit (streams directive centralizes subscriptions); only tear down custom resources manually if you allocate them (e.g., canvases, animation frames).
+
+### Path definition recap
+Each entry in `DEFAULT_CONFIG.paths`:
+```ts
+someKey: {
+	description: 'User label',
+	path: 'navigation.speedThroughWater',
+	pathType: 'number' | 'string' | 'Date' | 'boolean',
+	convertUnitTo: 'knots',       // For numeric path only. Sets automatic conversion to this unit
+	sampleTime: 1000,              // ms, typical 500+
+	source: null,                 // optional source selection. null = default source
+	isPathConfigurable: true,     // false to hide path in path options UI
+	pathRequired: true,           // set false for optional
+	showPathSkUnitsFilter: false, // Show numeric UI filter support
+	pathSkUnitsFilter: null       // Set and apply a path unit filter (e.g. 'knots' for speed)
+}
+```
+
+### Data stream behavior (via WidgetStreamsDirective)
+- Respects per-path `sampleTime`.
+- Converts units for number paths using UnitsService.
+- Optional timeout logic based on widget config flags.
+- Centralized unsubscribe when host destroys the widget.
+
+### Embedded widgets (composite pattern)
+Use this patterns when a parent widget (e.g. Autopilot) displays other widgets:
+
+#### `<widget-embedded>`
+Supply a complete `widgetProperties` object (no persistence writes):
+```ts
+xteWidgetProps = {
+	uuid: this.id() + '-xte',
+	type: 'widget-numeric',
+	config: {
+		type: 'widget-numeric',
+		title: 'XTE',
+		paths: { numericPath: { description: 'Cross Track Error', path: 'navigation.course.crossTrackError', pathType: 'number', convertUnitTo: 'nm', sampleTime: 1000, isPathConfigurable: false } },
+		numDecimal: 2
+	}
+};
+```
+Template:
+```html
+<widget-embedded [widgetProperties]="xteWidgetProps"></widget-embedded>
+```
+`widget-embedded` internally wires runtime + streams + metadata and instantiates the child.
+
+### Safety patterns
+- Null guard every `runtime.options()` access in effects & template (`runtime.options()?.paths?.key`).
+- Avoid repeated `runtime.options()` chains in template: expose a computed `cfg = computed(() => this.runtime.options())`.
+- For performance, do all `streams.observe` calls in one untracked block.
 
 ## Widget path options (important)
 - pathType: Controls pipeline behavior (see features above). Must be accurate: 'number' | 'string' | 'Date' | 'boolean'.
@@ -61,18 +133,21 @@ Use this quick-start map to be productive in this repo. Prefer these concrete pa
 - Use standalone components, signals, @if/@for; follow .github/instructions/angular.instructions.md for style.
 - Widget config UIs live under src/app/widget-config; path controls use custom validators (no Validators.required). Respect isPathConfigurable and pathRequired.
 
-## Widgets: do this, not that
-- Do: Define a complete defaultConfig (including config.paths) and call validateConfig() before using config. Don’t: Scatter fallback defaults across methods.
-- Do: Use observeDataStream(...) and destroyDataStreams() in ngOnDestroy. Don’t: Manually subscribe to DataService in multiple places without centralized cleanup.
-- Do: Call observeDataStream once per path key; let BaseWidget aggregate subscriptions. Don’t: Manage multiple Subscription instances yourself—destroyDataStreams() handles all.
-- Do: Convert/format with UnitsService and formatWidgetNumberValue(). Don’t: Hardcode unit math (e.g., divide by 0.5144) or toFixed() ignoring widget decimals/min/max.
+## Widgets: do this, not that (Host2)
+- Do: Provide a complete `DEFAULT_CONFIG` with all paths & options. Don’t: Scatter defaults across lifecycle hooks.
+- Do: Centralize `streams.observe` calls in a single effect. Don’t: Register observers in multiple hooks.
+- Do: Keep transient state in signals. Don’t: Mutate merged config objects.
+- Do: Use UnitsService / formatting helpers. Don’t: Hardcode conversion factors.
+- Do: Guard `options()` & path existence. Don’t: Assume presence.
+- Do: Use widget-embedded or inline directives for composites. Don’t: Reintroduce legacy host wrappers.
 
 ## Key files/dirs
-- Core services: src/app/core/services/ (DataService, SignalKConnectionService, SignalKDeltaService, AppNetworkInitService, UnitsService, DataSetService, NotificationsService).
-- Widget base: src/app/core/utils/base-widget.component.ts (subscriptions, units, zones, formatting).
-- Widgets: src/app/widgets/ (e.g., widget-numeric, widget-gauge-ng-*, widget-data-chart, widget-windtrends-chart).
-- Config UI: src/app/widget-config/ (shared config components, validators, modals).
-- Build: angular.json, package.json scripts.
+- Core services: `src/app/core/services/` (DataService, SignalKConnectionService, SignalKDeltaService, AppNetworkInitService, UnitsService, DataSetService, NotificationsService)
+- Directives: `src/app/core/directives/` (widget-runtime, widget-streams, widget-metadata)
+- Widgets: `src/app/widgets/` (e.g., widget-numeric, widget-gauge-ng-*, widget-data-chart, widget-windtrends-chart, widget-autopilot)
+- Embedded host: `src/app/core/components/widget-embedded/`
+- Config UI: `src/app/widget-config/`
+- Build: `angular.json`, `package.json` scripts
 
 ## Debugging
 - Use Data Inspector (src/app/core/components/data-inspector) to verify live paths/metadata.

package/.github/instructions/angular.instructions.md

@@ -127,7 +127,7 @@ Here is a link to the most recent Angular style guide https://angular.dev/style-
 3. **Project Setup**: Refer to `README.md` for build commands, dependencies, and environment setup
 
 ### **Integration Notes:**
-- When developing KIP widgets, extend `BaseWidgetComponent` as described in `COPILOT.md` AND follow the Angular v20+ patterns in this file
+- When developing KIP widgets, follow the Host2 widget architecture (signals + `WidgetRuntimeDirective` / `WidgetStreamsDirective` (+ optional `WidgetMetadataDirective`)) and, for new widgets, prefer generating the scaffold via the `create-host2-widget` schematic (see `COPILOT.md` sections 9 & 13)
 - Use signals, standalone components, and modern control flow from this file within the KIP architecture from `COPILOT.md`
 - For theming and colors, always use the KIP theme system described in `COPILOT.md`, not generic CSS approaches
 - All services should follow both the Angular DI patterns here AND the KIP service architecture in `COPILOT.md`

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+# v 4.0.0
+## New features
+- **Next‑gen widget framework**: A simplified component architecture that makes widgets faster to develop, leaner to run, and more consistent to configure — now with an automated widget generator and **AI‑assisted guidance** to get you from idea to working widget in minutes. Want to contribute your first widget? Run `npm run generate:widget` and follow the prompts.
+- Data Chart, streamlined: Dataset configuration now lives directly inside the widget. The separate “Dataset Options” page has been retired for a cleaner flow.
+- Racesteer (beta): Performance‑plugin powered windsteer with real‑time optimal steering cues and on‑the‑fly performance ratios against your polar based on live conditions. Requires a valid polar chart.
+## Improvements
+- Radial Gauge, your way: Hide the needle, progress bar, and ticks independently for ultra‑custom layouts.
+- Snappier gestures on macOS Chrome with responsiveness refinements.
+- Precision layouts with 2× grid resolution for tighter, more accurate arrangements.
+- Chartplotter Mode control: Optional setting to disable KIP gestures over the Freeboard‑SK chart to prevent accidental swipes while moving the chart. Fixes #845.
+- Dashboard editor ergonomics: Cancel/Ok button order now follows platform conventions (Sorry folks. You'll need to rewire your brains. Doctors say it's healthy!).
+- Smarter upgrades: Configuration upgrade service now supports v9 → v12 migrations with a new upgrade activity window.
+- Documentation refresh: Syntax‑highlighted help, a comprehensive Chartplotter Mode guide, and clearer text across Remote Control and Notifications.
+## Fixes
+- Eliminated an occasional “empty dashboard flicker” when dashboards load. Mostly visible on low computing power hardware.
+- Data Trends widget: fixed UI overlap on small screens. Fixes #848.
+- Authentication reliability: Token renewal logic reworked to avoid Node.js 28‑day timer limits.
 # v 3.12.0
 # New Features
 * Chartplotter Mode: A dual‑panel, performance‑tuned split experience that lets you run KIP dashboards and Freeboard‑SK together in one adaptive shell. Keep the chart live while moving between dashboards. Seamless side‑by‑side in landscape, smart vertical stacking in portrait and as always, designed for mobile and touch. Use the per‑dashboard forced collapse option for data‑focused layouts while Freeboard remains active in the background. Drag resize split distribution with commit‑on‑save editing. This feature brings you:

package/README.md

@@ -5,7 +5,7 @@
 
 **KIP is the most popular Signal K MFD and marine instrument panel: plug-and-play, touch-optimized, pre-installed, and ready-to-use across all devices.**
 
-Unlike many dashboards, KIP comes **automatically included with Signal K distributions**, so there’s nothing extra to install or configure. Simply start your [Signal K](https://signalk.org) server, open KIP in a browser, and it’s ready to go. A single instance works everywhere — no per-device deployment is needed.
+Unlike many instrument panels, KIP offers full MFD functionality and is **automatically included with Signal K distributions**, so there’s nothing extra to install or configure. Simply start your [Signal K](https://signalk.org) server, open KIP in a browser, and it’s ready to go. A single instance works everywhere — no per‑device deployment is needed.
 
 KIP is designed for sailors and boaters who want:
 
@@ -20,29 +20,31 @@ With KIP, you get the **familiar feel of professional Multi-Function Displays**
 
 ![KIP](./images/KIPDemo.png)
 
-Key features include:
-- **Flexible Layouts**: Build purposeful dashboards with an easy-to-use and intuitive grid layout system. Drag widgets into place and make adjustments with simple gestures or clicks.
-- **Reusable Widget Library**: A wide range of widgets for numerical, textual, and graphical data, as well as advanced controls like switches, sliders, and autopilot operation.
-- **Night Mode**: Preserve night vision with a simple tap or automatic switching based on sunrise/sunset.
-- **Data State Notifications**: Stay informed with visual and audio alerts for critical data thresholds.
-- **Multiple User Profiles**: Tailor configurations for different roles, devices, or use cases.
-- **Cross-Device Compatibility**: Access KIP remotely on any device by navigating to `http://<Signal K Server URL>:<port>/@mxtommy/kip`.
-- **Remote Control**: Control which dashboard is shown on another KIP instance (e.g., a mast display, hard-to-reach screen, or a non‑touch device).
-- **Kiosk Mode**: Run as a single full-screen application; mast, helm, portable display used as a dedicated instrument panel, a chartplotter, etc.
-
-KIP is open-source under the MIT license, built by the community and 100% free. [Join the community](https://discord.gg/AMDYT2DQga) on Discord or contribute to the project on GitHub!
+## Table of Content
+- [Installations Showcase](#installations-showcase)
+- [Design Goal](#design-goal)
+- [User Experience](#user-experience)
+- [Dashboards and Configuration](#dashboards-and-configuration) & [Widget Library](#widget-library)
+- [Night Modes](#night-modes)
+- [Chartplotter Mode](#chartplotter-mode)
+- [Remote Control](#remote-control-other-kip-displays)
+- [Kiosk Mode](#dedicated-fullscreen-instrument-display-kiosk-mode)
+- [Progressive Web App (PWA)](#progressive-web-app-pwa)
+- [Multiple User Configurations](#multiple-user-configurations)
+- [How To Contribute](#how-to-contribute) & [Creating Your Own Widgets](#kip-widgets)
+- [Connect, Share, and Support](#connect-share-and-support) & [Features, Ideas, Bugs](#features-ideas-bugs)
 
 ## Installations Showcase
 ![Form factor support](./images/exterior_user_installs.png)
-In addition to the obvious navstation, tablet and phone use cases, users have taken KIP outside using Raspberry Pi and Pi Zero computers, rugged tablets and all kinds of cheap to expensive touch screens.
+In addition to the obvious navstation, wall mounted instrument panel and autopilot remote control usecases using PCs, tablets and phones, users have taken KIP into the elements using Raspberry Pi, Pi Zero, rugged tablets and all kinds of low cost AliExpress screens and industry leading, high quality, sunlight readable marine touch screens. KIP's native remote control feature opens up all kinds of possibilities.
 
-## Read the Help introduction How-to
-You just installed KIP and your stuck; read the [Introduction](https://github.com/mxtommy/Kip/blob/master/src/assets/help-docs/welcome.md) help file.
+## Read the Help Introduction How-To
+You just installed KIP and you're stuck; read the [Introduction](https://github.com/mxtommy/Kip/blob/master/src/assets/help-docs/welcome.md) help file.
 
 # Design Goal
 The goal is to replicate and enhance the functionality of modern marine instrumentation displays while providing unmatched customization and flexibility. The design principles include:
 
-- **Full-Screen Utilization**: Ensure the display uses the entire screen without requiring scrolling, maximizing visibility and usability.
+- **Full-Screen Utilization**: Ensure the display uses the entire screen without requiring scrolling, maximizing visibility, usability reducing onscreen control clutter.
 - **Optimized for Readability**: Present data in a large, clear, and easily interpretable format to ensure quick comprehension. Utilize high-contrast color schemes to enhance visibility, especially in bright daylight conditions.
 - **Touchscreen Excellence**: Deliver an intuitive and seamless experience for touchscreen users, with support for gestures like swiping and tapping.
 - **Cross-Device Compatibility**: Guarantee a consistent and responsive experience across phones, tablets, computers, and other devices.
@@ -50,34 +52,34 @@ The goal is to replicate and enhance the functionality of modern marine instrume
 
 ![Form factor support](./images/formfactor.png)
 
-## Features
+## User Experience
 
-### Intuitive Controls
+### Interractions
 - Swipe up and down to navigate through your dashboards effortlessly.
 - Swipe left and right to access notifications and other system features quickly.
-- Use keyboard shortcuts for essential features, ensuring fast and efficient navigation across devices.
-
-![Sidenav Dashboard Access](./images/ActionSidenav.png)
-Sidenav for quick access to all important features.
+- Use keyboard shortcuts for essential features, ensuring fast and efficient navigation across devices types.
 
-### Progressive Web App (PWA) Support
-Run KIP in full-screen mode without browser controls, just like a native mobile app. This feature is supported on most mobile operating systems. Follow your browser's instructions to install KIP as a PWA for quick and easy access. It's usually just a few clicks, such as "Add to Home Screen".
-
-### Flexible Dashboard Layouts
+### Customyze
 - Effortlessly create and customize dashboards using an intuitive grid layout system.
 - Add, resize, and align widgets to design tailored displays for your specific needs.
 - Duplicate widgets or entire dashboards, including their configurations, with a single click.
 - Simply drag dashboards to reorganize them. Double-click any dashboard to open the icon gallery and give each page a unique visual identity.
-- Seamlessly switch between multiple configuration profles for different roles and devices or use cases.
+- Easily switch between multiple user and device configurations profiles for different roles, formfactors or use cases.
 
-## User Experience
+Sidenav for quick access to all important features.
+![Sidenav Dashboard Access](./images/ActionSidenav.png)
+
+Chartplotter Mode with dashboards
+![Chartplotter Mode](./images/ChartplotterMode.png)
 
-### Flexible and Easy
+## Dashboards and Configuration
+
+### Customizable and Easy
 Meant to build purposeful dashboards with however many widgets you want, wherever you want them.
 
 Add, resize, and position the widgets of your choosing. Need more? Add as many additional dashboards as you wish to keep your display purposeful. Simply swipe up and down to quickly cycle through dashboards or effortlessly jump between dashboards with a single tap in the action sidenav, always knowing exactly where you are thanks to clear highlighting of your current dashboard.
 
-Add widget lists sorted by category
+Widget lists are sorted by category.
 ![Layouts Configuration Image](./images/KipWidgetConfig-layout-1024.png)
 
 Intuitive widget configuration.
@@ -89,10 +91,10 @@ See what Signal K has to offer that you can leverage with widgets. Select it and
 Many units are supported. Choose your preferred app defaults, then tweak them widget-by-widget as necessary. KIP will automatically convert the units for you.
 ![Units Configuration Image](./images/KipConfig-Units-1024.png)
 
-Organize your dashboards and access tools
+Organize your dashboards and access tools.
 ![Options and Dashboards](./images/Options.png)
 
-## Reusable Widget Library
+## Widget Library
 All KIP widgets are visual presentation controls that are very versatile, with multiple advanced configuration options available to suit your needs:
 - **Numeric display**: Create gauges to display any numerical data sent by your system: SOG, depth, wind speed, VMG, refrigerator temperature, weather data, etc.
 - **Text display**: Create gauges to display any textual data sent by your system: MPPT state, vessel details, next waypoint, Fusion radio song information, noon and sun phases, any system component configuration detail or status available, etc.
@@ -120,16 +122,16 @@ All KIP widgets are visual presentation controls that are very versatile, with m
 Get the latest version of KIP to see what's new!
 
 ### Widget Samples
-Gauges
+Gauges sample
 ![Sample Gauges Image](./images/KipGaugeSample1-1024x545.png)
 
-Various
+Various other types of widgets
 ![Electrical Concept Image](./images/KipGaugeSample2-1024x488.png)
 
-Freeboard-SK Integration with Autopilot
+Freeboard-SK Chartplotter integration with Autopilot widget
 ![Freeboard-SK Image](./images/KipFreeboard-SK-1024.png)
 
-Grafana Integration
+Grafana integration with other widgets
 ![Embedded Webpage Concept Image](./images/KipGaugeSample3-1024x508.png)
 
 ## Night Modes
@@ -139,12 +141,8 @@ Keep your night vision with automatic or manual day and night switching to a col
 
 ![Night mode - Brightness](./images/KipBrightness-1024.png)
 
-## Harness the Power of Data State Notifications
-Stay informed with notifications about the state of the data you are interested in.
-For example, Signal K will notify KIP when a water depth or temperature sensor reaches certain levels. In addition to KIP's centralized notification menu, individual widgets offer tailored visual representations appropriate to their design objectives, providing an optimal user experience.
-
-## Multiple User Profiles
-If you have different roles on board: captain, skipper, tactician, navigator, engineer—or simply different people with different needs, each can tailor KIP as they wish. The use of profiles also allows you to tie specific configuration arrangements to use cases or device form factors.
+## Chartplotter Mode
+Keep a live Freeboard‑SK chart visible while switching dashboards for an MFD‑style workflow. The chart persists (no reload or flicker), you can choose its side, collapse it per‑dashboard for full data pages, and drag resize the split. Layout auto‑stacks in portrait / narrow screens. See the dedicated Chartplotter Mode help page for setup, performance tips, and troubleshooting.
 
 ## Remote Control Other KIP Displays
 Control which dashboard is shown on another KIP instance (e.g., a mast display, hard-to-reach screen, or a non‑touch device) from any KIP, including your phone.
@@ -155,13 +153,19 @@ Use cases
 - Non‑touch/no input: select dashboards when no keyboard/mouse is connected or touch is not supported/disabled.
 
 ## Dedicated Fullscreen instrument display (Kiosk Mode)
-Runs KIP on Raspberry Pi as a single full-screen application, suppresses desktop UI and stays on screen like a dedicated instrument display at a fraction of the cost. Read the [Kiosk Mode](https://github.com/mxtommy/Kip/blob/master/src/assets/help-docs/kiosk.md) help file.
+Runs KIP on Raspberry Pi as a single full-screen application, suppresses the desktop UI and stays on screen like a dedicated chartplotter or marine instrument panel at a fraction of the cost. Read the [Kiosk Mode](https://github.com/mxtommy/Kip/blob/master/src/assets/help-docs/kiosk.md) help file.
+
+## Progressive Web App PWA
+Run KIP without browser controls, just like a native computer, tablet or phone app. This feature is supported on most mobile operating systems and desktop browser. It freezes up screen real estate and offers a native Android and iOS app experience with single icon launch. Follow your browser's instructions to install Progressiver Web Apps. It's usually just a few clicks, such as "Add to Home Screen".
+
+## Multiple User Configurations
+If you have different roles on board: captain, skipper, tactician, navigator, engineer—or simply different people with different needs, each can tailor KIP as they wish. The use of profiles also allows you to tie specific configuration arrangements to use cases or device form factors.
 
 ## Complementary Components
-Typical complementary components you may install (many are often bundled with Signal K distributions):
+Typical complementary components you may install (most are often bundled with Signal K distributions):
 
 **Navigation & Charting**
-- **Freeboard‑SK** – Multi‑station, web chart plotter dedicated to Signal K: routes, waypoints, charts, alarms, weather layers, and instrument overlays.
+- **Freeboard‑SK** (pre-installed) – Multi‑station, web chart plotter dedicated to Signal K: routes, waypoints, charts, alarms, weather layers, and instrument overlays.
 
 **Visual Flow / Automation**
 - **Node‑RED** – Low‑code, flow‑based wiring of devices, APIs, online services, and custom logic (alert escalation, device control automation, data enrichment, protocol bridging).
@@ -170,12 +174,9 @@ Typical complementary components you may install (many are often bundled with Si
 - **InfluxDB / other TSDB** – High‑resolution historical storage of sensor & performance metrics beyond what lightweight widget charts should retain.
 - **Grafana** – Rich exploratory / comparative dashboards, ad‑hoc queries, alert rules on stored metrics, correlation across heterogeneous data sources.
 
-# Connect, Share, and Support
-KIP has its own Discord Signal K channel for getting in touch. Join us at https://discord.gg/AMDYT2DQga
-
-# Features, Ideas, Bugs
-See KIP's GitHub project for the latest feature requests:
-https://github.com/mxtommy/Kip/issues
+## Harness the Power of Data State Notifications
+Stay informed with notifications about the state of the data you are interested in.
+For example, Signal K will notify KIP when a water depth or temperature sensor reaches certain levels. In addition to KIP's centralized notification menu, individual widgets offer tailored visual representations appropriate to their design objectives, providing an optimal user experience.
 
 # How To Contribute
 KIP is under the MIT license and is built with Node and Angular using various open-source assets. All free!
@@ -194,42 +195,55 @@ What KIP deliberately IS NOT trying to become:
 
 Those domains already have excellent, specialized open‑source tools. Instead of re‑implementing them, KIP plays nicely alongside them within a Signal K based onboard stack.
 
-**Processing & Extensions**
-- **Signal K Plugins** – Domain‑specific enrichment (polars, performance calculations, derived environmental data, routing aids) published directly into the Signal K data model that KIP can then display.
+### Processing, Extensions and Widgets
+
+#### Signal K Plugins
+Domain‑specific enrichment (polars, performance calculations, derived environmental data, routing aids) published directly into the Signal K data model that KIP can then display.
+
+#### KIP Widgets
+Visual data representation component that use Signal K path data and API V2 features. Scaffolding a new widgets only takes a few moments and is backed by KIP AI agent instructions providing willed creative minds a personal assistant programmer.
+
+Run one simple command (example):
+```
+npm run generate:widget
+```
+or ask your AI to create a widget using the KIP project AI instructions.
+
+For deeper details you can still look at `COPILOT.md`, but you don’t need to in order to get started.
 
-**Why this separation matters**
+### Why this separation matters
 
 Keeping KIP focused preserves responsiveness (lower CPU / memory), reduces UI clutter, and accelerates core sailing user experience development. Heavy analytics, complex workflow logic, and broad third‑party embedding stay where they are strongest—outside—but still feed KIP through the common Signal K data fabric.
 
 In short: use KIP to see & act on live sailing information; use the complementary tools to store it long‑term, analyze it deeply, automate decisions, or build advanced integrations.
 
-**Tools**
+## Getting Started
 
-Linux, Mac, RPi, or Windows dev platform supported
-1. Install the latest Node version (v20+)
-2. Download your favorite coding IDE (we use the free Visual Studio Code)
-3. Create your own GitHub KIP fork.
-4. Configure your IDE's source control to point to your forked KIP instance (with Visual Studio Code, GitHub support is built-in) and get the fork's master branch locally.
-5. Install `npm` and `node`. On macOS, you can use `brew install node` if you have Homebrew.
-6. Install the Angular CLI using `npm install -g @angular/cli`
+**Linux, Mac, RPi, or Windows dev platform supported**
+1. Download your favorite coding IDE (we use the free Visual Studio Code)
+2. Create your own GitHub KIP fork.
+3. Configure your IDE's source control to point it to your forked KIP instance (Visual Studio Code, GitHub support is built-in) and get the fork's master branch locally.
+4. Install `npm` and `node`. On macOS, you can use `brew install node` if you have Homebrew. See https://nodejs.org/en/download for more options.
+5. Install the Angular CLI using `npm install -g @angular/cli`
 
-**Coding**
+**Project Setup**
 1. From your fork's master branch, create a working branch with a name such as: `new-widget-abc` or `fix-issue-abc`, etc.
 2. Check out this new branch.
-3. In a command shell (or in the Visual Studio Code Terminal window), go to the root of your local project branch folder, if not done automatically by your IDE.
-4. Install project dependencies using the NPM package and dependency manager: run `npm install`. NPM will read the Kip project dependencies, download, and install everything automatically for you.
+3. In a command shell (or in the Visual Studio Code Terminal window), go to the root of your local project folder, if not done automatically by your IDE.
+4. Install project dependencies using the NPM package and dependency manager: run `npm install`. NPM will read the KIP project dependencies, download, and install everything automatically for you.
 5. Build the app locally using Angular CLI: from that same project root folder, run `npm run build:all`. The CLI tool will build KIP.
 
-**Setup**
-1. Fire up your local dev instance with `npm run dev`.
-2. Hit Run/Start Debugging in Visual Studio Code or point your favorite browser to `http://localhost:4200/@mxtommy/kip`. Alternatively, to start the dev server and allow remote devices connections, such as with your phone or RPi:  
+**Code and Test**
+1. Fire up your local KIP development instance with `npm run dev`.
+2. Hit Run/Start Debugging in Visual Studio Code or manually point your favorite browser to `http://localhost:4200/@mxtommy/kip`. Alternatively, to start the development server and allow remote devices connections, such as with your phone or RPi (blocked for security reasons by default):  
    `ng serve --configuration=dev --serve-path=/@mxtommy/kip/ --host=<your computer's IP> --port=4200`
 3. Voila!
 
 *As you work on source code and save files, the app will automatically reload in the browser with your latest changes.*  
-*You also need a running Signal K server for KIP to connect to and receive data.*
+*You will also need a running Signal K server for KIP to connect to and receive data. You could also use https://demo.signalk.org but without authentication enabled, your actions, features and test coverage will be limited.*
 
 **Apple PWA Icon Generation**
+
 Use the following tool and command line:  
 `npx pwa-asset-generator ./src/assets/favicon.svg ./src/assets/ -i ./src/index.html -m ./src manifest.json -b "linear-gradient(to bottom, rgba(255,255,255,0.15) 0%, rgba(0,0,0,0.15) 100%), radial-gradient(at top center, rgba(255,255,255,0.40) 0%, rgba(0,0,0,0.40) 120%) #989898" -p 5%`
 
@@ -237,7 +251,7 @@ Use the following tool and command line:
 
 Once done with your work, from your fork's working branch, make a GitHub pull request to have your code reviewed, merged, and included in the next release. It's always optimal to sync with us prior to engaging in extensive new development work.
 
-## Development Instructions & Guidelines
+## Development Instructions & Guidelines Documentation
 
 For comprehensive development guidance, please refer to these instruction files:
 
@@ -245,16 +259,22 @@ For comprehensive development guidance, please refer to these instruction files:
 - **[COPILOT.md](./COPILOT.md)**: Complete KIP project guidelines including architecture, services, widget development patterns, theming, and Signal K integration.
 - **[Angular Instructions](./.github/instructions/angular.instructions.md)**: Modern Angular v20+ coding standards, component patterns, and framework best practices.
 
-### **Performance & SVG Animation**
-For guidance on high-performance widget animations (e.g., wind dial rotations, laylines, wind sectors) using requestAnimationFrame outside Angular's change detection, see the new section 12 "SVG Animation Utilities" in [COPILOT.md](./COPILOT.md#12-svg-animation-utilities-requestanimationframe-helpers).
-
 ### **Development Workflow:**
 1. **Start Here**: Read `COPILOT.md` for KIP-specific architecture and patterns.
 2. **Angular Standards**: Follow `.github/instructions/angular.instructions.md` for modern Angular development.
 3. **Setup & Build**: Use this README for project setup and build commands.
 
 ### **Key Priorities:**
-- **Widget Development**: Always extend `BaseWidgetComponent` (see COPILOT.md).
+- **Widget Development**: Use the Host2 widget pattern (signals + directives) and scaffold new widgets with the `create-host2-widget` schematic (see `COPILOT.md`).
 - **Angular Patterns**: Use signals, standalone components, and modern control flow.
 - **Theming**: Follow KIP's theme system for consistent UI.
 - **Code Quality**: Run `npm run lint` before commits.
+
+KIP is open-source under the MIT license, built by the community and 100% free. [Join the community](https://discord.gg/AMDYT2DQga) on Discord or contribute to the project on GitHub!
+
+# Connect, Share, and Support
+KIP has its own Discord Signal K channel for getting in touch. Join us at https://discord.gg/AMDYT2DQga
+
+# Features, Ideas, Bugs
+See KIP's GitHub project for the latest feature requests:
+https://github.com/mxtommy/Kip/issues

package/docs/widget-schematic.md

@@ -0,0 +1,102 @@
+## Host2 Widget Schematic
+
+Use the custom schematic to scaffold a new Host2 architecture widget.
+
+### Command
+
+```
+npx schematics ./tools/schematics/collection.json:create-host2-widget \
+  --name speed-over-ground \
+  --title "Speed Over Ground" \
+  --description "Displays SOG from navigation.speedOverGround" \
+  --icon navigation-speed \
+  --path-key numericPath \
+  --path-description "Speed Over Ground" \
+  --convert-unit-to knots \
+  --sample-time 1000 \
+  --register-widget Core
+```
+
+Only the required flags are `--name`, `--title`, `--description`, and `--icon` when running non-interactively. By default `--dry-run=false` is applied via the npm script.
+
+### Prompting Behavior
+
+The schematic now uses Angular schema `x-prompt` for both required and optional fields.
+
+Modes:
+1. Non-interactive (default when values supplied or CLI run without `--interactive`): Only missing required fields will prompt; others use defaults.
+2. Interactive (`--interactive` or `--interactive=true`): Prompts sequentially for every field (required + optional) unless you provided it on the command line.
+
+Flag naming: CLI flags must be kebab-case. Each dashed flag maps to camelCase schema properties (e.g. `--register-widget` → `registerWidget`, `--sample-time` → `sampleTime`). Using camelCase directly (e.g. `--registerWidget`) will fail with an "Unknown argument" error.
+
+Examples:
+```
+# Minimal required (will prompt for any missing among required)
+npm run generate:widget -- --name depth --title Depth --description "Shows depth" --icon depth-icon --register-widget Core
+
+# Full guided session (asks optional too)
+npm run generate:widget -- --interactive --name aws --title "Apparent Wind" --description "Displays apparent wind" --icon wind --register-widget Core
+
+# Skip service registration
+npm run generate:widget -- --name scratch --title Scratch --description "Sandbox" --icon placeholder --register-widget no
+```
+
+### Important Options (subset)
+
+| Option | Default | Notes |
+| ------ | ------- | ----- |
+| name | (none) | Kebab-case base name without `widget-` prefix |
+| title | (none) | Display name inserted into widget definition |
+| description | (none) | One-line description for registry |
+| icon | (none) | Icon key placeholder (replace later) |
+| category | Core | One of Core, Gauge, Component, Racing |
+| pathKey (flag: --path-key) | signalKPath | Internal key used for data stream observation |
+| pathDescription (flag: --path-description) | My Path | Shown in config UIs (future) |
+| pathType (flag: --path-type) | number | number|string|boolean|Date |
+| convertUnitTo (flag: --convert-unit-to) | unitless | Target display unit (UnitsService) |
+| sampleTime (flag: --sample-time) | 1000 | ms between sampled updates |
+| registerWidget (flag: --register-widget) | (none) | Category (Core/Gauge/Component/Racing) or 'no' to skip service update |
+| addSpec | true | Generates a basic host test wrapper spec |
+| readme | true | Emits README.md with scaffold notes |
+| interactive | false | Use `--interactive` to have the CLI ask for any values you did not supply |
+
+### What Gets Generated
+
+```
+src/app/widgets/widget-<name>/<name>.component.ts
+src/app/widgets/widget-<name>/<name>.component.html
+src/app/widgets/widget-<name>/<name>.component.scss
+src/app/widgets/widget-<name>/<name>.component.spec.ts (if --addSpec)
+src/app/widgets/widget-<name>/README.md (if --readme)
+```
+
+If `registerWidget` is not set to `no`, the schematic also updates `WidgetService`:
+1. Adds an import for the new component.
+2. Adds the component class to `_componentTypeMap`.
+3. Inserts a widget definition object into `_widgetDefinition` (automatically ordered within its category).
+
+### After Generation Checklist
+
+- Replace placeholder `icon` in the widget definition with a real SVG symbol id.
+- Adjust `DEFAULT_CONFIG.paths` if you need multiple paths (add entries & observers in one `untracked` block).
+- Implement formatting / unit display logic using existing helper services if needed.
+- Flesh out the spec with domain assertions (current spec only verifies instantiation).
+
+### Removing a Generated Widget
+
+Manual cleanup steps:
+1. Delete the folder `src/app/widgets/widget-<name>`.
+2. Remove the import, map entry, and definition block for the widget from `WidgetService`.
+
+### Troubleshooting
+
+| Symptom | Cause | Fix |
+| ------- | ----- | --- |
+| Duplicate README like `README<name>.md` | Older schematic version left name in filename | Delete the redundant file & upgrade schematic (already fixed) |
+| Widget already exists error | Folder collision | Choose a different `--name` or delete the existing widget |
+| No WidgetService update | Service path changed | Adjust `WIDGET_SERVICE` constant in schematic factory |
+
+### Development Notes
+
+- Template sources end with `.template`; a post-processing rule strips the suffix for final emission.
+- Config UI generation was intentionally removed; future re-introduction would require new templates.