@enyo-energy/energy-app-sdk 0.0.194 → 0.0.196

package/README.md

@@ -32,6 +32,7 @@ The official TypeScript SDK for building Energy Apps on the enyo platform. Creat
   - [NetworkAccessGuard](#networkaccessguard)
   - [NetworkDeviceManager](#networkdevicemanager)
   - [Startup pattern](#startup-pattern)
+- [Package Files](#package-files)
 - [Firmware Update Registry](#firmware-update-registry)
   - [Declaring firmware](#declaring-firmware)
   - [Firmware modes](#firmware-modes)
@@ -171,7 +172,8 @@ The SDK exposes several layered building blocks. Pick the one that matches the k
 | Manage electricity tariffs (default tariff, price per kWh) | [`useElectricityTariff()`](#useelectricitytariff-energyappelectricitytariff) |
 | Register a PV system (kWp, DC strings, orientation) | [`usePvSystem()`](#usepvsystem-energyapppvsystem) |
 | Discover capabilities of the active energy manager | [`useEnergyManager()`](#useenergymanager-energyappenergymanager) |
-| Drive a multi-step onboarding flow | [`useOnboarding()`](#useonboarding-energyapponboarding) |
+| Serve your v2 onboarding guides when the host asks for them | [`useOnboardingV2()`](#useonboardingv2-energyapponboardingv2) |
+| Drive a multi-step onboarding flow (v1, deprecated) | [`useOnboarding()`](#useonboarding-energyapponboarding) |
 | Allocate process-local sequential IDs | [`useSequenceGenerator()`](#usesequencegenerator-energyappsequencegenerator) |
 | Manage retries with circuit-breaker semantics | [`RetryManager`](#retry-framework) |
 | Keep an `applianceId` cache in sync with the SDK | [`ApplianceManager`](#appliance-management) |
@@ -1333,8 +1335,36 @@ Requires the `Savings` permission.
 
 ### Operational Utilities
 
+#### `useOnboardingV2(): EnergyAppOnboardingV2`
+
+Serve the onboarding guides your app ships. Guides are **pulled, not published**: you register one handler, and the host calls it with "give me your v2 onboarding guides". You answer with the **complete set** or with **nothing** — there is no save, update or delete, and every answer replaces the host's picture of what your app offers.
+
+```typescript
+await energyApp.useOnboardingV2().registerOnboardingGuidesHandler(async (request) => {
+    const result = { requestId: request.requestId, guides: buildGuides() };
+
+    const { ok, errors } = validateOnboardingV2GuidesResult(result, {
+        files: packageDefinition.files,
+    });
+    if (!ok) {
+        console.error('onboarding guides invalid', errors);
+        return null;   // keep whatever the host already has
+    }
+
+    return result;
+});
+```
+
+`null` and `[]` are **not** the same answer: `[]` says "I genuinely have no guides" and drops the host's cached ones, `null` says "I cannot answer right now" and leaves them alone. Use `null` for transient failures. The host stops waiting after `request.timeoutMs`, so build the guides in memory rather than fetching them.
+
+Each guide must carry the `vendorId`, `modelIds` and `startVariant` it applies to — that is how the host selects one for a run, and there is no publish step left to bind them. See [ONBOARDING.md](./ONBOARDING.md#serving-guides-the-host-pulls-the-app-never-publishes) for the full v2 model.
+
+Not permission-gated.
+
 #### `useOnboarding(): EnergyAppOnboarding`
 
+> **Deprecated** — the v1 model. New guides use the v2 graph model and are served through [`useOnboardingV2()`](#useonboardingv2-energyapponboardingv2).
+
 Drive a multi-step onboarding guide — start / advance / back / skip / cancel, persist responses, and observe step transitions.
 
 ```typescript
@@ -1778,6 +1808,65 @@ async function connectDevice(networkDeviceId: string) {
 
 This pattern matches the wiring used by real Sungrow / Fronius energy-app packages: one `NetworkDeviceManager` per package, `ensureAccess` before every connect, `withAccessGuard` around every poll, and a single `getDevices({ accessStatus: 'granted' })` pass at startup to cover the warm-restart case.
 
+## Package Files
+
+Ship images and other public assets with your package. You declare them by local path
+and name in the package definition, the enyo CLI uploads them during `enyo release`,
+and the rest of the definition refers to each upload **by name** rather than by URL —
+so nothing has to hard-code a URL that only exists after the release.
+
+Today the consumer is the onboarding v2 image block (see ONBOARDING.md).
+
+```typescript
+import {
+    defineEnergyAppPackage,
+    definePublicFile,
+    validatePackageFiles
+} from '@enyo-energy/energy-app-sdk';
+
+const packageDef = defineEnergyAppPackage({
+    // ...
+    files: [
+        definePublicFile({
+            name: 'dip-switches',
+            path: './assets/onboarding/dip-switches.png',
+            internalComment: 'Photo of the DIP block behind the front cover'
+        }),
+        definePublicFile({name: 'wiring', path: './assets/onboarding/wiring.jpg'})
+    ]
+});
+
+// then, in a guide:
+onboardingV2Block.imageFile('show-dips', 'dip-switches');
+```
+
+| Field | Meaning |
+|---|---|
+| `name` | Kebab-case slug, unique in the package. The handle everything else refers to — treat it as an API; renaming it breaks every reference. |
+| `path` | Path relative to the package root. Must stay inside the package: absolute paths, `..` and URLs are rejected. |
+| `mimeType` | Optional; inferred from the extension when omitted. |
+| `internalComment` | Optional note, never shown to users. |
+
+**Every entry is public.** The upload is readable by anyone with (or guessing) its URL,
+with no authentication in front of it — that is the point: an installer app has to show
+the image before the energy app runs anywhere. Declare vendor material only —
+installation diagrams, wiring photos, product shots — never customer data, credentials
+or licensed content.
+
+This is unrelated to `useFiles()`, the runtime API for offering a user a file to save:
+those bytes are produced on demand by the running app and never become a URL.
+
+Validate the declarations before releasing:
+
+```typescript
+const {ok, errors, warnings} = validatePackageFiles(packageDef.files);
+// or: assertValidPackageFiles(packageDef.files) — throws PackageFilesValidationError
+```
+
+It checks that names are unique slugs, that paths stay inside the package and carry an
+extension, and that any declared MIME type is well formed; two names pointing at one
+path is a warning.
+
 ## Firmware Update Registry
 
 Ship firmware images with your package and hand them to devices at runtime. You declare the files by local path in the package definition, the enyo CLI uploads them during `enyo release`, and the app reaches them through `energyApp.useFirmwareRegistry()`. The release tarball never carries the bytes.

package/dist/cjs/energy-app-package-definition.d.cts

@@ -261,6 +261,63 @@ export interface EnergyAppPackageCompatibilityVendor {
     /** Models from this vendor that the package supports */
     models: EnergyAppPackageCompatibilityModel[];
 }
+/**
+ * A file published together with an Energy App package and served publicly
+ * after upload.
+ *
+ * The file is declared here by its local {@link path}; the enyo CLI uploads it
+ * during `enyo release` and the published definition carries the resulting
+ * public URL, so the released package tarball never has to carry the bytes.
+ * Other parts of the definition refer to the upload by its {@link name} rather
+ * than by URL — an onboarding v2 image block
+ * ({@link EnyoOnboardingV2ImageBlock.file}) is the first consumer — which keeps
+ * the URL an implementation detail that enyo resolves at render time.
+ *
+ * **Everything declared here is public.** The upload is readable by anyone who
+ * has (or guesses) its URL, with no authentication in front of it: it exists so
+ * that an installer app can show an image before the energy app runs anywhere.
+ * Declare only vendor material safe to publish — installation diagrams, wiring
+ * photos, product shots. Never customer data, credentials or licensed content.
+ *
+ * Not to be confused with {@link EnergyAppFile}, the *runtime* API for offering
+ * a user a file to save: those bytes are produced on demand by the running app,
+ * are scoped to a device, and never become a URL.
+ *
+ * @example
+ * ```typescript
+ * files: [
+ *     definePublicFile({
+ *         name: 'dip-switches',
+ *         path: './assets/onboarding/dip-switches.png',
+ *         internalComment: 'Photo of the DIP block behind the front cover'
+ *     })
+ * ]
+ * ```
+ */
+export interface EnergyAppPackagePublicFile {
+    /**
+     * Stable, app-chosen name for this file: a kebab-case slug, unique within
+     * the package. This is the handle the rest of the definition refers to, so
+     * treat it as an API — renaming it breaks every reference to the file.
+     */
+    name: string;
+    /**
+     * Path to the file relative to the package root, e.g.
+     * `'./assets/onboarding/dip-switches.png'`. Must stay inside the package:
+     * absolute paths, `../` segments and URLs are rejected. Resolved and
+     * uploaded by the enyo CLI on release; the published definition carries a
+     * public URL instead.
+     */
+    path: string;
+    /**
+     * Optional IANA MIME type served with the file, e.g. `image/png`. Inferred
+     * from the extension when omitted; set it explicitly only when the
+     * extension is missing or misleading.
+     */
+    mimeType?: string;
+    /** Optional internal note explaining this file; never shown to users. */
+    internalComment?: string;
+}
 /**
  * How the firmware registry decides which image a device should install next.
  *
@@ -423,6 +480,21 @@ export interface EnergyAppPackageDefinition {
      * single vendor implicitly or has no fixed compatibility surface.
      */
     compatibility: EnergyAppPackageCompatibilityVendor[];
+    /**
+     * Files shipped with this package, declared as local paths, uploaded by the
+     * enyo CLI on release and served publicly from then on.
+     *
+     * Each entry is referenced elsewhere in the package by its `name` — today
+     * from an onboarding v2 image block
+     * ({@link EnyoOnboardingV2ImageBlock.file}) — so a guide never has to
+     * hard-code a URL. Validate the declarations with `validatePackageFiles()`
+     * before publishing.
+     *
+     * Every entry is publicly readable by anyone with its URL; see
+     * {@link EnergyAppPackagePublicFile} for what that rules out. Omit for
+     * packages that ship no assets.
+     */
+    files?: EnergyAppPackagePublicFile[];
     /**
      * Firmware images shipped with this package, declared as local file paths
      * and uploaded by the enyo CLI on release.

package/dist/cjs/energy-app.cjs

@@ -117,6 +117,20 @@ class EnergyApp {
     useOnboarding() {
         return this.energyAppSdk.useOnboarding();
     }
+    /**
+     * Gets the Onboarding v2 API for serving this app's onboarding guides.
+     *
+     * Guides are pulled rather than published: the app registers one handler and
+     * the host calls it with "give me your v2 onboarding guides", receiving the
+     * complete current set or nothing. There is no save, update or delete —
+     * every answer replaces the host's picture of what this app offers.
+     *
+     * Available to every app — this API is not permission-gated.
+     * @returns The Onboarding v2 API instance
+     */
+    useOnboardingV2() {
+        return this.energyAppSdk.useOnboardingV2();
+    }
     /**
      * Gets the Secret Manager API for retrieving secrets from the developer organization.
      * Provides methods to fetch secrets that have been configured in the developer org's secret store.

package/dist/cjs/energy-app.d.cts

@@ -16,6 +16,7 @@ import { EnergyAppNotification } from "./packages/energy-app-notification.cjs";
 import { EnergyAppSecretManager } from "./packages/energy-app-secret-manager.cjs";
 import { EnergyAppLocation } from "./packages/energy-app-location.cjs";
 import { EnergyAppOnboarding } from "./packages/energy-app-onboarding.cjs";
+import { EnergyAppOnboardingV2 } from "./packages/energy-app-onboarding-v2.cjs";
 import { EnergyAppTimeseries } from "./packages/energy-app-timeseries.cjs";
 import { EnyoPackageChannel } from "./enyo-package-channel.cjs";
 import { EnergyAppEnergyManager } from "./packages/energy-app-energy-manager.cjs";
@@ -99,6 +100,18 @@ export declare class EnergyApp implements EnyoEnergyAppSdk {
     useElectricityPrices(): EnergyAppEnergyPrices;
     useNotification(): EnergyAppNotification;
     useOnboarding(): EnergyAppOnboarding;
+    /**
+     * Gets the Onboarding v2 API for serving this app's onboarding guides.
+     *
+     * Guides are pulled rather than published: the app registers one handler and
+     * the host calls it with "give me your v2 onboarding guides", receiving the
+     * complete current set or nothing. There is no save, update or delete —
+     * every answer replaces the host's picture of what this app offers.
+     *
+     * Available to every app — this API is not permission-gated.
+     * @returns The Onboarding v2 API instance
+     */
+    useOnboardingV2(): EnergyAppOnboardingV2;
     /**
      * Gets the Secret Manager API for retrieving secrets from the developer organization.
      * Provides methods to fetch secrets that have been configured in the developer org's secret store.

package/dist/cjs/enyo-energy-app-sdk.d.cts

@@ -15,6 +15,7 @@ import { EnergyAppNotification } from "./packages/energy-app-notification.cjs";
 import { EnergyAppSecretManager } from "./packages/energy-app-secret-manager.cjs";
 import { EnergyAppLocation } from "./packages/energy-app-location.cjs";
 import { EnergyAppOnboarding } from "./packages/energy-app-onboarding.cjs";
+import { EnergyAppOnboardingV2 } from "./packages/energy-app-onboarding-v2.cjs";
 import { EnergyAppTimeseries } from "./packages/energy-app-timeseries.cjs";
 import { EnyoPackageChannel } from "./enyo-package-channel.cjs";
 import { EnergyAppEnergyManager } from "./packages/energy-app-energy-manager.cjs";
@@ -106,6 +107,8 @@ export interface EnyoEnergyAppSdk {
     useLocation: () => EnergyAppLocation;
     /** Get the Onboarding API */
     useOnboarding: () => EnergyAppOnboarding;
+    /** Get the Onboarding v2 API for registering the handler the host calls to collect this app's onboarding guides */
+    useOnboardingV2: () => EnergyAppOnboardingV2;
     /** Get the Timeseries API for querying historical energy data */
     useTimeseries: () => EnergyAppTimeseries;
     /** Get the Energy Manager API for retrieving energy manager info and capabilities */

package/dist/cjs/implementations/files/define-public-file.cjs

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * Ergonomic authoring helpers for a package's public files
+ * ({@link EnergyAppPackageDefinition.files}).
+ *
+ * `definePublicFile()` is an identity helper that type-checks a file entry
+ * where it is written — mirroring the SDK's `defineEnergyAppPackage()` and
+ * `defineFirmwareFile()` pattern. `resolvePublicFile()` performs the same
+ * name lookup enyo does when it renders a reference, so an app can unit-test
+ * that every name it uses actually resolves.
+ *
+ * Pair with `validatePackageFiles()` (`./public-file-validators.ts`) to fail
+ * fast before publishing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.definePublicFile = definePublicFile;
+exports.resolvePublicFile = resolvePublicFile;
+/**
+ * Identity helper that type-checks a public file entry at definition time
+ * (mirrors `defineEnergyAppPackage`). Prefer this over a bare object literal so
+ * mistakes surface where the entry is written.
+ *
+ * @param file - The public file entry to declare.
+ * @returns The same entry, typed as {@link EnergyAppPackagePublicFile}.
+ *
+ * @example
+ * ```typescript
+ * definePublicFile({
+ *     name: 'dip-switches',
+ *     path: './assets/onboarding/dip-switches.png'
+ * })
+ * ```
+ */
+function definePublicFile(file) {
+    return file;
+}
+/**
+ * Looks up a declared public file by its name.
+ *
+ * This is the resolution step enyo performs for a reference such as an
+ * onboarding v2 image block's `file`. Exposed so an app can assert in its own
+ * tests that the names its guides use are declared, rather than discovering a
+ * typo as a missing image on an installer's screen.
+ *
+ * @param files - The package's declared public files, or `undefined` when the
+ *   package declares none.
+ * @param name - The file name to resolve.
+ * @returns The matching entry, or `undefined` when no entry carries that name.
+ *
+ * @example
+ * ```typescript
+ * const file = resolvePublicFile(packageDef.files, 'dip-switches');
+ * if (!file) throw new Error('image reference does not resolve');
+ * ```
+ */
+function resolvePublicFile(files, name) {
+    return files?.find(file => file.name === name);
+}

package/dist/cjs/implementations/files/define-public-file.d.cts

@@ -0,0 +1,51 @@
+/**
+ * Ergonomic authoring helpers for a package's public files
+ * ({@link EnergyAppPackageDefinition.files}).
+ *
+ * `definePublicFile()` is an identity helper that type-checks a file entry
+ * where it is written — mirroring the SDK's `defineEnergyAppPackage()` and
+ * `defineFirmwareFile()` pattern. `resolvePublicFile()` performs the same
+ * name lookup enyo does when it renders a reference, so an app can unit-test
+ * that every name it uses actually resolves.
+ *
+ * Pair with `validatePackageFiles()` (`./public-file-validators.ts`) to fail
+ * fast before publishing.
+ */
+import type { EnergyAppPackagePublicFile } from '../../energy-app-package-definition.cjs';
+/**
+ * Identity helper that type-checks a public file entry at definition time
+ * (mirrors `defineEnergyAppPackage`). Prefer this over a bare object literal so
+ * mistakes surface where the entry is written.
+ *
+ * @param file - The public file entry to declare.
+ * @returns The same entry, typed as {@link EnergyAppPackagePublicFile}.
+ *
+ * @example
+ * ```typescript
+ * definePublicFile({
+ *     name: 'dip-switches',
+ *     path: './assets/onboarding/dip-switches.png'
+ * })
+ * ```
+ */
+export declare function definePublicFile(file: EnergyAppPackagePublicFile): EnergyAppPackagePublicFile;
+/**
+ * Looks up a declared public file by its name.
+ *
+ * This is the resolution step enyo performs for a reference such as an
+ * onboarding v2 image block's `file`. Exposed so an app can assert in its own
+ * tests that the names its guides use are declared, rather than discovering a
+ * typo as a missing image on an installer's screen.
+ *
+ * @param files - The package's declared public files, or `undefined` when the
+ *   package declares none.
+ * @param name - The file name to resolve.
+ * @returns The matching entry, or `undefined` when no entry carries that name.
+ *
+ * @example
+ * ```typescript
+ * const file = resolvePublicFile(packageDef.files, 'dip-switches');
+ * if (!file) throw new Error('image reference does not resolve');
+ * ```
+ */
+export declare function resolvePublicFile(files: EnergyAppPackagePublicFile[] | undefined, name: string): EnergyAppPackagePublicFile | undefined;

package/dist/cjs/implementations/files/public-file-validators.cjs

@@ -0,0 +1,161 @@
+"use strict";
+/**
+ * Client-side validator for the public files declared in a package definition
+ * ({@link EnergyAppPackageDefinition.files}).
+ *
+ * The declarations are resolved twice after they leave the app repository: the
+ * enyo CLI reads each `path` from the package at release time, and enyo resolves
+ * each `name` when something references the upload. Both steps happen far from
+ * the author, so anything that makes them fail — a duplicate name, a path
+ * pointing outside the package — is a blocking `error` caught here instead.
+ *
+ * `warnings` are advisory: a file nothing references still uploads fine, it is
+ * just dead weight in the release.
+ *
+ * Use {@link validatePackageFiles} for the non-throwing result, or
+ * {@link assertValidPackageFiles} to throw on failure.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PackageFilesValidationError = void 0;
+exports.isImagePublicFile = isImagePublicFile;
+exports.validatePackageFiles = validatePackageFiles;
+exports.assertValidPackageFiles = assertValidPackageFiles;
+/**
+ * Thrown by {@link assertValidPackageFiles} when a package's public file
+ * declarations fail validation. The message lists every blocking error so
+ * callers can surface them directly.
+ */
+class PackageFilesValidationError extends Error {
+    /** The individual blocking errors that caused the failure. */
+    errors;
+    /**
+     * @param errors - The blocking validation errors.
+     */
+    constructor(errors) {
+        super(`Invalid package files:\n- ${errors.join('\n- ')}`);
+        this.name = 'PackageFilesValidationError';
+        this.errors = errors;
+    }
+}
+exports.PackageFilesValidationError = PackageFilesValidationError;
+/** A public file `name` — the same kebab-case slug shape used for step names. */
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/**
+ * A path escaping the package: absolute (`/x`, `C:\x`), URL-like (`https://x`,
+ * `data:...`), or climbing out via `..`. The CLI resolves `path` against the
+ * package root, so any of these either breaks the release or pulls in a file
+ * that was never reviewed with the package.
+ */
+const ESCAPING_PATH_RE = /^(?:[/\\]|[a-zA-Z][a-zA-Z\d+.-]*:)|(?:^|[/\\])\.\.(?:[/\\]|$)/;
+/**
+ * File extensions enyo serves as images. A reference from an image block must
+ * name one of these; other extensions upload fine and are simply never usable
+ * as an image.
+ */
+const IMAGE_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.webp', '.gif', '.svg'];
+/**
+ * Extracts the lower-cased extension of a path, including the leading dot.
+ *
+ * @param path - The declared file path.
+ * @returns The extension (e.g. `'.png'`), or an empty string when the last
+ *   segment carries none.
+ */
+function extensionOf(path) {
+    const segment = path.split(/[/\\]/).pop() ?? '';
+    const dot = segment.lastIndexOf('.');
+    return dot > 0 ? segment.slice(dot).toLowerCase() : '';
+}
+/**
+ * Tests whether a declared file can be served as an image, i.e. whether an
+ * onboarding image block may reference it.
+ *
+ * Judged by the declared {@link EnergyAppPackagePublicFile.mimeType} when one is
+ * set, and by the path's extension otherwise — the same order the CLI uses when
+ * it picks the upload's content type.
+ *
+ * @param file - The declared public file.
+ * @returns True when the file is an image.
+ */
+function isImagePublicFile(file) {
+    if (file.mimeType)
+        return file.mimeType.toLowerCase().startsWith('image/');
+    return IMAGE_EXTENSIONS.includes(extensionOf(file.path));
+}
+/**
+ * Structural validation of a package's public file declarations: names are
+ * unique kebab-case slugs, paths stay inside the package and look like files,
+ * and any declared MIME type is well formed.
+ *
+ * @param files - The declared public files, or `undefined` when the package
+ *   declares none (trivially valid).
+ * @returns The {@link PackageFilesValidationResult}.
+ *
+ * @example
+ * ```typescript
+ * const {ok, errors} = validatePackageFiles(packageDef.files);
+ * if (!ok) throw new Error(errors.join('\n'));
+ * ```
+ */
+function validatePackageFiles(files) {
+    const errors = [];
+    const warnings = [];
+    if (!files?.length)
+        return { ok: true, errors, warnings };
+    const names = new Set();
+    const paths = new Map();
+    for (const [index, file] of files.entries()) {
+        const at = `files[${index}] (${file.name || '?'})`;
+        if (!file.name?.trim()) {
+            errors.push(`${at}: name is required.`);
+        }
+        else if (!SLUG_RE.test(file.name)) {
+            errors.push(`${at}: name must be a kebab-case slug, e.g. "dip-switches".`);
+        }
+        else if (names.has(file.name)) {
+            errors.push(`${at}: duplicate name "${file.name}" — names must be unique within the package.`);
+        }
+        else {
+            names.add(file.name);
+        }
+        const path = file.path?.trim();
+        if (!path) {
+            errors.push(`${at}: path is required.`);
+        }
+        else if (ESCAPING_PATH_RE.test(path)) {
+            errors.push(`${at}: path "${path}" must be relative to the package root — no absolute paths, "..", or URLs.`);
+        }
+        else if (!extensionOf(path)) {
+            errors.push(`${at}: path "${path}" has no file extension.`);
+        }
+        else {
+            // The same bytes under two names upload twice and drift apart when
+            // only one reference is updated later.
+            const previous = paths.get(path);
+            if (previous) {
+                warnings.push(`${at}: path "${path}" is already declared as "${previous}".`);
+            }
+            else if (file.name) {
+                paths.set(path, file.name);
+            }
+        }
+        if (file.mimeType !== undefined && !/^[\w.+-]+\/[\w.+-]+$/.test(file.mimeType)) {
+            errors.push(`${at}: mimeType "${file.mimeType}" is not a valid MIME type.`);
+        }
+    }
+    return { ok: errors.length === 0, errors, warnings };
+}
+/**
+ * Like {@link validatePackageFiles}, but throws
+ * {@link PackageFilesValidationError} when there are blocking errors. Warnings
+ * never throw; the validated declarations are returned on success for chaining.
+ *
+ * @param files - The declared public files.
+ * @returns The same declarations when they have no blocking errors.
+ * @throws {PackageFilesValidationError} When validation produces any error.
+ */
+function assertValidPackageFiles(files) {
+    const { ok, errors } = validatePackageFiles(files);
+    if (!ok)
+        throw new PackageFilesValidationError(errors);
+    return files;
+}

package/dist/cjs/implementations/files/public-file-validators.d.cts

@@ -0,0 +1,77 @@
+/**
+ * Client-side validator for the public files declared in a package definition
+ * ({@link EnergyAppPackageDefinition.files}).
+ *
+ * The declarations are resolved twice after they leave the app repository: the
+ * enyo CLI reads each `path` from the package at release time, and enyo resolves
+ * each `name` when something references the upload. Both steps happen far from
+ * the author, so anything that makes them fail — a duplicate name, a path
+ * pointing outside the package — is a blocking `error` caught here instead.
+ *
+ * `warnings` are advisory: a file nothing references still uploads fine, it is
+ * just dead weight in the release.
+ *
+ * Use {@link validatePackageFiles} for the non-throwing result, or
+ * {@link assertValidPackageFiles} to throw on failure.
+ */
+import type { EnergyAppPackagePublicFile } from '../../energy-app-package-definition.cjs';
+/**
+ * Thrown by {@link assertValidPackageFiles} when a package's public file
+ * declarations fail validation. The message lists every blocking error so
+ * callers can surface them directly.
+ */
+export declare class PackageFilesValidationError extends Error {
+    /** The individual blocking errors that caused the failure. */
+    readonly errors: string[];
+    /**
+     * @param errors - The blocking validation errors.
+     */
+    constructor(errors: string[]);
+}
+/** The outcome of validating a package's public file declarations. */
+export interface PackageFilesValidationResult {
+    /** True when there are no blocking `errors` (warnings are still allowed). */
+    ok: boolean;
+    /** Blocking problems — these must be fixed before releasing. */
+    errors: string[];
+    /** Advisory problems — allowed, but usually worth reviewing. */
+    warnings: string[];
+}
+/**
+ * Tests whether a declared file can be served as an image, i.e. whether an
+ * onboarding image block may reference it.
+ *
+ * Judged by the declared {@link EnergyAppPackagePublicFile.mimeType} when one is
+ * set, and by the path's extension otherwise — the same order the CLI uses when
+ * it picks the upload's content type.
+ *
+ * @param file - The declared public file.
+ * @returns True when the file is an image.
+ */
+export declare function isImagePublicFile(file: EnergyAppPackagePublicFile): boolean;
+/**
+ * Structural validation of a package's public file declarations: names are
+ * unique kebab-case slugs, paths stay inside the package and look like files,
+ * and any declared MIME type is well formed.
+ *
+ * @param files - The declared public files, or `undefined` when the package
+ *   declares none (trivially valid).
+ * @returns The {@link PackageFilesValidationResult}.
+ *
+ * @example
+ * ```typescript
+ * const {ok, errors} = validatePackageFiles(packageDef.files);
+ * if (!ok) throw new Error(errors.join('\n'));
+ * ```
+ */
+export declare function validatePackageFiles(files: EnergyAppPackagePublicFile[] | undefined): PackageFilesValidationResult;
+/**
+ * Like {@link validatePackageFiles}, but throws
+ * {@link PackageFilesValidationError} when there are blocking errors. Warnings
+ * never throw; the validated declarations are returned on success for chaining.
+ *
+ * @param files - The declared public files.
+ * @returns The same declarations when they have no blocking errors.
+ * @throws {PackageFilesValidationError} When validation produces any error.
+ */
+export declare function assertValidPackageFiles(files: EnergyAppPackagePublicFile[] | undefined): EnergyAppPackagePublicFile[] | undefined;

package/dist/cjs/implementations/onboarding-v2/define-onboarding-guide-v2.cjs

@@ -67,12 +67,39 @@ exports.onboardingV2Block = {
      */
     bullets: (id, items) => ({ id, type: enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Bullets, items }),
     /**
-     * An image block.
+     * An image block addressing an externally hosted image by URL.
+     *
+     * Prefer {@link block.imageFile} for an image that lives in the app
+     * repository: nothing mirrors the URL passed here, so the guide is only as
+     * available as the host serving it.
+     *
      * @param id - Stable block id, unique within the guide.
      * @param url - Public asset URL.
      * @param caption - Optional translated caption (de/en).
      */
     image: (id, url, caption) => ({ id, type: enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Image, url, caption }),
+    /**
+     * An image block addressing a file shipped with the package.
+     *
+     * The file must be declared in the package definition's `files`
+     * ({@link EnergyAppPackagePublicFile}); the enyo CLI uploads it on release
+     * and enyo resolves the name to a public URL when the guide is rendered.
+     * Pass the package's declarations to `validateOnboardingGuideV2()` to have
+     * a mistyped name rejected before publishing.
+     *
+     * @param id - Stable block id, unique within the guide.
+     * @param file - Name of the declared package file, e.g. `'dip-switches'`.
+     * @param caption - Optional translated caption (de/en).
+     *
+     * @example
+     * ```typescript
+     * block.imageFile('dip', 'dip-switches', [
+     *     {language: 'de', value: 'DIP-Schalter hinter der Frontblende'},
+     *     {language: 'en', value: 'DIP switches behind the front cover'}
+     * ])
+     * ```
+     */
+    imageFile: (id, file, caption) => ({ id, type: enyo_onboarding_v2_js_1.EnyoOnboardingV2BlockType.Image, file, caption }),
     /**
      * A hint/callout block.
      * @param id - Stable block id, unique within the guide.