@telemetryos/root-sdk 1.14.0 → 1.16.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @telemetryos/root-sdk
 
+## 1.16.0
+
+### Minor Changes
+
+- 15a06b5: Iframe management, heartbeat logic, and SDK fixes
+  - Added iframe lifecycle management and heartbeat logic for monitoring application health
+  - Introduced dependency store for tracking application dependencies
+  - Added subscription registry for managing real-time subscriptions in the API coordinator
+  - Re-exported missing root-sdk types and utilities from the sdk package (Navigation class, media types, bridge utilities, client types)
+  - Fixed application store namespace from incorrect value to "application"
+  - Removed unused media fields from root-sdk
+
+### Patch Changes
+
+- Updated dependencies [15a06b5]
+  - @telemetryos/sdk-bridge@1.16.0
+
+## 1.15.0
+
+### Minor Changes
+
+- ### New Features
+  - **Theme system** — Templates now ship with 8 built-in themes (`telemetryos`, `neon-pulse`, `solar-flare`, `arctic-aurora`, `emerald-matrix`, `the-matrix`, `plain-light`, `plain-dark`), each with a complete color palette including gradients, text colors, accents, and status indicators.
+  - **FlickeringGrid component** — New canvas-based animated background component with configurable square size, grid gap, flicker chance, opacity, and color.
+  - **SettingsSection component** — New collapsible accordion component exported from `@telemetryos/sdk` for organizing settings into expandable sections. Includes `aria-expanded`/`aria-controls` and `inert` support.
+  - **Settings form styles** — New shared CSS (`@telemetryos/sdk/react/styles.css`) with light/dark theme variables for text inputs, selects, sliders, color pickers, toggles, and checkboxes.
+  - **Expanded entrance animations** — Added `flip`, `fade`, `scale`, `slide`, `drop`, `fade-in`, `blur`, `zoom`, `unfold`, `rise`, `glitch`, and `breathe-glow` animations; removed `swing`.
+  - **Dark wordmark** — Added `telemetryos-wordmark-dark.svg` to template assets.
+  - **Root-SDK bridge re-exports** — `@telemetryos/root-sdk` now re-exports `BridgeMessage`, `ClientMessage`, and their validators/formatters from `@telemetryos/sdk-bridge`, so consumers no longer need a direct `sdk-bridge` import.
+
+  ### Infrastructure
+  - Moved template assets from `assets/` to `public/assets/` for automatic Vite build inclusion (both `vite-react-typescript` and `vite-react-typescript-web` templates).
+
+### Patch Changes
+
+- Updated dependencies
+  - @telemetryos/sdk-bridge@1.15.0
+
 ## 1.14.0
 
 ### Minor Changes

package/dist/applications.d.ts

@@ -1,22 +1,108 @@
 import { Client, MessageInterceptor } from './client.js';
+/** The source control origin of an application. */
+export type ApplicationSourceKind = 'github' | 'git' | 'uploaded';
+/** A named entry point that maps a surface (e.g. render, settings, web) to a file path. */
 export type MountPoint = {
-    [key: string]: any;
+    name: string;
     path: string;
 };
+/** A background worker script that runs alongside the application. */
+export type BackgroundWorker = {
+    name: string;
+    path: string;
+};
+/** A Docker container that runs alongside the application on devices. */
+export type Container = unknown;
+/** Full application record including source, build, and metadata fields. */
 export type Application = {
+    kind: ApplicationSourceKind;
+    gitUrl?: string;
+    gitRef?: string;
+    hasGitSshPrivateKey?: boolean;
+    hasHttpCredentials?: boolean;
+    hasGithubToken?: boolean;
+    githubAccount?: string;
+    githubRepository?: string;
+    baseImage: string;
+    buildWorkingPath?: string;
+    buildScript?: string;
+    buildOutputPath?: string;
+    buildEnvironmentVariables?: Record<string, string>;
+    id: string;
+    title: string;
+    description: string;
+    isEnabled: boolean;
+    isProtected: boolean;
+    isGlobal: boolean;
+    isBlock: boolean;
+    useLatest: boolean;
+    versions: ApplicationVersion[];
+    createdAt: string;
+    updatedAt: string;
+};
+/** A specific published version of an application. */
+export type ApplicationVersion = {
     name: string;
-    mountPoints: Record<string, MountPoint>;
+    version: string;
+    logoPath: string;
+    thumbnailPath: string;
+    mountPoints: MountPoint[];
+    backgroundWorkers: BackgroundWorker[];
+    containers: Container[];
+    applicationId: string;
+    buildId: string;
+    baseUrl: string;
+    /** 40-character lowercase hex string uniquely identifying this version. */
+    applicationSpecifier: string;
+    filePaths: string[];
+    publishedAt: string;
 };
+/** Response from {@link Applications.getById}. */
+export type GetByIdResult = {
+    application: Application;
+};
+/** Response from {@link Applications.getBySpecifier}. */
+export type GetBySpecifierResult = {
+    application: Application;
+};
+/** Response from {@link Applications.getAllByMountPoint}. */
+export type GetByMountPointResult = {
+    applications: Application[];
+};
+/** Response containing a resolved URL for an application asset. */
 export type GetUrlResult = {
     url: string;
 };
