@nebulahome/package-sdk 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -3,6 +3,12 @@
 The SDK's version is the version of the package API the platform implements: a minor version adds
 to it, a major one breaks it, and a patch leaves it as it is.
 
+## 1.4.0
+
+- **Toasts.** `useToast()` from `@nebulahome/package-sdk/ui` shows the interface's own toasts -
+  `success`, `warning`, `error`, `info`, each with a title, a line or two and at most one action -
+  for the outcome of something the viewer just did.
+
 ## 1.3.0
 
 - **The page's actions in its header.** `<PageActions>` from `@nebulahome/package-sdk/ui` draws

package/README.md

@@ -140,6 +140,22 @@ import { sunPosition } from '@nebulahome/package-sdk/sun';
 const { elevation, azimuth } = sunPosition(at, { latitude, longitude });
 ```
 
+## Toasts
+
+The interface's own toasts, for the outcome of something the viewer just did (since 1.4):
+
+```tsx
+const toast = useToast();
+const save = usePackageMutation('rules.save');
+
+try {
+  await save.mutate(rules);
+  toast.success({ title: t('save.done', 'Saved') });
+} catch (error) {
+  toast.error({ title: t('save.failed', "Couldn't save"), message: String(error) });
+}
+```
+
 ## Entry points
 
 | Import                    | What                                                                                                                                                                                                                                            |
@@ -189,8 +205,9 @@ git tag package-sdk@<version> && git push origin package-sdk@<version>
 ```
 
 `.github/workflows/release-package-sdk.yml` checks the tag says the package's version, runs the
