feat(directives): attribute/tag adopt the shared textStyle block (size + color) (#496)

* feat(directives): attribute/tag adopt the shared textStyle block (size + color)

The `attribute` and `tag` directives previously supported only a flat
`textSize` field (added in #491). The shared TextStyle abstraction
(src/layout/style/text-style.ts) already documented attribute/tag lines as
a consumer, but they were never wired to it.

Wire them into the shared `textStyle: { size, color }` block — the same
shape edgeStyle/atomStyle use — so each attribute/tag line can set its own
color as well as size. `textSize` moves to `textStyle.size` as a clean
break (no deprecate-and-warn): textSize only shipped in #491, so there is
no back-compat burden.

Changes:
- layoutspec: AttributeDirective/TagDirective carry `textStyle?: TextStyle`,
  parsed via the shared parseTextStyle; drop normalizeAttrTextSize.
- layoutinstance: the per-attribute channel carries the whole TextStyle;
  getAttributeTextSize -> getAttributeTextStyle; box sizer reads .size.
- interfaces/webcolatranslator: attributeSizes -> attributeTextStyles.
- webcola-cnd-graph: attribute/tag tspans get font-size from .size and
  fill from .color (null = inherit the themed label, so dark mode adapts).
- spec-editor registry: attribute/tag expose the shared textStyle group.
- docs: YAML_SPECIFICATION.md, site/directives.md, site/yaml-reference.md,
  and the agent-manifest (1.8.0 -> 1.9.0) document size + color.
- tests: new attribute-tag-textstyle suite (parse + end-to-end for both
  directives, incl. sparse color-only and absent cases) — #491 had none.
- bump 3.0.1 -> 3.1.0 (minor: additive optional fields).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* test(spec-editor): cover attribute/tag textStyle in the no-code builder

The no-code editor (SpecEditor/BuilderView) is driven by the registry, so
the prior commit's registry change already wires attribute/tag to the
shared textStyle group — FieldRenderer renders `kind: 'group'` generically
(same path edgeStyle/atomStyle use) and the legacy NoCodeView shim passes
params through untouched. Add explicit coverage + fix stale docs:

- Assert attribute/tag expose a `textStyle` group field with children
  [size, color] in the directive registry.
- Ingest + round-trip an attribute textStyle block and a tag textStyle
  block through the codec (parseYamlToState → serializeStateToYaml).
- Fix the registry header shape-manifest comment: attribute/tag now show
  `textStyle?:{size,color}` (they never listed the field).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: sidprasad

docs/YAML_SPECIFICATION.md

@@ -693,7 +693,9 @@ Converts edge relationships into node attributes (displayed as key-value pairs o
     field: <field-name>          # Required: Relation to convert to attribute
     selector: <unary-selector>   # Optional: Filter which source atoms apply
     filter: <n-ary-selector>     # Optional: Filter which tuples to include
-    textSize: <size>             # Optional: small | normal | large (default: normal)
+    textStyle:                   # Optional: style the attribute line (shared block)
+      size: <small|normal|large> #   font size relative to the node label (default: normal)
+      color: <color>             #   text color (any CSS color)
 ```
 
 **Fields:**
@@ -703,13 +705,14 @@ Converts edge relationships into node attributes (displayed as key-value pairs o
 | `field` | ✅ Yes | string | Name of the relation to display as attribute |
 | `selector` | ❌ No | string | Unary selector to filter source atoms |
 | `filter` | ❌ No | string | N-ary selector to filter specific tuples |
-| `textSize` | ❌ No | `small` \| `normal` \| `large` | Size of this attribute's text, relative to the node label. Default `normal`. |
+| `textStyle.size` | ❌ No | `small` \| `normal` \| `large` | Size of this attribute's text, relative to the node label. Default `normal`. |
+| `textStyle.color` | ❌ No | string | Text color of this attribute's line (any CSS color). Default inherits the node label color. |
 
 **Behavior:**
 - Removes the edge from the graph
 - Displays the target value as an attribute on the source node
 - Multiple targets become a list
-- `textSize` controls the line's font size: `large` renders **bigger** than the node's label, `normal` is the default (smaller than the label), and `small` is smaller still. The node box grows/shrinks to fit.
+- `textStyle` is the same shared block edges and atoms use. `size` controls the line's font size: `large` renders **bigger** than the node's label, `normal` is the default (smaller than the label), and `small` is smaller still — the node box grows/shrinks to fit. `color` sets the line's text color (unset = inherit the node's label color, so dark mode still adapts).
 
 **Examples:**
 
@@ -728,10 +731,10 @@ Converts edge relationships into node attributes (displayed as key-value pairs o
     field: status
     filter: 'status & (univ -> Active)'
 
-# Emphasize a key attribute — rendered larger than the node label
+# Emphasize a key attribute — larger than the node label, in red
 - attribute:
     field: balance
-    textSize: large
+    textStyle: { size: large, color: "#c0392b" }
 ```
 
 ---
@@ -745,7 +748,9 @@ Adds computed attributes to nodes based on selector evaluation. Unlike `attribut
     toTag: <unary-selector>      # Required: Selector for atoms to receive the tag
     name: <attribute-name>       # Required: Name of the attribute to display
     value: <n-ary-selector>      # Required: Selector whose result becomes the value
-    textSize: <size>             # Optional: small | normal | large (default: normal)
+    textStyle:                   # Optional: style the tag line (shared block)
+      size: <small|normal|large> #   font size relative to the node label (default: normal)
+      color: <color>             #   text color (any CSS color)
 ```
 
 **Fields:**
@@ -755,13 +760,14 @@ Adds computed attributes to nodes based on selector evaluation. Unlike `attribut
 | `toTag` | ✅ Yes | string | Unary selector for atoms that receive this tag |
 | `name` | ✅ Yes | string | Attribute name to display |
 | `value` | ✅ Yes | string | N-ary selector returning the attribute values |
-| `textSize` | ❌ No | `small` \| `normal` \| `large` | Size of this tag's text, relative to the node label. Default `normal`. |
+| `textStyle.size` | ❌ No | `small` \| `normal` \| `large` | Size of this tag's text, relative to the node label. Default `normal`. |
+| `textStyle.color` | ❌ No | string | Text color of this tag's line (any CSS color). Default inherits the node label color. |
 
 **Behavior:**
 - Does NOT remove edges (unlike `attribute`)
 - For binary results: displays as `name: value`
 - For n-ary results: displays as `name[key1][key2]: value`
-- `textSize` controls the line's font size: `large` renders **bigger** than the node's label, `normal` is the default (smaller than the label), and `small` is smaller still.
+- `textStyle` is the same shared block edges and atoms use. `size` controls the line's font size: `large` renders **bigger** than the node's label, `normal` is the default (smaller than the label), and `small` is smaller still. `color` sets the line's text color (unset = inherit the node's label color).
 
 **Examples:**
 
@@ -778,12 +784,12 @@ Adds computed attributes to nodes based on selector evaluation. Unlike `attribut
     name: score
     value: grades
 
-# De-emphasize a secondary tag — rendered smaller than the default
+# De-emphasize a secondary tag — smaller than the default, muted gray
 - tag:
     toTag: Person
     name: id
     value: internalId
-    textSize: small
+    textStyle: { size: small, color: "#888" }
 ```
 
 ---

docs/agent-manifest.json

@@ -3,7 +3,7 @@
   "description": "Canonical YAML specification for CnD layout",
   "file": "docs/YAML_SPECIFICATION.md",
   "cdn_url": "https://cdn.jsdelivr.net/gh/sidprasad/cnd-core@main/docs/YAML_SPECIFICATION.md",
-  "pinned_example": "https://cdn.jsdelivr.net/gh/sidprasad/cnd-core@v1.8.0/docs/YAML_SPECIFICATION.md",
+  "pinned_example": "https://cdn.jsdelivr.net/gh/sidprasad/cnd-core@v1.9.0/docs/YAML_SPECIFICATION.md",
   "content_type": "text/markdown",
-  "version": "1.8.0"
+  "version": "1.9.0"
 }

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "spytial-core",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "A fully client-side application for SpyTial.",
   "main": "./dist/browser/spytial-core-complete.global.js",
   "types": "./dist/browser/spytial-core-complete.global.d.ts",

package.json

@@ -453,22 +453,25 @@ Converts an edge relationship into a **label on the source node**. The edge is r
     field: <field-name>          # Required
     selector: <unary-selector>   # Optional
     filter: <n-ary-selector>     # Optional
-    textSize: <size>             # Optional: small | normal | large
+    textStyle:                   # Optional: shared text-style block
+      size: <small|normal|large> #   font size relative to the node label
+      color: <color>             #   text color (any CSS color)
 ```
 
 | Field | Required | Type | Description |
 |-------|----------|------|-------------|
 | `field` | Yes | string | Relation to display as an attribute |
 | `selector` | No | string | Filter by source atom type |
 | `filter` | No | string | Filter specific tuples |
-| `textSize` | No | `small` \| `normal` \| `large` | Size of the attribute text relative to the node label (default `normal`) |
+| `textStyle.size` | No | `small` \| `normal` \| `large` | Size of the attribute text relative to the node label (default `normal`) |
+| `textStyle.color` | No | string | Text color of the attribute line (default inherits the node label color) |
 
 ### What Happens
 
 - The edge for this field is **removed** from the graph
 - The target value appears as `field: value` on the source node
 - Multiple targets become a comma-separated list
-- `textSize` scales the line's font: `large` is bigger than the node label, `normal` (default) is smaller, `small` smaller still; the node box resizes to fit
+- `textStyle` is the same shared block edges and atoms use. `size` scales the line's font (`large` bigger than the node label, `normal` default, `small` smaller still; the node box resizes to fit); `color` sets its text color (unset = inherit the node label color)
 
 ### Examples
 
@@ -524,22 +527,25 @@ Adds computed labels to nodes **without** removing edges. Unlike `attribute`, th
     toTag: <unary-selector>      # Required
     name: <attribute-name>       # Required
     value: <n-ary-selector>      # Required
-    textSize: <size>             # Optional: small | normal | large
+    textStyle:                   # Optional: shared text-style block
+      size: <small|normal|large> #   font size relative to the node label
+      color: <color>             #   text color (any CSS color)
 ```
 
 | Field | Required | Type | Description |
 |-------|----------|------|-------------|
 | `toTag` | Yes | string | Selector for atoms that receive the tag |
 | `name` | Yes | string | Label name to display |
 | `value` | Yes | string | Selector whose result becomes the value |
-| `textSize` | No | `small` \| `normal` \| `large` | Size of the tag text relative to the node label (default `normal`) |
+| `textStyle.size` | No | `small` \| `normal` \| `large` | Size of the tag text relative to the node label (default `normal`) |
+| `textStyle.color` | No | string | Text color of the tag line (default inherits the node label color) |
 
 ### Behavior
 
 - Does **NOT** remove edges (unlike `attribute`)
 - For binary results: displays as `name: value`
 - For higher-arity results: displays as `name[key1][key2]: value`
-- `textSize` scales the line's font: `large` is bigger than the node label, `normal` (default) is smaller, `small` smaller still
+- `textStyle` is the same shared block edges and atoms use. `size` scales the line's font (`large` bigger than the node label, `normal` default, `small` smaller still); `color` sets its text color (unset = inherit the node label color)
 
 ### Examples
 

site/directives.md

@@ -108,11 +108,13 @@ directives:
   - attribute:
       field: age
       selector: Person
+      textStyle: { size: large, color: "#c0392b" }  # optional: shared size + color block
 
   - tag:
       toTag: Student
       name: grade
       value: currentGrade
+      textStyle: { size: small, color: "#2980b9" }
 
   - icon:
       selector: File

site/yaml-reference.md

@@ -1,7 +1,6 @@
 import { Group } from "webcola";
 import { RelativeOrientationConstraint, CyclicOrientationConstraint, AlignConstraint, GroupByField, GroupBySelector, RelativeDirection } from "./layoutspec";
 import { EdgeStyle } from "./edge-style";
-import { AttrTextSize } from "./text-extent";
 import type { TextStyle } from "./style/text-style";
 
 export interface LayoutGroup {
@@ -88,11 +87,12 @@ export interface LayoutNode {
     groups?: string[];
     attributes?: Record<string, string[]>;
     /**
-     * Per-attribute-key text-size tier (from the `textSize` field of an
-     * `attribute` or `tag` directive). Keyed by the same attribute key as
-     * {@link attributes}. Absent keys render at the normal secondary size.
+     * Per-attribute-key text style (the shared `textStyle` block: size + color)
+     * from an `attribute` or `tag` directive. Keyed by the same attribute key as
+     * {@link attributes}. Absent keys render at the normal secondary size with
+     * the inherited label color.
      */
-    attributeSizes?: Record<string, AttrTextSize>;
+    attributeTextStyles?: Record<string, TextStyle>;
     /**
      * Labels associated with this node from the data instance (e.g., Skolems).
      * These are displayed prominently on nodes, typically styled in the node's color.