-export type ApplicationsState = {
-    ready: string[];
-    unavailable: string[];
+/** The download/readiness status of a dependency application on the device. */
+export type ApplicationStatus = 'unloaded' | 'downloading' | 'ready';
+/** A real-time status update for a single dependency application. */
+export type DependencyResult = {
+    status: ApplicationStatus;
+    application: Application | null;
 };
+/**
+ * Provides methods for discovering, querying, and managing application
+ * dependencies within the TelemetryOS platform.
+ *
+ * Accessed via the `applications()` convenience function exported from the SDK.
+ */
 export declare class Applications {
     _client: Client;
     constructor(client: Client);
+    /**
+     * Retrieve a single application by its id.
+     *
+     * @param applicationId The unique identifier of the application to retrieve
+     * @returns A promise that resolves to the application data
+     */
+    getById(applicationId: string): Promise<Application>;
+    /**
+     * Retrieves a single application by specifier
+     *
+     * @param applicationSpecifier The unique specifier of the application to retrieve
+     * @returns A promise that resolves to the application data
+     */
+    getBySpecifier(applicationSpecifier: string): Promise<Application>;
     /**
      * Retrieves all applications with a specific mount point within the current account.
      *
@@ -31,17 +117,6 @@ export declare class Applications {
      * @returns A promise that resolves to an array of applications having the specified mount point
      */
     getAllByMountPoint(mountPoint: string): Promise<Application[]>;
-    /**
-     * Retrieves an application by its name.
-     *
-     * This method allows finding a specific application when you know its name. It's useful
-     * when you need to check if a particular application is available or get its details
-     * before attempting to embed it.
-     *
-     * @param name The name of the application to query for
-     * @returns A promise that resolves to the application object if found, or null if not found
-     */
-    getByName(name: string): Promise<Application | null>;
     /**
      * Sets the dependencies for the current application.
      *
@@ -49,19 +124,23 @@ export declare class Applications {
      * The player will download and prepare these dependencies before they can be loaded.
      *
      * IMPORTANT: This method must be called and awaited before loading any sub-applications
-     * in iframes. Only applications that return as 'ready' should be loaded.
+     * in iframes.
      *
-     * @param applicationSpecifiers An array of application specifiers that this application depends on
-     * @returns A promise that resolves with arrays of ready and unavailable application specifiers
+     * @param applicationSpecifiers A map of application specifier to an array of instance IDs
+     * @returns A function that returns a {@link DependencyHandle} for a given specifier and instance ID
      *
      * @example
      * ```typescript
-     * const result = await client.applications.setDependencies(['app1-hash', 'app2-hash'])
-     * // result.ready: ['app1-hash'] - these can be loaded in iframes
-     * // result.unavailable: ['app2-hash'] - these failed to load
+     * const getHandle = await applications().setDependencies({
+     *   'app1-specifier-hash': ['instance-1', 'instance-2'],
+     *   'app2-specifier-hash': ['instance-1'],
+     * })
+     * const handle = getHandle('app1-specifier-hash', 'instance-1')
+     * handle.onStatus((status) => console.log(status))
+     * const iframe = await handle.frame()
      * ```
      */
-    setDependencies(applicationSpecifiers: Record<string, string[]>): Promise<ApplicationsState>;
+    setDependencies(applicationSpecifiers: Record<string, string[]>): Promise<(applicationSpecifier: string, instanceId: string) => import("./dependency-store.js").DependencyHandle>;
     /**
      * Registers a message interceptor for client messages from sub-applications.
      *

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 import { Applications } from './applications.js';
 import { Media } from './media.js';
-import type { BridgeMessage } from '@telemetryos/sdk-bridge';
+import type { BridgeMessage, ClientMessage } from '@telemetryos/sdk-bridge';
 import { Store } from './store.js';
 import { RootSettingsNavigation } from './root-settings-navigation.js';
 import { Accounts } from './accounts.js';
@@ -12,6 +12,7 @@ import { Currency } from './currency.js';
 import { Environment } from './environment.js';
 import { Mqtt } from './mqtt.js';
 import { Navigation } from './navigation.js';
+import { DependencyStore } from './dependency-store.js';
 /**
  * The maximum time in milliseconds to wait for a response to a request call.
  *
@@ -23,6 +24,12 @@ import { Navigation } from './navigation.js';
  * platform doesn't respond or if network connectivity is lost.
  */
 export declare const requestResponseTimeout: number;
+/**
+ * The interval the client will send it's heartbeat signature to the TelemetryOS platform.
+ * If the platform stops receiving the heartbeat, it will consider the client disconnected,
+ * and clean it's resources as well as try to reload the client application.
+ */
+export declare const heartbeatInterval: number;
 /**
  * A callback function type for handling messages received from the TelemetryOS platform.
  *
@@ -61,7 +68,7 @@ export type SubscriptionResult<D = void> = {
  * }
  * ```
  */
-export type MessageInterceptor = (data: any) => BridgeMessage;
+export type MessageInterceptor = (data: ClientMessage) => BridgeMessage | undefined | void;
 /**
  * Client is the core class that powers communication with the TelemetryOS platform.
  *
@@ -79,6 +86,9 @@ export declare class Client {
     _applicationInstance: string;
     _applicationSpecifier: string;
     _deviceId: string;
+    _heartbeatInterval: NodeJS.Timeout | null;
+    _heartbeatSignature: string;
+    _dependencyStore: DependencyStore;
     _navigation: Navigation;
     _messageInterceptors: Map<string, MessageInterceptor>;
     _onHandlers: Map<string, MessageHandler<any>[]>;

package/dist/dependency-store.d.ts

@@ -0,0 +1,103 @@
+import { Application, ApplicationStatus, DependencyResult } from './applications.js';
+import { Client } from './client.js';
+/**
+ * Manages the set of declared dependency applications and their handles.
+ *
+ * A single DependencyStore is created per {@link Client} and maintains one
+ * {@link DependencyHandle} per specifier+instanceId pair. When dependencies
+ * are updated via {@link setDependencies}, handles for removed dependencies
+ * are destroyed automatically.
+ *
+ * The store also intercepts heartbeat messages from child iframes. If a
+ * dependency stops sending heartbeats, its iframe is automatically reloaded.
+ */
+export declare class DependencyStore {
+    _client: Client;
+    _dependencies: Map<string, DependencyHandle>;
+    _heartbeatTimeouts: Map<string, NodeJS.Timeout>;
+    constructor(client: Client);
+    /**
+     * Sends the full set of dependency specifiers to the platform and reconciles
+     * local handles. Any previously tracked dependency that is no longer present
+     * in the new specifiers map is destroyed.
+     *
+     * @param applicationSpecifiers A map of application specifier to an array of instance IDs
+     */
+    setDependencies(applicationSpecifiers: Record<string, string[]>): Promise<void>;
+    /**
+     * Returns the {@link DependencyHandle} for a given specifier and instance ID,
+     * creating one if it does not already exist.
+     *
+     * @param specifier The application specifier (40-char hex)
+     * @param instanceId The unique instance identifier
+     * @returns The existing or newly created DependencyHandle
+     */
+    handleFor(specifier: string, instanceId: string): DependencyHandle;
+    /**
+     * Resets the heartbeat timeout for the given dependency. If no heartbeat
+     * arrives within {@link missedHeartbeatsThreshold} intervals the
+     * dependency's iframe is reloaded.
+     */
+    _handleHeartbeat(applicationSpecifier: string, applicationInstance: string): void;
+}
+/**
+ * A reactive handle to a single dependency application.
+ *
+ * Created by {@link DependencyStore.handleFor}, a DependencyHandle subscribes to
+ * real-time status updates from the platform for its specifier+instanceId pair.
+ * Consumers can observe status changes via {@link onStatus} and obtain an iframe
+ * element for embedding via {@link frame}.
+ *
+ * @example
+ * ```typescript
+ * const handle = getHandle('specifier', 'instance-1')
+ * handle.onStatus((status) => console.log('status:', status))
+ * const iframe = await handle.frame()
+ * if (iframe) document.body.appendChild(iframe)
+ * ```
+ */
+export declare class DependencyHandle {
+    _store: DependencyStore;
+    _specifier: string;
+    _instanceId: string;
+    _status: ApplicationStatus;
+    _application: Application | null;
+    _iframe: HTMLIFrameElement | null;
+    _onStatusHandlers: Set<(status: ApplicationStatus) => void>;
+    _subscriptionHandler: (message: DependencyResult) => void;
+    /** The current download/readiness status of the dependency. */
+    get status(): ApplicationStatus;
+    /** A deep clone of the application record, or null if not yet available. */
+    get application(): Application | null;
+    constructor(store: DependencyStore, specifier: string, instanceId: string);
+    /**
+     * Returns a promise that resolves with an iframe element once the dependency
+     * is ready, or null if the dependency becomes unloaded before it is ready.
+     *
+     * If the dependency is already ready, the promise resolves immediately with
+     * the cached iframe. The iframe's `src` is pre-configured for the dependency.
+     *
+     * @returns A promise resolving to the iframe element or null
+     */
+    frame(): Promise<HTMLIFrameElement | null>;
+    /**
+     * Registers a callback that fires whenever the dependency status changes.
+     *
+     * @param handler Callback receiving the new {@link ApplicationStatus}
+     * @returns An unsubscribe function that removes the handler
+     */
+    onStatus(handler: (status: ApplicationStatus) => void): () => void;
+    _buildIframe(): HTMLIFrameElement | null;
+    /**
+     * Resets the iframe by clearing it, requesting the host to clean up
+     * subscriptions and state for this instance, then reloading it if the
+     * iframe is still in the DOM.
+     */
+    _resetIframe(): Promise<void>;
+    /**
+     * Tears down this handle: resets status to 'unloaded', blanks the iframe,
+     * requests the host to clean up all subscriptions (window + worker),
+     * notifies status handlers, and unsubscribes from platform updates.
+     */
+    _destroy(): Promise<void>;
+}