-SDK's gates and publishes a GitHub release with the archive npm will receive. The maintainer
-publishes that archive, signed in to npm:
+SDK's gates and keeps the archive npm will receive as the run's artifact; it makes no GitHub
+release, npm is where the SDK is published. The maintainer downloads that artifact from the run
+and publishes it, signed in to npm:
 
 ```sh
 npm publish nebulahome-package-sdk-<version>.tgz

package/dist/chunks/node-build.js

@@ -6850,7 +6850,7 @@ function composeFileProblems(text, settingKeys) {
 * the two are compared before a package is installed or started (PACKAGES_DOCS.md 11).
 */
 /** The SDK's own version, `1.0.0`. */
-const SDK_VERSION = "1.3.0";
+const SDK_VERSION = "1.4.0";
 //#endregion
 //#region src/vite/catalogues.ts
 /**

package/dist/chunks/version.js

@@ -7,6 +7,6 @@
 * the two are compared before a package is installed or started (PACKAGES_DOCS.md 11).
 */
 /** The SDK's own version, `1.0.0`. */
-const SDK_VERSION = "1.3.0";
+const SDK_VERSION = "1.4.0";
 //#endregion
 export { SDK_VERSION as t };

package/dist/styles.css

@@ -276,6 +276,11 @@
   --text-display--line-height: 1.15;
   --text-display--letter-spacing: -0.03em;
 
+  /** The title of the screen every page shows while Nebula Home restarts or updates. */
+  --text-display-lg: 40px;
+  --text-display-lg--line-height: 1.1;
+  --text-display-lg--letter-spacing: -0.035em;
+
   /** The number an entity card is about; its unit follows at half size in `foreground-subtle`. */
   --text-reading: 32px;
   --text-reading--line-height: 1;
@@ -384,6 +389,92 @@
    * the dashes go by `animation-direction`.
    */
   --animate-energy-flow: energy-flow 1.6s linear infinite;
+
+  /*
+   * Nebula Home restarting or updating itself (boards N-Restart, N-Update, N-Transition-Flow): the
+   * ring turns slowly and unevenly while the core breathes out of phase, rings ripple out from the
+   * mark, its glow swells, a bar sweeps or shimmers, and the screen arrives out of a blur.
+   */
+  --animate-orbit-work: orbit 2.4s cubic-bezier(0.55, 0.1, 0.35, 0.9) infinite;
+  --animate-breathe: breathe 2.4s ease-in-out infinite;
+  --animate-ripple: ripple 2.4s cubic-bezier(0.2, 0.6, 0.3, 1) infinite;
+  --animate-glow: glow 3.6s ease-in-out infinite;
+  --animate-sweep: sweep 1.6s cubic-bezier(0.4, 0, 0.2, 1) infinite;
+  --animate-shimmer: shimmer 2s linear infinite;
+  --animate-enter: enter 0.8s cubic-bezier(0.2, 0.7, 0.2, 1) both;
+  --animate-arrive: arrive 0.6s cubic-bezier(0.2, 0.7, 0.2, 1) both;
+}
+
+/* The core of the mark breathing while Nebula Home works on itself. */
+@keyframes breathe {
+  0%,
+  100% {
+    transform: scale(1);
+    opacity: 1;
+  }
+  50% {
+    transform: scale(0.86);
+    opacity: 0.75;
+  }
+}
+
+/* A ring leaving the mark and fading as it widens. */
+@keyframes ripple {
+  from {
+    transform: scale(0.55);
+    opacity: 0.55;
+  }
+  to {
+    transform: scale(1.9);
+    opacity: 0;
+  }
+}
+
+@keyframes glow {
+  0%,
+  100% {
+    opacity: 0.45;
+  }
+  50% {
+    opacity: 0.8;
+  }
+}
+
+/* A bar that cannot say how far it is: a highlight crossing it again and again. */
+@keyframes sweep {
+  from {
+    left: -40%;
+  }
+  to {
+    left: 100%;
+  }
+}
+
+/* A light passing along a bar that is moving. */
+@keyframes shimmer {
+  from {
+    background-position: -200% 0;
+  }
+  to {
+    background-position: 200% 0;
+  }
+}
+
+/* A screen arriving out of a blur, a little small. */
+@keyframes enter {
+  from {
+    opacity: 0;
+    transform: scale(0.96);
+    filter: blur(10px);
+  }
+}
+
+/* A note rising into place. */
+@keyframes arrive {
+  from {
+    opacity: 0;
+    transform: translateY(10px);
+  }
 }
 
 /* One period of a wire's dash pattern, which is 12 units long: 2 drawn, 10 gap. */
@@ -566,6 +657,47 @@
  * The Matter mark's square, lit violet from its top-left corner: the broker's hero and its
  * dialogs' lead. Over the square's own ground, so it sits on `bg-surface-raised`.
  */
+@utility modbus-glow {
+  background-image: radial-gradient(
+    120% 120% at 0% 0%,
+    color-mix(in srgb, var(--color-cyan) 18%, transparent),
+    transparent 60%
+  );
+}
+
+/* The newer brokers' squares, each lit in its own mark's colour the same way. */
+@utility thread-glow {
+  background-image: radial-gradient(
+    120% 120% at 0% 0%,
+    color-mix(in srgb, var(--color-thread) 20%, transparent),
+    transparent 60%
+  );
+}
+
+@utility bluetooth-glow {
+  background-image: radial-gradient(
+    120% 120% at 0% 0%,
+    color-mix(in srgb, #5b9dff 20%, transparent),
+    transparent 60%
+  );
+}
+
+@utility serial-glow {
+  background-image: radial-gradient(
+    120% 120% at 0% 0%,
+    color-mix(in srgb, #f0c27b 18%, transparent),
+    transparent 60%
+  );
+}
+
+@utility infrared-glow {
+  background-image: radial-gradient(
+    120% 120% at 0% 0%,
+    color-mix(in srgb, #f7895c 18%, transparent),
+    transparent 60%
+  );
+}
+
 @utility matter-glow {
   background-image: radial-gradient(
     120% 120% at 0% 0%,

package/dist/ui.d.ts

@@ -298,6 +298,32 @@ type PlatformLinkProps = LinkAttributes & {
 type PageActionsProps = {
   readonly children?: ReactNode;
 };
+/** What a toast says. Since 1.4. */
+type ToastMessage = {
+  /** A few words, no full stop. */
+  readonly title: string;
+  /** One or two lines. */
+  readonly message?: string;
+  /** The one thing to do about it; doing it closes the toast. */
+  readonly action?: {
+    readonly label: string;
+    readonly onSelect: () => void;
+  };
+};
+/**
+ * Shows one of the interface's toasts, one function per kind: bottom right, three at a time, the
+ * rest waiting their turn; the same toast twice is shown once. Since 1.4.
+ */
+type Toasts = {
+  /** Confirms what was just done; stays 4 s. */
+  readonly success: (message: ToastMessage) => void;
+  /** Something that needs a look, not right now; stays 8 s. */
+  readonly warning: (message: ToastMessage) => void;
+  /** Something that failed; stays 10 s. */
+  readonly error: (message: ToastMessage) => void;
+  /** Something that started or changed; stays 6 s. */
+  readonly info: (message: ToastMessage) => void;
+};
 /** What the interface lends to implement `/ui`. */
 type UiHost = {
   readonly usePackage: () => PackageInfo;
@@ -332,6 +358,8 @@ type UiHost = {
   readonly PageActions: ComponentType<PageActionsProps>;
   /** Since 1.3. */
   readonly useAreaActions: () => AreaActions;
+  /** Since 1.4. */
+  readonly useToast: () => Toasts;
 };
 //#endregion
 //#region src/ui/index.d.ts
@@ -454,6 +482,13 @@ export declare function useAreas(): readonly AreaView[];
  * @returns What changes the areas.
  */
 export declare function useAreaActions(): AreaActions;
+/**
+ * Shows the interface's toasts: the outcome of something the viewer just did - "Saved", "Couldn't
+ * reach the printer" - from a handler, a mutation's `onError`, wherever. Since 1.4.
+ *
+ * @returns One function per kind: `success`, `warning`, `error`, `info`.
+ */
+export declare function useToast(): Toasts;
 /**
  * A camera's latest still, fetched again every so often, or an image entity's picture, fetched
  * again when it changes: an address an `<img>` shows, let go of when a newer one replaces it.
@@ -516,4 +551,4 @@ export declare function PlatformLink(props: PlatformLinkProps): ReactElement;
  */
 export declare function PageActions(props: PageActionsProps): ReactElement;
 //#endregion
-export type { AreaActions, AreaDraft, AreaKind, AreaView, CardProps, ChangeCause, CustomEntityState, EntitiesFilter, EntityPicture, EntityView, EntityViewProps, History, HistoryQuery, HistorySeries, HistoryWindow, Locale, Mutation, MutationOptions, PackageCall, PackageInfo, PackageLinkProps, PackageNavigate, PackageRoute, PackageSettings, PageActionsProps, PageProps, PictureOptions, PlatformLinkProps, PlatformNavigate, PlatformTarget, PluralEnglish, RpcOptions, RpcState, SendCommand, SettingsPatch, StateHistoryPoint, Telemetry, TelemetryPoint, TelemetryQuery, TelemetryResolution, Theme, Translate, Translation, TranslationValues, UiHost, Viewer, VisibleSettings };
+export type { AreaActions, AreaDraft, AreaKind, AreaView, CardProps, ChangeCause, CustomEntityState, EntitiesFilter, EntityPicture, EntityView, EntityViewProps, History, HistoryQuery, HistorySeries, HistoryWindow, Locale, Mutation, MutationOptions, PackageCall, PackageInfo, PackageLinkProps, PackageNavigate, PackageRoute, PackageSettings, PageActionsProps, PageProps, PictureOptions, PlatformLinkProps, PlatformNavigate, PlatformTarget, PluralEnglish, RpcOptions, RpcState, SendCommand, SettingsPatch, StateHistoryPoint, Telemetry, TelemetryPoint, TelemetryQuery, TelemetryResolution, Theme, ToastMessage, Toasts, Translate, Translation, TranslationValues, UiHost, Viewer, VisibleSettings };

package/dist/ui.js

@@ -212,6 +212,15 @@ function useAreaActions() {
 	return ui("useAreaActions", "1.3")();
 }
 /**
+* Shows the interface's toasts: the outcome of something the viewer just did - "Saved", "Couldn't
+* reach the printer" - from a handler, a mutation's `onError`, wherever. Since 1.4.
+*
+* @returns One function per kind: `success`, `warning`, `error`, `info`.
+*/
+function useToast() {
+	return ui("useToast", "1.4")();
+}
+/**
 * A camera's latest still, fetched again every so often, or an image entity's picture, fetched
 * again when it changes: an address an `<img>` shows, let go of when a newer one replaces it.
 *
@@ -291,4 +300,4 @@ function PageActions(props) {
 	return createElement(ui("PageActions", "1.3"), props);
 }
 //#endregion
-export { PackageLink, PageActions, PlatformLink, useAreaActions, useAreas, useCommand, useCustomEntity, useEntities, useEntity, useEntityPicture, useLocale, usePackage, usePackageCall, usePackageMutation, usePackageNavigate, usePackageRoute, usePackageRpc, usePackageSettings, usePlatformNavigate, usePortalContainer, useStateHistory, useTelemetry, useTheme, useTranslation, useViewer };
+export { PackageLink, PageActions, PlatformLink, useAreaActions, useAreas, useCommand, useCustomEntity, useEntities, useEntity, useEntityPicture, useLocale, usePackage, usePackageCall, usePackageMutation, usePackageNavigate, usePackageRoute, usePackageRpc, usePackageSettings, usePlatformNavigate, usePortalContainer, useStateHistory, useTelemetry, useTheme, useToast, useTranslation, useViewer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulahome/package-sdk",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Write a NebulaHome package: declare it, build it, and run it on the platform.",
   "license": "MIT",
   "type": "module",
@@ -100,10 +100,10 @@
     "vitest": "^4.1.11",
     "yaml": "^2.9.0",
     "zod": "^4.5.4",
-    "@nebulahome/contracts": "0.0.0",
-    "@nebulahome/eslint-config": "0.0.0",
-    "@nebulahome/tsconfig": "0.0.0",
-    "@nebulahome/ui": "0.0.0"
+    "@nebulahome/contracts": "2026.10.0-alpha.23",
+    "@nebulahome/tsconfig": "2026.10.0-alpha.23",
+    "@nebulahome/eslint-config": "2026.10.0-alpha.23",
+    "@nebulahome/ui": "2026.10.0-alpha.23"
   },
   "scripts": {
     "build": "tsdown && node scripts/build-styles.js",