@mxtommy/kip 4.5.0 → 4.5.2

package/.github/instructions/project.instructions.md

@@ -1,468 +0,0 @@
-# KIP Project Instructions
-
-This file is longer-form reference material. For the canonical, up-to-date KIP coding rules (especially Host2 widgets), follow [.github/copilot-instructions.md](../copilot-instructions.md).
-
-## 1. Project Overview
-KIP Instrument MFD is an advanced and versatile marine instrumentation package designed to display Signal K data in a modern, customizable dashboard, on boats. It provides real-time visualization of navigation, wind, engine, and other marine data streams offered by Signal K, supporting a wide range of widgets and configuration options. The project aims to deliver a user-friendly, extensible, and visually appealing interface for both professional and recreational marine users.
-
-- **Key technologies:** Angular (v20+), Angular Material, Signal K, TypeScript, SCSS.
-
----
-
-## 2. Architecture & Structure
-- **Main folders:**  
-  - `src/app/`: Main application code.
-  - `src/app/widgets/`: Widget components (e.g., wind, autopilot).
-  - `src/app/widget-config/`: Widget configuration components and logic.
-  - `src/app/core/`: Core services, interfaces, and utilities.
-- **Component structure:**  
-  - Each widget has its own component, template, and theme SCSS in `src/app/widgets/`.
-  - All widget configuration logic and UI is centralized and handled independently by components in `src/app/widget-config/`.
-  - Creating a new widget does not require changes to `src/app/widget-config/` unless your widget introduces new configuration properties or needs a custom config UI.
-  - The main configuration form logic is in `src/app/widget-config/modal-widget-config/`. For unique widget config needs, you may add a new config component (e.g., `modal-widget-<name>-config`).
-  - Widget logic/UI and widget configuration are separate concepts that work together.
-
-### Finalized architecture (2026 Q1)
-- **History series reconciliation pipeline:** Dashboard widget topology is normalized by `DashboardHistorySeriesSyncService` and reconciled through `KipSeriesApiClientService` into plugin-backed series definitions.
-- **Dataset lifecycle centralization:** `WidgetDatasetOrchestratorService` is the write-owner for widget datasets (create/edit/remove and owner-based cleanup).
-- **Shared history adaptation:** `HistoryToChartMapperService` centralizes History API values-to-chart datapoint mapping, including average aliases and circular-angle summary stats.
-- **Delete-path cleanup simplification:** Dashboard delete flow now performs owner UUID dataset cleanup via lifecycle service instead of selector-specific branches.
-
-### Architecture guardrails for contributors
-- Replace direct widget/dashboard `DatasetStreamService` write calls with `WidgetDatasetOrchestratorService` sync/remove helpers.
-- Preserve stable widget UUID ownership contracts; these IDs are used for dataset and series reconciliation behavior.
-- Keep history response transformation logic in `HistoryToChartMapperService` to avoid divergence across chart consumers.
-- Avoid reintroducing legacy widget-selector cleanup branches.
-
----
-
-## 4. Conventions & Patterns
-- **Naming:**  
-  - Use descriptive, camelCase names for variables and controls.
-  - Widget config properties match the widget’s function (e.g., `trueWindAngle`, `drift`).
-- **Forms:**  
-  - Use Angular Reactive Forms for all configuration UIs.
-  - Group related controls in form groups.
-- **Theming:**  
-  - Use SCSS mixins for light/dark themes.
-  - Theme mixins must be included in global or component styles.
-
----
-
-## 5. Development Workflow
-- **Linting:**  
-  - Run `npm run lint` before every commit (enforced with Husky pre-commit hook).
-- **Testing:**  
-  - _To be defined._
-- **Build & Serve:**  
-  - `npm run dev` for development server.
-  - `npm run build:dev` for KIP only development build.
-  - `npm run build:prod` for KIP only production build.
-  - `npm run build:all` for KIP and KIP plugin production build.
-
----
-
-## 6. Documentation & Comments
-- **Document all custom validators and business rules.**
-- **Update this file and the README with any major changes or new patterns.**
-- **JSDoc requirement:** Every public TypeScript property and public method must include full JSDoc containing: purpose, parameters, return value, and at least one usage example.
-
----
-
-
-## 8. Core Service Summaries
-All major services in `src/app/core/services/` are summarized below for Copilot and developer context. Each entry includes purpose, key methods/responsibilities, dependencies, and usage notes.
-
-- **AppNetworkInitService (`app-initNetwork.service.ts`)**
-  - Purpose: Loads network services (Signal K connection, authentication, Storage Service) and retrieves configurations from the Signal K server and loaded it before app startup using Angular's `APP_INITIALIZER`.
-  - Key methods: `initNetworkServices()`, config loading, login management.
-  - Dependencies: SignalKConnectionService, AuthenticationService, StorageService, DataService, SignalKDeltaService.
-  - Usage: Ensures network, authentication, Storage Service and configuration are ready before app bootstraps.
-
-- **AuthenticationService (`authentication.service.ts`)**
-  - Purpose: Handles user/device authentication with the Signal K server.
-  - Key methods: `login()`, `logout()`, token management, exposes `isLoggedIn$` observable.
-  - Dependencies: SignalKConnectionService, HttpClient.
-
-- **DialogService (`dialog.service.ts`)**
-  - Purpose: Centralizes all app dialogs using Angular Material.
-  - Dependencies: MatDialog, Dialog components.
-  - Usage: Used throughout the app to open modals and dialogs for user interaction.
-
-- **SignalKConnectionService (`signalk-connection.service.ts`)**
-  - Purpose: Manages the WebSocket connection to the Signal K server, including reconnect logic and status tracking.
-  - Key methods: `connect()`, `disconnect()`, status observables.
-  - Dependencies: WebSocket, AuthenticationService.
-
-- **SignalKDeltaService (`signalk-delta.service.ts`)**
-  - Purpose: Handles real-time delta updates from Signal K, distributing data to widgets and services.
-  - Key methods: Delta subscription, data distribution.
-  - Dependencies: SignalKConnectionService, DataService.
-
-- **DataService (`data.service.ts`)**
-  - Purpose: Central data provider for Signal K and other sources; handles subscriptions, value updates, and metadata management.
-  - Key methods: `subscribeToPath()`, `getValue()`, `getMetadata()`, data and metadata update distribution.
-  - Dependencies: SignalKDeltaService, StorageService.
-
-- **AppService (`app-service.ts`)**
-  - Purpose: Centralizes app-wide utilities, notifications, and theme management.
-  - Key methods: Notification helpers, theme switching, app-level utilities.
-  - Dependencies: Angular core, theme and notification services.
-
-- **UIEventService (`uiEvent.service.ts`)**
-  - Purpose: Manages UI events such as drag, fullscreen, wake lock, and hotkeys.
-  - Key methods: Event emitters, hotkey handlers.
-  - Dependencies: Angular core, browser APIs.
-
-- **SettingsService (`settings.service.ts`)**
-  - Purpose: Manages persistent app settings, user preferences, and configuration storage.
-  - Key methods: `getSetting()`, `setSetting()`, config file management.
-  - Dependencies: StorageService.
-
-- **StorageService (`storage.service.ts`)**
-  - Purpose: Provides persistent storage for app data, settings, and user preferences.
-  - Key methods: `getItem()`, `setItem()`, config file management.
-  - Dependencies: LocalStorage, IndexedDB, or similar.
-
-- **NotificationsService (`notifications.service.ts`)**
-  - Key methods: Notification state management, audio/visual alerts, muting.
-  - Dependencies: SettingsService, DataService, SignalkRequestsService.
-
-- **ToastService (`toast.service.ts`)**
-  - Purpose: In-app snackbars using Angular Material.
-  - Key methods: `show(message, duration = 1500, silent = true, action = 'Dismiss', severity = 'message')`.
-  - Dependencies: MatSnackBar, SettingsService.
-  - Usage: Use for short, user-visible feedback (login errors, PUT failures, success confirmations). Sound is suppressed when `silent=true` or user sound settings disable audio.
-
-- **CanvasService (`canvas.service.ts`)**
-  - Purpose: Provides drawing and rendering utilities for widgets and dashboard components.
-  - Key methods: Canvas context helpers, drawing utilities.
-  - Dependencies: None (core Angular).
-
-- **DashboardService (`dashboard.service.ts`)**
-  - Purpose: Handles dashboard layout, widget arrangement, and dashboard state.
-  - Key methods: Layout management, widget arrangement, dashboard state.
-  - Dependencies: StorageService, WidgetService.
-
-- **DatasetStreamService (`dataset-stream.service.ts`)**
-  - Purpose: Manages data sets, including loading, saving, and updating widget data sources.
-  - Key methods: Data set CRUD, data source updates.
-  - Dependencies: DataService, StorageService.
-
-- **WidgetDatasetOrchestratorService (`widget-dataset-orchestrator.service.ts`)**
-  - Purpose: Centralized dataset orchestration for widget lifecycle operations.
-  - Key methods: `syncDataChartDataset()`, `syncNumericMiniChartDataset()`, `syncWindTrendsDatasets()`, `removeOwnedDatasets()`.
-  - Dependencies: DatasetStreamService.
-  - Usage: Preferred write path for widget/dash dataset lifecycle actions.
-
-- **HistoryToChartMapperService (`history-to-chart-mapper.service.ts`)**
-  - Purpose: Shared adapter for converting History API value responses into chart datapoints.
-  - Key methods: `mapValuesToChartDatapoints()`.
-  - Dependencies: None (core mapping service).
-  - Usage: Keeps chart history behavior consistent across all consumers.
-
-- **DashboardHistorySeriesSyncService (`dashboard-history-series-sync.service.ts`)**
-  - Purpose: Derives desired historical-series definitions from current dashboard/widget state and reconciles with plugin backend.
-  - Key methods: Internal extraction + debounced reconcile scheduling.
-  - Dependencies: DashboardService, KipSeriesApiClientService, SignalKConnectionService.
-  - Usage: Single orchestration path for add/edit/delete/copy/paste/duplicate widget series convergence.
-
-- **KipSeriesApiClientService (`kip-series-api-client.service.ts`)**
-  - Purpose: Frontend bridge to KIP plugin series reconcile endpoint.
-  - Key methods: `reconcileSeries()`.
-  - Dependencies: HttpClient, SignalKConnectionService.
-  - Usage: Posts full desired series definitions to plugin for canonical reconciliation.
-
-- **PluginConfigClientService (`plugin-config-client.service.ts`)**
-  - Purpose: Plugin configuration foundation service for dependency checks and plugin state/config persistence via Signal K `/plugins` endpoints.
-  - Key methods: `listPlugins()`, `getPlugin()`, `getPluginConfig()`, `savePluginConfig()`, `setPluginEnabled()`, `validateDependency()`, `normalizePluginSchema()`.
-  - Dependencies: HttpClient, SignalKConnectionService.
-  - Usage: Source of truth for plugin detection and config save flows; no plugin install/uninstall support.
-
-- **SignalKRequestsService (`signalk-requests.service.ts`)**
-  - Purpose: Handles requests to the Signal K server, such as PUT/POST operations and custom actions.
-  - Key methods: `sendRequest()`, custom action handlers.
-  - Dependencies: SignalKConnectionService, DataService.
-
-- **TimersService (`timers.service.ts`)**
-  - Purpose: Centralized timer utility for app and widgets, supporting intervals, timeouts, and scheduling.
-  - Key methods: Timer creation, interval management.
-  - Dependencies: Angular core.
-
-- **UnitsService (`units.service.ts`)**
-  - Purpose: Handles unit conversion and formatting for all displayed data.
-  - Key methods: `convert()`, `format()`, unit preference management.
-  - Dependencies: SettingsService.
-
-- **WidgetService (`widget.service.ts`)**
-  - Purpose: Manages widget registration, configuration, and lifecycle.
-  - Key methods: Widget registration, config helpers, lifecycle management.
-  - Dependencies: DashboardService, DataService.
-
----
-
-## 9. Host2 Widget Architecture
-
-Host2 widget rules are maintained in one place to avoid duplication. Use the canonical Host2 widget contract and patterns from:
-
-- [.github/copilot-instructions.md](../copilot-instructions.md)
-
-Quick reminders:
-- Always guard `runtime.options()` and `cfg.paths?.key?.path` before observing.
-- Register all `streams.observe(...)` in a single `effect()` and group subscriptions in one `untracked()` block.
-- Keep transient UI state in signals; do not mutate the merged config object.
----
-
-## 10. KIP Colors, Theming, and Widget Best Practices
-
-- **KIP Color & Theming Concepts:**
-  - KIP uses a centralized theme system with color roles defined in SCSS and exposed to TypeScript via CSS variables and the `AppService`.
-  - Theme colors (e.g., `contrast`, `blue`, `zoneAlarm`, `background`, etc.) are defined in SCSS files (`styles.scss`, theme partials) and mapped to CSS variables (e.g., `--kip-blue-color`).
-  - The `AppService` provides a `cssThemeColorRoles$` observable and a `theme()` signal for accessing current theme colors in TypeScript.
-  - Theme switching (light, dark, night) is handled by toggling classes on `<body>` and updating CSS variables.
-  - All widgets should use theme colors for UI consistency and accessibility.
-
-- **Best Practices for Using Colors & Theming in Widgets:**
-  - **TypeScript:**
-    - Access theme colors via `this.theme().<colorRole>` (e.g., `this.theme().zoneAlarm`, `this.theme().contrast`).
-    - Never hardcode color hex values in widget TypeScript; always use theme roles.
-    - For dynamic coloring (e.g., based on state/zones), use the correct theme role for each state (see `zoneAlarm`, `zoneWarn`, etc.).
-    - Use the color mapping pattern as in `getColors()` for supporting multiple color roles and dim/dimmer variants.
-    - When updating widget visuals (e.g., gauge, highlights), always update with theme colors to support live theme switching.
-  - **SCSS:**
-    - Use CSS variables (e.g., `var(--kip-blue-color)`) for all color assignments in widget/component styles.
-    - Do not use static hex codes; always reference a theme variable.
-    - For custom widget styles, define new CSS variables in the theme partials if needed, and use them in your SCSS.
-    - Use the `.light-theme`, `.night-theme`, and default (dark) selectors to override variables for each theme as needed.
-    - Use SCSS mixins for reusable style patterns and to support theme switching.
-  - **General:**
-    - Always test widgets in all themes (light, dark, night) to ensure colors are accessible and visually correct.
-    - Use theme roles for all UI elements, including backgrounds, borders, text, and highlights.
-    - For state-based coloring (e.g., alarms, warnings), use the corresponding zone color from the theme.
-    - Avoid inline styles for colors; prefer class-based or variable-based styling.
----
-
-## 11. Additional Instructions & Cross-References
-
-### **Related Instruction Files:**
-- **README.md**: Project overview, setup instructions, and development guidelines
-- **`.github/instructions/angular.instructions.md`**: Detailed Angular v20+ coding standards, component patterns, and framework-specific best practices
-
-### **Instruction Hierarchy:**
-1. **Primary**: This `COPILOT.md` file (KIP-specific project guidelines and architecture)
-2. **Secondary**: `.github/instructions/angular.instructions.md` (Angular framework standards and modern patterns)
-3. **Tertiary**: `README.md` (General project information and setup)
-
-### **Usage Notes:**
-- All Angular development should follow both this COPILOT.md file AND the angular.instructions.md guidelines
-- When conflicts arise, KIP-specific guidelines in this file take precedence over general Angular patterns
-- For widget development, use the Host2 widget architecture (sections 9 & 13) – standalone components + directives (no inheritance)
-- For general Angular coding (components, services, forms, component), follow the modern Angular v20+ patterns in angular.instructions.md
-
----
-
-## 12. SVG Animation Utilities (requestAnimationFrame Helpers)
-
-High-performance SVG animations in KIP (e.g., wind steering dial laylines, sector bands, rotating indicators) use a small set of utilities found in `src/app/widgets/utils/svg-animate.util.ts` to ensure:
-
-- No unnecessary Angular change detection on every animation frame
-- Consistent easing and shortest‑path angle interpolation
-- Centralized cancellation logic (preventing overlapping animations per element/concern)
-- Readable, minimal widget component code
-
-### 12.1 Design Principles
-1. Run frame loops outside Angular's `NgZone` to avoid triggering change detection ~60 times/sec.
-2. Only re-enter the zone once per animation (on completion callback) if UI state needs Angular binding updates.
-3. Gate “tiny” animations (angle deltas below a threshold) to avoid visual jitter and wasted work.
-4. Always animate the shortest angular path (wrap via ±180 logic) for rotational continuity.
-5. Provide generic primitives (angle + sector interpolation) so components don’t duplicate interpolation math.
-
-### 12.2 Provided Functions
-| Function | Purpose | Key Inputs | Notes |
-|----------|---------|-----------|-------|
-| `animateRotation(el, fromDeg, toDeg, durationMs, onDone?, ngZone?)` | Smoothly rotates an SVG element (`transform: rotate(...)`) | Element, start+end angles, duration | Tracks per-element frame id internally (WeakMap) so a new call cancels the prior rotation for that element. |
-| `animateRudderWidth(rectEl, fromWidth, toWidth, durationMs, onDone?, ngZone?)` | Interpolates a `<rect>` width | SVGRectElement, numeric widths | Same outside-zone strategy; width set via `setAttribute`. |
-| `animateAngleTransition(fromDeg, toDeg, durationMs, applyFn, onDone?, ngZone?)` | Generic angle interpolation (no DOM assumptions) | Angles, duration, callback(angle) | Use for derived geometry (e.g., computing a path string). |
-| `animateSectorTransition(from: SectorAngles, to: SectorAngles, durationMs, applyFn, onDone?, ngZone?)` | Interpolates a structured group of three related angles (`min, mid, max`) | Objects with `{min, mid, max}` | Uses same angle normalization per field + easing. |
-
-`SectorAngles` interface:
-```
-interface SectorAngles { min: number; mid: number; max: number; }
-```
-
-### 12.3 NgZone Strategy
-All helpers accept an optional `NgZone`. When provided they:
-1. Call `ngZone.runOutsideAngular()` wrapping the frame loop.
-2. Use `requestAnimationFrame` until elapsed >= duration.
-3. Apply easing (cubic in/out) and normalized shortest-path interpolation.
-4. On final frame, invoke `onDone` inside Angular (`ngZone.run(...)`) so any bound template values update once.
-
-If `ngZone` is omitted they still function (pure browser environment) — suitable for non-Angular contexts or tests.
-
-### 12.4 Cancellation Rules
-- `animateRotation` & `animateRudderWidth` internally keep a WeakMap<Element, frameId>; a new call replaces the old.
-- Callers of `animateAngleTransition` / `animateSectorTransition` receive the raw `frameId` and MUST store & cancel it if a new animation is started for the same conceptual target (e.g., a layline or sector band) before completion.
-- Always cancel outstanding frame ids in `ngOnDestroy` to avoid orphan rAF callbacks if the component is torn down mid-animation.
-
-### 12.5 Angle Handling Details
-- Input angles are normalized to [0, 360).
-- Delta uses wrapped signed difference: `((to - from + 540) % 360) - 180` for shortest path.
-- Interpolated angle = `from + easedT * delta`; final angle normalized again.
-- A small epsilon (e.g., ~0.25°) can be used by callers to skip tiny animations; component sets `EPS_ANGLE` constant.
-
-### 12.6 Easing
-Currently a fixed cubic ease-in-out: `t < 0.5 ? 4t^3 : 1 - pow(-2t + 2, 3)/2`. Chosen for smooth acceleration/deceleration without overshoot. If future needs arise, expose an optional easing parameter (keep backward compatibility by defaulting to cubic in/out).
-
-### 12.7 Usage Patterns
-
-Rotate an indicator:
-```
-this.animationFrameIds.set(
-  el,
-  animateRotation(el, currentAngle, targetAngle, 300, () => { /* one-time post animation logic */ }, this.ngZone)
-);
-```
-
-Animate a layline path angle:
-```
-if (this.portLaylineAnimId) cancelAnimationFrame(this.portLaylineAnimId);
-this.portLaylineAnimId = animateAngleTransition(
-  prevAngle,
-  nextAngle,
-  300,
-  angle => this.updateLaylinePath(angle, /* isPort= */ true),
-  () => { this.portLaylineAnimId = null; },
-  this.ngZone
-);
-```
-
-Animate a wind sector (three angles):
-```
-if (this.portSectorAnimId) cancelAnimationFrame(this.portSectorAnimId);
-this.portSectorAnimId = animateSectorTransition(
-  previousSector,
-  newSector,
-  300,
-  sector => this.updateSectorPath(sector, true),
-  () => { this.portSectorAnimId = null; },
-  this.ngZone
-);
-```
-
-### 12.8 When NOT to Animate
-- First render / initialization where the user has no prior visual expectation — just set final state.
-- Discontinuous jumps (e.g., compass wrap after data gap) that would produce a long spin — snap instead.
-- Extremely small (< epsilon) changes — update instantly.
-
-### 12.9 Testing Tips
-- For deterministic unit tests, inject a mock `performance.now()` / substitute a manual time advance, or abstract the timestamp acquisition behind a seam if greater test coverage is required.
-- Validate shortest-path logic with cases like `from=350 → to=10` (should rotate +20°, not -340°).
-- Confirm cancellation by firing a second animation mid-way; the first should not apply further frames.
-
-### 12.10 Future Extensions (Backlog Ideas)
-- Optional custom easing function parameter.
-- Support for group animations (batch multiple angle transitions under one rAF loop for micro-optimizations).
-- Auto-prefetch “snap if > threshold degrees” heuristic inside helpers (today caller decides).
-
----
-
-## 13. create-host2-widget Schematic (Host2 Widget Generator)
-
-The `create-host2-widget` schematic scaffolds a production-ready Host2 widget with optional zones support, tests, and README guidance. It enforces current architectural patterns (signals + directives) and reduces manual registration effort.
-
-### 13.1 When To Use
-Use the schematic for any new widget that:
-- Consumes one (or more, to be added later) Signal K path values.
-- Requires standard lifecycle (config merging, unit conversion, timeout handling) via `WidgetRuntimeDirective` + `WidgetStreamsDirective`.
-- Optionally needs zones metadata visualization.
-
-### 13.2 Invocation Examples
-Minimal (interactive prompts for all options):
-```
-npm run generate:widget
-```
-or
-```
-ng g create-host2-widget
-```
-
-Non-interactive with explicit options:
-```
-npx schematics ./tools/schematics/collection.json:create-host2-widget \
-  --name tides-chart \
-  --title "Tides Chart" \
-  --registerWidget Core \
-  --pathType number \
-  --pathDefault navigation.speedThroughWater \
-  --zonesSupport=false \
-  --addSpec=true \
-  --todoBlock=false \
-  --readme=true
-```
-
-### 13.3 Options Reference
-| Option | Values / Type | Default | Purpose | Notes |
-|--------|---------------|---------|---------|-------|
-| `name` | string (kebab-case) | — (required) | Base name (component selector becomes `widget-<name>`) | Must be unique under `src/app/widgets/` |
-| `title` | string | — (required) | Display title (Add Widget dialog) | Used in WidgetService definition object |
-| `registerWidget` | `Core | Gauge | Component | Racing | No` | — | Auto-register in `widget.service.ts` or skip | `No` (case-insensitive) means skip registration |
-| `pathType` | `number|string|boolean|Date` | `number` | Primary path value type | Influences stream conversion & formatting |
-| `pathDefault` | string/null | `null` | Pre-filled Signal K path | Leave null if unsure |
-| `zonesSupport` | boolean | `false` | Include zones metadata scaffolding | Adds metadata directive & highlights logic placeholder |
-| `addSpec` | boolean | `true` | Generate spec test file | Basic presence test; extend manually |
-| `todoBlock` | boolean | `true` | Include instructional TODO comments | Set false for clean production scaffold |
-| `readme` | boolean | `true` | Generate widget README | Developer-focused quick guide |
-| `debugLogging` | boolean | `false` | Verbose schematic execution logs | Helpful when troubleshooting formatting/registration |
-
-Hidden defaults inserted into templates: `sampleTime=1000`, `convertUnitTo=null`, placeholder icon & description (replace post-gen).
-
-### 13.4 Generated Artifacts
-- `widget-<name>.component.ts|html|scss` – Host2 component & view.
-- Optional `widget-<name>.component.spec.ts` when `--addSpec=true`.
-- Optional `README.md` (widget-local developer instructions) when `--readme=true`.
-- Service registration (import, component map entry, widget definition object) unless `registerWidget=No`.
-
-### 13.5 Post-Generation Checklist
-- Replace placeholder icon (`placeholder-icon`) with an actual symbol id in `src/assets/svg/icons.svg` and update `widget.service.ts` entry.
-- Write a concise, user-facing description in the WidgetService definition object.
-- Adjust `DEFAULT_CONFIG.displayName` and color.
-- Decide whether to keep or remove TODO comments (regen with `--todoBlock=false` once stable).
-- Add any additional paths (with guards) and corresponding `streams.observe` registrations.
-- If zones used: adapt highlight computation (unit, scale bounds, colors) and remove unused scaffolding.
-- Add/expand tests (mock streams, theme, optional zones metadata).
-
-### 13.6 Zones Support Notes
-If `--zonesSupport=true`:
-- `WidgetMetadataDirective` is injected; you must call `metadata.observe('signalKPath')` (or other path key) only if a path is configured.
-- `metadata.zones()` exposes current zones; pass through `getHighlights` with min/max scale & unit for overlays.
-- Always guard: missing path OR zones → return empty highlight array.
-
-### 13.7 Common Pitfalls & Resolutions
-| Pitfall | Cause | Resolution |
-|---------|-------|-----------|
-| Widget not listed in Add dialog | Chose `registerWidget No` or category mismatch | Regenerate OR manually add definition to `widget.service.ts` |
-| Duplicate import/service entry | Manual edits then re-run schematic | Remove redundant lines; schematic guards imports but verify component map |
-| Runtime error in highlights | Accessing undefined scale or wrong path key | Guard `cfg.paths['signalKPath']` and ensure scale present before computing |
-| Units not converting | Missing or null `convertUnitTo` in path config | Add target unit in path definition (number types only) |
-| Tests failing after adding new paths | Spec doesn’t mock added streams | Update spec to provide minimal mock path observation |
-
-### 13.8 Recommended Development Flow
-1. Generate widget with `--todoBlock=true` for guidance.
-2. Implement path observation & basic rendering logic.
-3. Add zones (if required) and verify highlight behavior with test data.
-4. Remove TODO comments (or regenerate clean variant) once stable.
-5. Add additional paths & unit tests (timeout, no-path, zones absent).
-6. Finalize icon & description, then open PR.
-
-### 13.9 Troubleshooting Registration
-If the schematic ran but the widget is missing:
-1. Open `widget.service.ts` and search for your selector (e.g., `widget-tides-chart`).
-2. Confirm: import line, component map entry, and definition object exist.
-3. If absent, re-run with `--debugLogging=true` to inspect logs, or manually paste the generated object from another widget as a template.
-
-### 13.10 Conventions Recap
-- One effect for all observers.
-- Guard optional paths before observing.
-- Signals for state; avoid extraneous change detection.
-- Use `untracked()` when registering observers to prevent superfluous effect retriggers.
----

package/.github/workflows/ci.yml

@@ -1,37 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [ main, master, develop ]
-  pull_request:
-    branches: [ main, master, develop ]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-
-    strategy:
-      matrix:
-        node-version: [20.x, 22.x]
-
-    steps:
-    - name: Checkout repository
-      uses: actions/checkout@v4
-
-    - name: Setup Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v4
-      with:
-        node-version: ${{ matrix.node-version }}
-        cache: 'npm'
-
-    - name: Install dependencies
-      run: npm i
-
-    - name: Lint
-      run: npm run lint
-
-    - name: Run tests
-      run: npm run test:headless
-
-    - name: Build All (Webapp & Plugin)
-      run: npm run build:all

package/docs/widget-schematic.md

@@ -1,102 +0,0 @@
-## 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.