@decaf-ts/ui-decorators 0.20.7 → 0.20.9

package/lib/types/graph/constants.d.cts

@@ -10,6 +10,28 @@ export declare enum PortDirection {
     CONNECTION = "connection"
 }
 export type GraphNodeKind = string;
+/**
+ * Node face silhouette (D1, DECAF-50 §4.5). Manifest-authoritative: the
+ * projected node geometry renders this shape and its corner radius instead of a
+ * hardcoded template CSS value.
+ */
+export type GraphNodeShape = "rounded" | "square" | "pill";
+/**
+ * Manifest-declared, value-driven display rule (D1, DECAF-50 §4.5). The manifest
+ * `display` metadata is the single authority for node geometry; content-driven
+ * growth is expressed here and evaluated from the node instance's parameters —
+ * never as a hardcoded per-node formula or a direct DOM style write.
+ */
+export type GraphNodeSizeRule = {
+    /** Rule kind. Only `parameterCount` is defined: growth tracks an array parameter's length. */
+    type: "parameterCount";
+    /** Node-instance parameter whose item count drives the growth (e.g. `cases`). */
+    parameter: string;
+    /** Dimension that grows. */
+    dimension: "height" | "width";
+    /** Increment added per parameter item. */
+    perItem: number;
+};
 export type GraphConnectionRule = {
     allowSelf?: boolean;
     allowMultiple?: boolean;
@@ -30,6 +52,22 @@ export type GraphNodeMetadata = {
     maxChildren?: number;
     minWidth?: number;
     width?: number;
+    /**
+     * Node face silhouette (D1, DECAF-50 §4.5). Manifest-authoritative;
+     * folded into the manifest display fields by the D1 revision.
+     */
+    shape?: GraphNodeShape;
+    /**
+     * Node corner radius in pixels (D1, DECAF-50 §4.5). Manifest-authoritative;
+     * folded into the manifest display fields by the D1 revision.
+     */
+    cornerRadius?: number;
+    /**
+     * Manifest-declared, value-driven display rules (D1, DECAF-50 §4.5). Content
+     * growth (e.g. Switch case count) is expressed here and evaluated from the
+     * node instance's parameters — never hardcoded per-node formulas.
+     */
+    sizeRules?: GraphNodeSizeRule[];
     connectionRules?: GraphConnectionRule;
     metadata?: Record<string, unknown>;
     /**
@@ -222,6 +260,21 @@ export type GraphNodeDefinition = {
     ui?: Record<string, any>;
     graph?: GraphNodeMetadata;
     ports: GraphPortDefinition[];
+    /**
+     * Node face silhouette (D1, DECAF-50 §4.5), copied from
+     * {@link GraphNodeMetadata.shape} by `graphDefinitionOf`.
+     */
+    shape?: GraphNodeShape;
+    /**
+     * Node corner radius in pixels (D1, DECAF-50 §4.5), copied from
+     * {@link GraphNodeMetadata.cornerRadius} by `graphDefinitionOf`.
+     */
+    cornerRadius?: number;
+    /**
+     * Manifest-declared, value-driven display rules (D1, DECAF-50 §4.5), copied
+     * from {@link GraphNodeMetadata.sizeRules} by `graphDefinitionOf`.
+     */
+    sizeRules?: GraphNodeSizeRule[];
     /**
      * Effective color resolved from the category registry (or the node's
      * explicit `color` override). Computed by `graphDefinitionOf`.
@@ -262,6 +315,33 @@ export interface GraphCategoryStyle {
  * color/icon is set on the node.
  */
 export declare const GRAPH_DEFAULT_CATEGORY_STYLE: GraphCategoryStyle;
+/**
+ * Fallback node size in pixels when a manifest declares no `width`/`height`
+ * (D1, DECAF-50 §4.5). The manifest display remains the authority; this value
+ * only fills an absent manifest dimension, never overriding a declared one.
+ */
+export declare const GRAPH_DEFAULT_NODE_SIZE = 96;
+/**
+ * Default node corner radius in pixels (D1, DECAF-50 §4.5) applied only when the
+ * manifest declares no `cornerRadius`. Folded into the manifest display fields by
+ * the D1 revision; no template CSS pins the radius.
+ */
+export declare const GRAPH_DEFAULT_NODE_CORNER_RADIUS = 18;
+/**
+ * Evaluates a node definition's manifest-declared, value-driven display rules
+ * (D1, DECAF-50 §4.5) against per-parameter item counts. Content growth is
+ * driven by the manifest, never by hardcoded per-node formulas: each matching
+ * `parameterCount` rule adds `perItem * count` to its dimension. Falls back to the
+ * manifest `width`/`height` when no rule applies.
+ *
+ * @param definition - The manifest definition carrying `width`/`height`/`sizeRules`.
+ * @param parameterCounts - Item counts keyed by parameter id (e.g. `cases`).
+ * @returns The resolved `{ width, height }` in pixels.
+ */
+export declare function graphNodeSizeOf(definition: Pick<GraphNodeDefinition, "width" | "height" | "sizeRules">, parameterCounts?: Record<string, number>): {
+    width: number;
+    height: number;
+};
 /**
  * Registers a category style (color + optional icon) in the global registry.
  * Call this at module init time (e.g. in the engine's node declarations) to
@@ -273,15 +353,30 @@ export declare function registerGraphCategoryStyle(category: string, style: Grap
  */
 export declare function graphCategoryStyleOf(category?: string): GraphCategoryStyle;
 /**
- * Resolves the effective color for a node: explicit `color` overrides the
- * category color, which overrides the default.
+ * Resolves the effective color for a node (D7/G3-22, DECAF-50 §4.5).
+ *
+ * The **category base colour is authoritative**: every node of a registered
+ * category renders that one base colour, so same-category nodes never diverge.
+ * An explicit per-node `color` is an override applied at this single precedence
+ * point — it only wins when the category has no registered base style.
+ *
+ * @param explicitColor - The node's explicit per-node colour override, when any.
+ * @param category - The node's display category.
+ * @param override - A user-applied per-node colour override; wins over everything.
+ * @returns The resolved colour.
  */
-export declare function resolveEffectiveColor(explicitColor?: string, category?: string): string;
+export declare function resolveEffectiveColor(explicitColor?: string, category?: string, override?: string): string;
 /**
- * Resolves the effective icon for a node: explicit `icon` overrides the
- * category icon, which overrides the default.
+ * Resolves the effective icon for a node (D7/G3-22, DECAF-50 §4.5). The
+ * **category base icon is authoritative**; an explicit per-node `icon` is an
+ * override applied at this single precedence point.
+ *
+ * @param explicitIcon - The node's explicit per-node icon override, when any.
+ * @param category - The node's display category.
+ * @param override - A user-applied per-node icon override; wins over everything.
+ * @returns The resolved icon name.
  */
-export declare function resolveEffectiveIcon(explicitIcon?: string, category?: string): string;
+export declare function resolveEffectiveIcon(explicitIcon?: string, category?: string, override?: string): string;
 import type { GraphRunStatus } from "./types.d.cts";
 /**
  * Disabled-node execution semantics (DECAF-50 §4.9).

package/lib/types/graph/constants.d.mts

@@ -10,6 +10,28 @@ export declare enum PortDirection {
     CONNECTION = "connection"
 }
 export type GraphNodeKind = string;
+/**
+ * Node face silhouette (D1, DECAF-50 §4.5). Manifest-authoritative: the
+ * projected node geometry renders this shape and its corner radius instead of a
+ * hardcoded template CSS value.
+ */
+export type GraphNodeShape = "rounded" | "square" | "pill";
+/**
+ * Manifest-declared, value-driven display rule (D1, DECAF-50 §4.5). The manifest
+ * `display` metadata is the single authority for node geometry; content-driven
+ * growth is expressed here and evaluated from the node instance's parameters —
+ * never as a hardcoded per-node formula or a direct DOM style write.
+ */
+export type GraphNodeSizeRule = {
+    /** Rule kind. Only `parameterCount` is defined: growth tracks an array parameter's length. */
+    type: "parameterCount";
+    /** Node-instance parameter whose item count drives the growth (e.g. `cases`). */
+    parameter: string;
+    /** Dimension that grows. */
+    dimension: "height" | "width";
+    /** Increment added per parameter item. */
+    perItem: number;
+};
 export type GraphConnectionRule = {
     allowSelf?: boolean;
     allowMultiple?: boolean;
@@ -30,6 +52,22 @@ export type GraphNodeMetadata = {
     maxChildren?: number;
     minWidth?: number;
     width?: number;
+    /**
+     * Node face silhouette (D1, DECAF-50 §4.5). Manifest-authoritative;
+     * folded into the manifest display fields by the D1 revision.
+     */
+    shape?: GraphNodeShape;
+    /**
+     * Node corner radius in pixels (D1, DECAF-50 §4.5). Manifest-authoritative;
+     * folded into the manifest display fields by the D1 revision.
+     */
+    cornerRadius?: number;
+    /**
+     * Manifest-declared, value-driven display rules (D1, DECAF-50 §4.5). Content
+     * growth (e.g. Switch case count) is expressed here and evaluated from the
+     * node instance's parameters — never hardcoded per-node formulas.
+     */
+    sizeRules?: GraphNodeSizeRule[];
     connectionRules?: GraphConnectionRule;
     metadata?: Record<string, unknown>;
     /**
@@ -222,6 +260,21 @@ export type GraphNodeDefinition = {
     ui?: Record<string, any>;
     graph?: GraphNodeMetadata;
     ports: GraphPortDefinition[];
+    /**
+     * Node face silhouette (D1, DECAF-50 §4.5), copied from
+     * {@link GraphNodeMetadata.shape} by `graphDefinitionOf`.
+     */
+    shape?: GraphNodeShape;
+    /**
+     * Node corner radius in pixels (D1, DECAF-50 §4.5), copied from
+     * {@link GraphNodeMetadata.cornerRadius} by `graphDefinitionOf`.
+     */
+    cornerRadius?: number;
+    /**
+     * Manifest-declared, value-driven display rules (D1, DECAF-50 §4.5), copied
+     * from {@link GraphNodeMetadata.sizeRules} by `graphDefinitionOf`.
+     */
+    sizeRules?: GraphNodeSizeRule[];
     /**
      * Effective color resolved from the category registry (or the node's
      * explicit `color` override). Computed by `graphDefinitionOf`.
@@ -262,6 +315,33 @@ export interface GraphCategoryStyle {
  * color/icon is set on the node.
  */
 export declare const GRAPH_DEFAULT_CATEGORY_STYLE: GraphCategoryStyle;
+/**
+ * Fallback node size in pixels when a manifest declares no `width`/`height`
+ * (D1, DECAF-50 §4.5). The manifest display remains the authority; this value
+ * only fills an absent manifest dimension, never overriding a declared one.
+ */
+export declare const GRAPH_DEFAULT_NODE_SIZE = 96;
+/**
+ * Default node corner radius in pixels (D1, DECAF-50 §4.5) applied only when the
+ * manifest declares no `cornerRadius`. Folded into the manifest display fields by
+ * the D1 revision; no template CSS pins the radius.
+ */
+export declare const GRAPH_DEFAULT_NODE_CORNER_RADIUS = 18;
+/**
+ * Evaluates a node definition's manifest-declared, value-driven display rules
+ * (D1, DECAF-50 §4.5) against per-parameter item counts. Content growth is
+ * driven by the manifest, never by hardcoded per-node formulas: each matching
+ * `parameterCount` rule adds `perItem * count` to its dimension. Falls back to the
+ * manifest `width`/`height` when no rule applies.
+ *
+ * @param definition - The manifest definition carrying `width`/`height`/`sizeRules`.
+ * @param parameterCounts - Item counts keyed by parameter id (e.g. `cases`).
+ * @returns The resolved `{ width, height }` in pixels.
+ */
+export declare function graphNodeSizeOf(definition: Pick<GraphNodeDefinition, "width" | "height" | "sizeRules">, parameterCounts?: Record<string, number>): {
+    width: number;
+    height: number;
+};
 /**
  * Registers a category style (color + optional icon) in the global registry.
  * Call this at module init time (e.g. in the engine's node declarations) to
@@ -273,15 +353,30 @@ export declare function registerGraphCategoryStyle(category: string, style: Grap
  */
 export declare function graphCategoryStyleOf(category?: string): GraphCategoryStyle;
 /**
- * Resolves the effective color for a node: explicit `color` overrides the
- * category color, which overrides the default.
+ * Resolves the effective color for a node (D7/G3-22, DECAF-50 §4.5).
+ *
+ * The **category base colour is authoritative**: every node of a registered
+ * category renders that one base colour, so same-category nodes never diverge.
+ * An explicit per-node `color` is an override applied at this single precedence
+ * point — it only wins when the category has no registered base style.
+ *
+ * @param explicitColor - The node's explicit per-node colour override, when any.
+ * @param category - The node's display category.
+ * @param override - A user-applied per-node colour override; wins over everything.
+ * @returns The resolved colour.
  */
-export declare function resolveEffectiveColor(explicitColor?: string, category?: string): string;
+export declare function resolveEffectiveColor(explicitColor?: string, category?: string, override?: string): string;
 /**
- * Resolves the effective icon for a node: explicit `icon` overrides the
- * category icon, which overrides the default.
+ * Resolves the effective icon for a node (D7/G3-22, DECAF-50 §4.5). The
+ * **category base icon is authoritative**; an explicit per-node `icon` is an
+ * override applied at this single precedence point.
+ *
+ * @param explicitIcon - The node's explicit per-node icon override, when any.
+ * @param category - The node's display category.
+ * @param override - A user-applied per-node icon override; wins over everything.
+ * @returns The resolved icon name.
  */
-export declare function resolveEffectiveIcon(explicitIcon?: string, category?: string): string;
+export declare function resolveEffectiveIcon(explicitIcon?: string, category?: string, override?: string): string;
 import type { GraphRunStatus } from "./types.d.mts";
 /**
  * Disabled-node execution semantics (DECAF-50 §4.9).

package/lib/types/graph/document/GraphNodeInstance.d.cts

@@ -2,6 +2,21 @@ import type { GraphInputBinding, GraphOutputBinding } from "./GraphNodeBinding.d
 import type { GraphJsonValue } from "./GraphJsonValue.d.cts";
 import type { GraphLoopConfiguration } from "./GraphLoopConfiguration.d.cts";
 import type { GraphNodeUiState } from "./GraphWorkflowUiState.d.cts";
+/**
+ * Document-carried UI data-pinning state (D4, DECAF-50 §4.22). Data pinning
+ * freezes the node's parameter values so downstream runs reuse them, and is a
+ * distinct concept from the engine's cache pinning (`GraphPinning`): this state is
+ * written into the canonical document and survives save/load round-trips.
+ */
+export interface GraphNodePinState {
+    /**
+     * Parameter values frozen when the node was pinned. Downstream runs apply this
+     * snapshot on top of the node's live parameters.
+     */
+    parameters: Record<string, GraphJsonValue>;
+    /** ISO-8601 timestamp of when the pin was captured, when known. */
+    pinnedAt?: string;
+}
 export interface GraphNodeInstance {
     id: string;
     kind: string;
@@ -13,4 +28,9 @@ export interface GraphNodeInstance {
     metadata?: Record<string, GraphJsonValue>;
     loop?: GraphLoopConfiguration;
     ui?: GraphNodeUiState;
+    /**
+     * UI data-pinning state (D4, DECAF-50 §4.22). Present iff the node is
+     * pinned; the frozen parameter snapshot is what downstream runs reuse.
+     */
+    pinned?: GraphNodePinState;
 }

package/lib/types/graph/document/GraphNodeInstance.d.mts

@@ -2,6 +2,21 @@ import type { GraphInputBinding, GraphOutputBinding } from "./GraphNodeBinding.d
 import type { GraphJsonValue } from "./GraphJsonValue.d.mts";
 import type { GraphLoopConfiguration } from "./GraphLoopConfiguration.d.mts";
 import type { GraphNodeUiState } from "./GraphWorkflowUiState.d.mts";
+/**
+ * Document-carried UI data-pinning state (D4, DECAF-50 §4.22). Data pinning
+ * freezes the node's parameter values so downstream runs reuse them, and is a
+ * distinct concept from the engine's cache pinning (`GraphPinning`): this state is
+ * written into the canonical document and survives save/load round-trips.
+ */
+export interface GraphNodePinState {
+    /**
+     * Parameter values frozen when the node was pinned. Downstream runs apply this
+     * snapshot on top of the node's live parameters.
+     */
+    parameters: Record<string, GraphJsonValue>;
+    /** ISO-8601 timestamp of when the pin was captured, when known. */
+    pinnedAt?: string;
+}
 export interface GraphNodeInstance {
     id: string;
     kind: string;
@@ -13,4 +28,9 @@ export interface GraphNodeInstance {
     metadata?: Record<string, GraphJsonValue>;
     loop?: GraphLoopConfiguration;
     ui?: GraphNodeUiState;
+    /**
+     * UI data-pinning state (D4, DECAF-50 §4.22). Present iff the node is
+     * pinned; the frozen parameter snapshot is what downstream runs reuse.
+     */
+    pinned?: GraphNodePinState;
 }

package/lib/types/graph/document/GraphWorkflowUiState.d.cts

@@ -13,6 +13,14 @@ export type GraphNodeUiState = {
         width?: number;
         height?: number;
     };
+    /**
+     * Explicit user resize flag (D1, DECAF-50 §4.5). Only a genuine user resize
+     * sets this; a carried default or template CSS never wins over the manifest
+     * display. `ui.size` is honoured by projection only when this is `true`.
+     */
+    resized?: boolean;
+    /** Explicit user per-node colour override (D7, DECAF-50 §4.5), when any. */
+    color?: string;
     expanded?: boolean;
     selectedTab?: string;
 };

package/lib/types/graph/document/GraphWorkflowUiState.d.mts

@@ -13,6 +13,14 @@ export type GraphNodeUiState = {
         width?: number;
         height?: number;
     };
+    /**
+     * Explicit user resize flag (D1, DECAF-50 §4.5). Only a genuine user resize
+     * sets this; a carried default or template CSS never wins over the manifest
+     * display. `ui.size` is honoured by projection only when this is `true`.
+     */
+    resized?: boolean;
+    /** Explicit user per-node colour override (D7, DECAF-50 §4.5), when any. */
+    color?: string;
     expanded?: boolean;
     selectedTab?: string;
 };

package/lib/types/index.d.cts

@@ -16,19 +16,19 @@ export * from "./dashboard/index.d.cts";
  * @const VERSION
  * @memberOf module:ui-decorators
  */
-export declare const VERSION = "0.20.7";
+export declare const VERSION = "0.20.8";
 /**
  * @description Represents the current commit hash of the module build.
  * @summary Stores the current git commit hash for the package. The build replaces
  * the placeholder with the actual commit hash at publish time.
  * @const COMMIT
  */
-export declare const COMMIT = "f92e8d1";
+export declare const COMMIT = "0285f65";
 /**
  * @description Represents the full version string of the module.
  * @summary Stores the semver version and commit hash for the package.
  * The build replaces the placeholder with the actual `<version>-<commit>` value at publish time.
  * @const FULL_VERSION
  */
-export declare const FULL_VERSION = "0.20.7-f92e8d1";
+export declare const FULL_VERSION = "0.20.8-0285f65";
 export declare const PACKAGE_NAME = "@decaf-ts/ui-decorators";

package/lib/types/index.d.mts

@@ -16,19 +16,19 @@ export * from "./dashboard/index.d.mts";
  * @const VERSION
  * @memberOf module:ui-decorators
  */
-export declare const VERSION = "0.20.7";
+export declare const VERSION = "0.20.8";
 /**
  * @description Represents the current commit hash of the module build.
  * @summary Stores the current git commit hash for the package. The build replaces
  * the placeholder with the actual commit hash at publish time.
  * @const COMMIT
  */
-export declare const COMMIT = "f92e8d1";
+export declare const COMMIT = "0285f65";
 /**
  * @description Represents the full version string of the module.
  * @summary Stores the semver version and commit hash for the package.
  * The build replaces the placeholder with the actual `<version>-<commit>` value at publish time.
  * @const FULL_VERSION
  */
-export declare const FULL_VERSION = "0.20.7-f92e8d1";
+export declare const FULL_VERSION = "0.20.8-0285f65";
 export declare const PACKAGE_NAME = "@decaf-ts/ui-decorators";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decaf-ts/ui-decorators",
-  "version": "0.20.7",
+  "version": "0.20.9",
   "description": "Extension of decorator validation to ui elements to allow for web integration",
   "type": "module",
   "exports": {
@@ -128,6 +128,8 @@
   "main": "./lib/cjs/index.cjs",
   "module": "./lib/esm/index.js",
   "sideEffects": [
+    "./lib/esm/index.js",
+    "./lib/cjs/index.cjs",
     "./lib/esm/overrides/index.js",
     "./lib/esm/graph/overrides/index.js",
     "./lib/esm/graph/overrides/overrides.js",