@camstack/types 1.2.446 → 1.2.448

package/dist/interfaces/event-bus.d.ts

@@ -641,6 +641,8 @@ export interface SystemReadyStatePayload {
     readonly ts: number;
     readonly [key: string]: unknown;
 }
+/** What a node update replaces — see {@link PendingRestartMarkerPayload.what}. */
+export type NodeUpdateTarget = 'server' | 'desktop-shell' | 'container-image';
 /**
  * Payload carried on `system.restarting` (when the restart is being
  * scheduled) and `system.restart-completed` (after the new process
@@ -659,6 +661,13 @@ export interface SystemReadyStatePayload {
  */
 export interface PendingRestartMarkerPayload {
     readonly kind: 'framework-update' | 'manual' | 'system' | 'framework-bulk-update';
+    /**
+     * WHAT is being replaced when the restart is an update. Absent means the
+     * `@camstack/server` closure (every announcement predating the field):
+     * `desktop-shell` is the Electron app's own self-update, `container-image` a
+     * container that booted on a different image than its previous boot.
+     */
+    readonly what?: NodeUpdateTarget;
     readonly packageName?: string;
     readonly fromVersion?: string;
     readonly toVersion?: string;

package/dist/remote/remote-builtin-components.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The built-in palette of remote layout components (D973): what the template
+ * editor's "Add component" offers before any addon contributes more. The
+ * core-blocks builtin serves this list through the `remote-layout-components`
+ * cap; the built-in layout presets are composed from the same entries with
+ * `insertComponent`, so a preset and a hand-built layout use one vocabulary.
+ *
+ * Roles are the existing remote roles; where the vocabulary has no word
+ * (a generic minus / plus, a colour key, an app slot) the key is `custom:<key>`.
+ * Printed legends are data, not interface strings, so they are not translated.
+ */
+import type { RemoteLayoutComponent } from './remote-components.js';
+export declare const BUILTIN_REMOTE_COMPONENTS: readonly RemoteLayoutComponent[];
+/** A built-in component by id (the presets compose from these). */
+export declare function builtinRemoteComponent(id: string): RemoteLayoutComponent;

package/dist/remote/remote-components.d.ts

@@ -0,0 +1,109 @@
+/**
+ * A remote layout COMPONENT (D973): a reusable, named chunk of a remote — a
+ * D-pad, a keypad, a section divider — offered in the template editor's
+ * "Add component" palette. Pure data: the buttons are placed RELATIVE to the
+ * component, and the frame, shape and tone are names from the closed
+ * vocabularies the UI draws. An addon contributes components through the
+ * `remote-layout-components` cap and ships no UI code.
+ */
+import { z } from 'zod';
+export declare const REMOTE_COMPONENT_CATEGORIES: readonly ['power', 'navigation', 'volume', 'numbers', 'media', 'colour', 'apps', 'layout'];
+export declare const RemoteComponentCategorySchema: z.ZodEnum<{
+    apps: "apps";
+    colour: "colour";
+    layout: "layout";
+    media: "media";
+    navigation: "navigation";
+    numbers: "numbers";
+    power: "power";
+    volume: "volume";
+}>;
+export type RemoteComponentCategory = z.infer<typeof RemoteComponentCategorySchema>;
+export declare const MAX_COMPONENT_BUTTONS = 40;
+export declare const RemoteComponentButtonSchema: z.ZodObject<{
+    idSuffix: z.ZodString;
+    row: z.ZodNumber;
+    col: z.ZodNumber;
+    rowSpan: z.ZodNumber;
+    colSpan: z.ZodNumber;
+    role: z.ZodString;
+    icon: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    shape: z.ZodOptional<z.ZodEnum<{
+        pill: "pill";
+        rect: "rect";
+        round: "round";
+        rounded: "rounded";
+    }>>;
+    tone: z.ZodOptional<z.ZodEnum<{
+        accent: "accent";
+        blue: "blue";
+        danger: "danger";
+        green: "green";
+        neutral: "neutral";
+        red: "red";
+        yellow: "yellow";
+    }>>;
+}, z.core.$strip>;
+export type RemoteComponentButton = z.infer<typeof RemoteComponentButtonSchema>;
+export declare const RemoteLayoutComponentSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    nameI18n: z.ZodOptional<z.ZodObject<{
+        en: z.ZodString;
+        it: z.ZodString;
+    }, z.core.$strip>>;
+    icon: z.ZodString;
+    category: z.ZodEnum<{
+        apps: "apps";
+        colour: "colour";
+        layout: "layout";
+        media: "media";
+        navigation: "navigation";
+        numbers: "numbers";
+        power: "power";
+        volume: "volume";
+    }>;
+    size: z.ZodObject<{
+        rows: z.ZodNumber;
+        cols: z.ZodNumber;
+    }, z.core.$strip>;
+    group: z.ZodNullable<z.ZodObject<{
+        frame: z.ZodEnum<{
+            divider: "divider";
+            dpad: "dpad";
+            keypad: "keypad";
+            none: "none";
+            panel: "panel";
+            "rocker-h": "rocker-h";
+            "rocker-v": "rocker-v";
+        }>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    buttons: z.ZodArray<z.ZodObject<{
+        idSuffix: z.ZodString;
+        row: z.ZodNumber;
+        col: z.ZodNumber;
+        rowSpan: z.ZodNumber;
+        colSpan: z.ZodNumber;
+        role: z.ZodString;
+        icon: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        shape: z.ZodOptional<z.ZodEnum<{
+            pill: "pill";
+            rect: "rect";
+            round: "round";
+            rounded: "rounded";
+        }>>;
+        tone: z.ZodOptional<z.ZodEnum<{
+            accent: "accent";
+            blue: "blue";
+            danger: "danger";
+            green: "green";
+            neutral: "neutral";
+            red: "red";
+            yellow: "yellow";
+        }>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type RemoteLayoutComponent = z.infer<typeof RemoteLayoutComponentSchema>;

package/dist/remote/remote-config.d.ts

@@ -15,6 +15,7 @@ export declare const RemoteBindingActionSchema: z.ZodObject<{
     cap: z.ZodString;
     method: z.ZodString;
     args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    argUnits: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     deviceId: z.ZodNumber;
 }, z.core.$strip>;
 export type RemoteBindingAction = z.infer<typeof RemoteBindingActionSchema>;
@@ -24,6 +25,7 @@ export declare const RemoteBindingSchema: z.ZodObject<{
         cap: z.ZodString;
         method: z.ZodString;
         args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        argUnits: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         deviceId: z.ZodNumber;
     }, z.core.$strip>;
 }, z.core.$strip>;
@@ -50,6 +52,7 @@ export declare const RemoteConfigSchema: z.ZodObject<{
             cap: z.ZodString;
             method: z.ZodString;
             args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            argUnits: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             deviceId: z.ZodNumber;
         }, z.core.$strip>;
     }, z.core.$strip>>;
@@ -88,6 +91,42 @@ export declare const RemoteAssumedStateSchema: z.ZodObject<{
 export type RemoteAssumedState = z.infer<typeof RemoteAssumedStateSchema>;
 export declare const EMPTY_REMOTE_ASSUMED_STATE: RemoteAssumedState;
 export declare const MAX_LAYOUT_SPAN = 24;
+export declare const MAX_LAYOUT_GROUPS = 50;
+/**
+ * Closed vocabularies the UI knows how to DRAW (D973). A layout names a shape,
+ * a tone or a frame; it never carries a style. An addon that contributes a
+ * component picks from these lists — it ships no UI code.
+ */
+export declare const REMOTE_BUTTON_SHAPES: readonly ['rect', 'rounded', 'round', 'pill'];
+export declare const RemoteButtonShapeSchema: z.ZodEnum<{
+    pill: "pill";
+    rect: "rect";
+    round: "round";
+    rounded: "rounded";
+}>;
+export type RemoteButtonShape = z.infer<typeof RemoteButtonShapeSchema>;
+export declare const REMOTE_BUTTON_TONES: readonly ['neutral', 'accent', 'danger', 'red', 'green', 'yellow', 'blue'];
+export declare const RemoteButtonToneSchema: z.ZodEnum<{
+    accent: "accent";
+    blue: "blue";
+    danger: "danger";
+    green: "green";
+    neutral: "neutral";
+    red: "red";
+    yellow: "yellow";
+}>;
+export type RemoteButtonTone = z.infer<typeof RemoteButtonToneSchema>;
+export declare const REMOTE_GROUP_FRAMES: readonly ['none', 'panel', 'divider', 'dpad', 'rocker-v', 'rocker-h', 'keypad'];
+export declare const RemoteGroupFrameSchema: z.ZodEnum<{
+    divider: "divider";
+    dpad: "dpad";
+    keypad: "keypad";
+    none: "none";
+    panel: "panel";
+    "rocker-h": "rocker-h";
+    "rocker-v": "rocker-v";
+}>;
+export type RemoteGroupFrame = z.infer<typeof RemoteGroupFrameSchema>;
 export declare const RemoteLayoutButtonSchema: z.ZodObject<{
     id: z.ZodString;
     row: z.ZodNumber;
@@ -97,8 +136,56 @@ export declare const RemoteLayoutButtonSchema: z.ZodObject<{
     icon: z.ZodOptional<z.ZodString>;
     label: z.ZodOptional<z.ZodString>;
     role: z.ZodString;
+    shape: z.ZodOptional<z.ZodEnum<{
+        pill: "pill";
+        rect: "rect";
+        round: "round";
+        rounded: "rounded";
+    }>>;
+    tone: z.ZodOptional<z.ZodEnum<{
+        accent: "accent";
+        blue: "blue";
+        danger: "danger";
+        green: "green";
+        neutral: "neutral";
+        red: "red";
+        yellow: "yellow";
+    }>>;
+    groupId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type RemoteLayoutButton = z.infer<typeof RemoteLayoutButtonSchema>;
+/**
+ * A rectangle of the grid that moves as ONE thing and is drawn with a frame: a
+ * titled panel, a section divider, a D-pad ring. `componentId` names the palette
+ * entry it came from (informational: the layout is self-contained).
+ */
+export declare const RemoteLayoutGroupSchema: z.ZodObject<{
+    id: z.ZodString;
+    componentId: z.ZodString;
+    frame: z.ZodEnum<{
+        divider: "divider";
+        dpad: "dpad";
+        keypad: "keypad";
+        none: "none";
+        panel: "panel";
+        "rocker-h": "rocker-h";
+        "rocker-v": "rocker-v";
+    }>;
+    row: z.ZodNumber;
+    col: z.ZodNumber;
+    rowSpan: z.ZodNumber;
+    colSpan: z.ZodNumber;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type RemoteLayoutGroup = z.infer<typeof RemoteLayoutGroupSchema>;
+export interface LayoutRect {
+    readonly row: number;
+    readonly col: number;
+    readonly rowSpan: number;
+    readonly colSpan: number;
+}
+export declare function rectsOverlap(a: LayoutRect, b: LayoutRect): boolean;
+export declare function rectContains(outer: LayoutRect, inner: LayoutRect): boolean;
 export declare const RemoteLayoutPayloadSchema: z.ZodObject<{
     columns: z.ZodNumber;
     rows: z.ZodNumber;
@@ -111,6 +198,40 @@ export declare const RemoteLayoutPayloadSchema: z.ZodObject<{
         icon: z.ZodOptional<z.ZodString>;
         label: z.ZodOptional<z.ZodString>;
         role: z.ZodString;
+        shape: z.ZodOptional<z.ZodEnum<{
+            pill: "pill";
+            rect: "rect";
+            round: "round";
+            rounded: "rounded";
+        }>>;
+        tone: z.ZodOptional<z.ZodEnum<{
+            accent: "accent";
+            blue: "blue";
+            danger: "danger";
+            green: "green";
+            neutral: "neutral";
+            red: "red";
+            yellow: "yellow";
+        }>>;
+        groupId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    groups: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        componentId: z.ZodString;
+        frame: z.ZodEnum<{
+            divider: "divider";
+            dpad: "dpad";
+            keypad: "keypad";
+            none: "none";
+            panel: "panel";
+            "rocker-h": "rocker-h";
+            "rocker-v": "rocker-v";
+        }>;
+        row: z.ZodNumber;
+        col: z.ZodNumber;
+        rowSpan: z.ZodNumber;
+        colSpan: z.ZodNumber;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type RemoteLayoutPayload = z.infer<typeof RemoteLayoutPayloadSchema>;

package/dist/remote/remote-layout-ops.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Pure edits of a remote layout that involve groups and components (D973).
+ * Shared by the template editor, the built-in presets and the server so an
+ * accepted edit is always a payload `RemoteLayoutPayloadSchema` accepts.
+ * Every function returns a NEW layout or a typed refusal; none mutates.
+ */
+import type { RemoteLayoutComponent } from './remote-components.js';
+import { type RemoteLayoutPayload } from './remote-config.js';
+export declare const LAYOUT_EDIT_REFUSALS: readonly ['outside', 'overlap', 'unknown-group', 'too-many'];
+export type LayoutEditRefusal = (typeof LAYOUT_EDIT_REFUSALS)[number];
+export type LayoutEditResult = {
+    readonly ok: true;
+    readonly layout: RemoteLayoutPayload;
+} | {
+    readonly ok: false;
+    readonly reason: LayoutEditRefusal;
+};
+export interface InsertedComponent {
+    readonly ok: true;
+    readonly layout: RemoteLayoutPayload;
+    /** The group created for the component, or null for a component of loose buttons. */
+    readonly groupId: string | null;
+    readonly buttonIds: readonly string[];
+}
+export type InsertComponentResult = InsertedComponent | {
+    readonly ok: false;
+    readonly reason: LayoutEditRefusal;
+};
+/** A button of a component, positioned relative to it. */
+export type ComponentButtonSpec = RemoteLayoutComponent['buttons'][number];
+export interface InsertOptions {
+    /** Multiply the component's rows / columns (and every button's span), e.g. a D-pad on a 12-column grid. */
+    readonly scale?: {
+        readonly rows?: number;
+        readonly cols?: number;
+    };
+    /** Extra relative buttons joined to this instance (the keypad's bottom-corner keys). */
+    readonly extras?: readonly ComponentButtonSpec[];
+    /** Replaces the component's own frame title ("Section" -> "Volume"). */
+    readonly title?: string;
+}
+/** The columns a component must be scaled by to span the whole grid width, or null when it does not divide. */
+export declare function fillWidthScale(layout: RemoteLayoutPayload, component: RemoteLayoutComponent): number | null;
+/**
+ * Put `component` on the layout with its top-left cell at `at`. A component
+ * with a group becomes one group whose rectangle is the whole component and
+ * whose members are its buttons; one without is a set of loose buttons. The
+ * grid does not grow: a component that does not fit is refused `outside`, one
+ * that would sit on an existing key or group `overlap`.
+ */
+export declare function insertComponent(layout: RemoteLayoutPayload, component: RemoteLayoutComponent, at: {
+    readonly row: number;
+    readonly col: number;
+}, options?: InsertOptions): InsertComponentResult;
+/** Move a group and every member by the same offset, atomically. */
+export declare function moveGroup(layout: RemoteLayoutPayload, groupId: string, to: {
+    readonly row: number;
+    readonly col: number;
+}): LayoutEditResult;
+/**
+ * Delete a group. With `keepButtons` its members stay where they are as loose
+ * keys; without, they go with it.
+ */
+export declare function removeGroup(layout: RemoteLayoutPayload, groupId: string, options: {
+    readonly keepButtons: boolean;
+}): LayoutEditResult;
+/** Dissolve a group, keeping its buttons in place. */
+export declare function ungroup(layout: RemoteLayoutPayload, groupId: string): LayoutEditResult;

package/dist/{sleep-6eG9C8Xl.mjs → sleep-63gM_1JR.mjs}

@@ -6877,6 +6877,7 @@ var CAP_NAMES = Object.freeze([
 	"recording-signal",
 	"records",
 	"remote",
+	"remote-layout-components",
 	"running-state",
 	"scene-monitor",
 	"script-runner",

package/dist/{sleep-UXDHn-oJ.js → sleep-BSPhInRm.js}

@@ -6877,6 +6877,7 @@ var CAP_NAMES = Object.freeze([
 	"recording-signal",
 	"records",
 	"remote",
+	"remote-layout-components",
 	"running-state",
 	"scene-monitor",
 	"script-runner",

package/dist/units/index.d.ts

@@ -8,6 +8,9 @@ export { UnitConversionError, unitDimension, convertUnit, tryConvertUnit, tryCon
 export type { UnitConversionReason } from './convert.js';
 export { DEFAULT_DISPLAY_PREFERENCE, DISPLAY_PREFERENCES, QUANTITY_BASE, ReadingQuantitySchema, baseUnitOf, displayUnitFor, historyUnitFor, isReadingQuantity, readingMeta, } from './quantity.js';
 export type { DisplayPreference, ReadingMeta, ReadingQuantity } from './quantity.js';
+export { baseUnitForQuantity, unitsForQuantity } from './quantity-units.js';
+export { QuantityUnitError, QuantityValueSchema, convertQuantityInput, isQuantityValue, paramMeta, paramMetaOf, } from './quantity-input.js';
+export type { ConvertQuantityInput, ParamMeta, QuantityUnitErrorCode, QuantityValue, } from './quantity-input.js';
 export { thresholdToBase, thresholdToDisplay } from './threshold.js';
 export { formatReading } from './format-reading.js';
 export type { FormatReadingInput, FormattedReading } from './format-reading.js';

package/dist/units/quantity-input.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A number a person types for a physical quantity — the input side of the
+ * value + unit contract (D972).
+ *
+ * Readings are stored in the base unit of their quantity (D944); a cap method
+ * param is stored in the unit its input schema DECLARES (`paramMeta`). The
+ * wire pair {@link QuantityValue} says "this number is expressed in this
+ * unit"; {@link convertQuantityInput} brings it to the stored unit and refuses,
+ * with a typed {@link QuantityUnitError}, a unit that cannot be that quantity.
+ */
+import { z } from 'zod';
+import { type ReadingQuantity } from './quantity.js';
+export type QuantityUnitErrorCode = 'non-finite' | 'unknown-unit' | 'cross-dimension'
+/** A unit was given for a field or param that is not a quantity. */
+ | 'no-quantity';
+/** A unit that cannot be applied to the number it was given with. */
+export declare class QuantityUnitError extends Error {
+    readonly code: QuantityUnitErrorCode;
+    constructor(code: QuantityUnitErrorCode, message: string);
+}
+/** The wire pair: `value` is expressed in `unit`. */
+export declare const QuantityValueSchema: z.ZodObject<{
+    value: z.ZodNumber;
+    unit: z.ZodString;
+}, z.core.$strip>;
+export type QuantityValue = z.infer<typeof QuantityValueSchema>;
+export declare function isQuantityValue(candidate: unknown): candidate is QuantityValue;
+export interface ConvertQuantityInput {
+    readonly value: number;
+    /** The unit `value` is expressed in, as the person picked it. */
+    readonly unit: string;
+    /** The unit to store: the quantity base, or a param's declared unit. */
+    readonly target: string;
+}
+/**
+ * `value` expressed in `unit`, brought to `target`. Throws
+ * {@link QuantityUnitError} for a non-finite value, an unknown unit or a unit
+ * of another dimension — never guesses.
+ */
+export declare function convertQuantityInput(input: ConvertQuantityInput): number;
+/** What a method input field declares: the quantity and the unit its value is in. */
+export interface ParamMeta {
+    readonly [key: string]: unknown;
+    readonly quantity: ReadingQuantity;
+    readonly unit: string;
+}
+/**
+ * Zod `.meta()` bag for a cap METHOD param that is a physical quantity — the
+ * input-side twin of `readingMeta`. The value is carried in `unit` (a gram
+ * portion stays in grams); the unit must belong to the quantity, checked once
+ * when the cap is declared.
+ */
+export declare function paramMeta(declared: {
+    readonly quantity: ReadingQuantity;
+    readonly unit: string;
+}): ParamMeta;
+/** The `paramMeta` on a method input field (or its unwrapped leaf), if any. */
+export declare function paramMetaOf(field: z.ZodType): ParamMeta | undefined;

package/dist/units/quantity-units.d.ts

@@ -0,0 +1,8 @@
+import { type ReadingQuantity } from './quantity.js';
+/** The unit a reading of `quantity` is stored in, or `undefined` when it has none. */
+export declare function baseUnitForQuantity(quantity: ReadingQuantity): string | undefined;
+/**
+ * The units a person can enter a number of `quantity` in — base unit first.
+ * Empty when the quantity carries no unit.
+ */
+export declare function unitsForQuantity(quantity: ReadingQuantity): readonly string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/types",
-  "version": "1.2.446",
+  "version": "1.2.448",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",