MASS4.Guinevere.Graphs 6.6.0

Guinevere.Graphs

GraphDocumentView.SelectUpstream() selects selected nodes and their transitive dependencies; SelectDownstream() selects their transitive consumers. Both follow all authored edge types, handle cycles, and include the starting nodes. With no selection they use the focused node or a focused port's owner. Selected or focused links seed both endpoint nodes. Selected groups seed all descendant nodes. Traversal crosses collapsed groups and selects their visible container without expanding them. With no node seeds the selection stays unchanged. These are view selection operations and leave the document and undo history intact. The playground exposes both actions in its Edit menu and sandbox command palette, including the FSM scenario's Edit menu.

MASS4.Guinevere.Graphs is a .NET 10 GUI package built on Guinevere, PSS styling and the published MASS4.Graph package, pinned to exactly 1.1.0 so that core upgrades are deliberate. It has no Excalibur or engine dependency. The generic canvas consumes immutable view descriptions; GraphDocumentView adapts the real headless document and editor without implementing a parallel model.

Keep one GraphCanvas per surface and call Draw in both Guinevere passes. Supply GraphElementView descriptions through a domain adapter. Only visible descriptions build layout controls; all descriptions remain available for logical navigation and accessibility. Bounds must conservatively enclose the complete node or edge ink, including curves. The package owns camera, selection, logical focus, and view metadata only. Domain payloads remain opaque; topology, type registration, payload serialization and undo are supplied by the headless core.

The element callback runs inside a stable, keyed, camera-transformed node. Draw in gui.CurrentNode.Rect or build child controls normally; text, hit tests, and nested controls inherit zoom. Screen transforms use viewport logical units, and display density belongs to the containing Guinevere viewport. World coordinates and camera calculations use doubles. WorldToScreen/ScreenToWorld include the last laid-out host transform; Camera.WorldToView/ViewToWorld use viewport-local units. An optional camera constructor argument configures zoom limits. Build and render use one descriptor and camera snapshot; resize or initial layout requests a settling frame.

Navigation: middle-drag pans; wheel zooms under the pointer; Ctrl+arrows pans; +/− zooms around the viewport center; 0 resets; Home frames all; F frames selection. Arrows move logical focus between nodes using world geometry. Enter enters a node's ports and starts/completes a connection; Tab/Shift+Tab cycles its ports; Escape cancels a connection or returns to the node. Space toggles view selection; Delete asks the adapter to delete the focused element. Tab leaves the surface when no ports are active; Escape returns from ports before leaving. Embedded input controls retain their own keyboard handling. The camera and Navigation methods are also directly callable by application commands.

Alt+arrows cycles logical links in adapter order so they can be inspected and deleted with the keyboard; Escape returns from a link to an available endpoint.

Set Navigation.EditRequested to execute requests through the real graph editor, and return its command result and diagnostics for announcements. An absent handler produces a validation announcement and changes no document. Navigation.SearchRequested opens a consumer-owned searchable command palette (Ctrl+K) or registry-backed creation palette (Insert/Shift+A); this package does not manufacture node registrations. Consumers must request a frame after out-of-band changes, as with other Guinevere state.

For real documents, create GraphDocumentView(editor) and call Draw(gui) in both passes. It builds labeled nodes and ports, cubic connectors, click/drag linking previews, curve selection and edit-adapter commands. AddNode, connection creation, Delete and undo/redo use that editor, including its compatibility strategy and validation rules. MG diagnostics remain available as structured Diagnostics; selection and connection events flow through the existing semantics bridge. Palette(query) searches editor.Document.Registry.NodeTypes.Entries, so generated registration remains transparent to the GUI.

Connections replace links occupying single-connection ports through one atomic CompositeCommand; a rejected replacement restores the original links and identities. Reconnecting identical endpoints succeeds without a mutation or history step. Set AvoidReplacingConnections to reject duplicates and occupied ports using the core diagnostics. Delete/Backspace on a focused port invokes DisconnectPort, removing all its attached links as one undoable command; the port remains intact.

Node payloads stay opaque. NodeTitle is an optional domain-owned presentation callback and is skipped for unknown node types. Default descriptions preserve unknown nodes and expose their error state. Positions are a separate view dictionary. GUI-owned layout commands participate in the real editor history alongside document commands but record no document changes: they never alter serialized metadata or invalidate evaluation. A group drag is one history step; keyboard nudges and ResetLayout are also undoable. Reset retains existing IDs, labels, ports, payloads, edges and earlier history. SetPosition supplies baseline metadata without recording a step. Initial positions can come from the document's optional layout metadata. GraphConnector supplies drawing, hit testing and conservative bounds for culling, including backward connections.

Rendering uses the normal PSS cascade. GraphStyles.Ensure(gui) installs the embedded Styles/graph.pss below application sheets; drawing also installs it automatically. Add a third-party sheet to gui.StyleSheets, use inherited tokens, or scope selectors with GraphDocumentView.StyleClasses. NodeClasses adds domain classes to registered nodes, so bricks can supply rules such as .material graph-node.texture { background-color = #243748; border-radius = 3; } without changing graph code. GraphTheme and GraphCanvasStyle have been removed.

The public selectors are graph-editor, graph-canvas, graph-node, graph-header, graph-title, graph-content, graph-port, graph-port-label, graph-link, graph-badge, graph-grid, graph-focus, graph-minimap, graph-minimap-node, graph-minimap-viewport, graph-flow, graph-flow-label and graph-marquee, graph-group and graph-group-header. Nodes, links and badges expose :selected, :warning and :error where applicable; links also expose :preview and :outline, ports expose :input, :output, :compatible and :incompatible, and grid lines expose :major and :axis. Compatibility highlights are a direction/type hint; the real editor still validates the complete command and its domain rules.

Use existing properties: background-color, color, border-*, outline-*, font-*, padding-*, width, height, min-width, max-width, gap, margin, left, top, right, stroke, stroke-width, stroke-dasharray, stroke-dashoffset and marker-width. Node cards and labels support normal PSS brushes, radii, shadows and text inheritance. Links accept SVG-style dash/gap lists, repeating odd lists, and PSS effects such as filter = drop-shadow(0 0 4 #55d8ffb0). Only graph-port-spacing (node port-row pitch) and graph-major-every (grid major-line interval) are graph-specific properties; grid gap controls minimum screen spacing. Flow gap controls pulse spacing, and its width bounds control pulse diameter. See the embedded sheet for defaults and the playground's Blueprint, Paper and High contrast sheets for complete examples.

Routing selects Bézier, straight or orthogonal links; routing and CompactZoom/OutlineZoom remain behavior options. NodePresenter draws a domain body in the slot sized by ContentHeight, inheriting PSS typography, colors and tokens; GraphNodeVisual.Style also exposes resolved declarations. NodeBadges chooses badge text and PortShape chooses marker geometry; their appearance comes from PSS. LinkRenderer can replace a resolved stroke. Domain callbacks never receive unavailable node types. Validation and last-edit diagnostics mark the affected elements. LinkHitTolerance and PortHitRadius remain screen-unit behavior settings independent of stroke width and zoom. Compact LOD omits port labels/content; Outline omits ports/titles and disables pointer port targeting. Logical navigation and accessibility remain available.

Click selects a node or link, Shift+click adds it, and Ctrl+click toggles it. Drag empty canvas space for rectangle selection; Shift adds and Ctrl toggles the intersected nodes and actual crossing link segments. Ctrl+A selects all. Shift+arrows nudges by GridSize; SnapSelection, AlignSelection and DistributeSelection are reversible layout commands. SnapToGrid snaps completed drags. Alt+drag previews a duplicate move and inserts the copied subgraph on release as one undo step; Escape cancels the preview without changing topology or history. ContextRequested lets applications expose the same edit actions from a right click.

Ctrl+C/X/V and Ctrl+D copy, cut, paste and duplicate through the host clipboard and real editor. CopySelection includes selected nodes and internal links, with domain serializers; Paste generates fresh node/port/edge IDs as one validated command. RemapClipboardPayload lets a domain remap references inside its opaque payload, receiving the complete node/port/edge identity map. Deletion and paste restore selection with topology on undo/redo. Unsupported unknown/extended nodes or missing variable dependencies reject paste with diagnostics, preserving the destination; the published core has no lossless insertion command for that content. Ordinary load/save still preserves it. Cut deletes only after the clipboard accepts the serialized selection.

Serialize saves the full core document, including unavailable nodes and their raw payload/extension data, with current authored positions by default. Serialize(false) omits layout. SerializeLayout writes an optional versioned mass4.guinevere.graph-layout sidecar keyed to the asset; unknown layout fields are retained. SerializeViewState writes a separate versioned camera sidecar, excluding selection, focus, hover and connection previews. GraphDocumentView.Load(json, registry, layout, viewState, compatibility, rules) uses the core's registered serializers, renames and migrations, returning a new editor and diagnostics; errors return no partial view. Future sidecar versions and mismatched asset IDs are rejected. Loading a replacement document is an application operation that starts fresh history. Groups use the published core model; membership and nesting always remain authored document content. Collapse is saved in the layout, so topology-only assets omit it and a layout sidecar restores it.

GraphCanvas.Overlays holds IGraphOverlay layers drawn above elements, called from the same site in both passes with the frame's camera mapping. GraphFlowOverlay visualizes only ICompiledGraph.Observe snapshots. TryObserve evaluates and observes a compiled artifact on the thread pool, refusing overlap, and publishes atomically; drawing reads the build-pass snapshot. Active links carry moving pulses and observed outputs show formatted values; failures surface as Error. Compilation stays on the UI thread because the interpreter reads the live document. This accepted limit can be addressed by compiling an immutable document snapshot when a real graph demonstrates compile jank.

IGraphSemanticsSink extends IControlSemanticsSink with graph/group/node/port/edge roles, parent and connection relationships, names/types/errors/state descriptions, available actions, selection/focus, logical position/count, and virtualized state. Implement it alongside IAccessibilityCapability in a platform bridge and register that bridge normally. Plain control sinks receive stable scoped IDs, names, types/states/errors, transformed bounds, and visual state. Graph summaries include node/link/selection counts; ports describe direction, multiplicity and attached links; edges name both endpoints. NodeState supplies domain-owned observed state and is skipped for unavailable types. No off-screen layout controls are required.

Native adapters implement IGraphActionSource, registered as a platform capability or implemented by the semantics bridge. Queue GraphAction requests by canvas ID; item keys are logical descriptor keys, while TargetKey names the other port for Connect. Focus reveals virtualized elements. Selection, activation, connection, deletion, clipboard, select-all and undo/redo use the same navigation and real editor commands as keyboard/pointer input. Search/create actions invoke Navigation.SearchRequested; the application owns the registry palette. Disabled descriptors advertise no actions. Requests are read during rendering and executed once at the next build boundary. Call Canvas.ProcessInput(gui) before building any toolbar, inspector or popup whose structure depends on graph actions; Draw also drains pending input for canvas-only consumers. EditorActionRequested and EditorActions extend the generic canvas with application commands; GraphDocumentView binds its editor automatically.

Semantic events carry the canvas GraphId and announce focus/selection, connection success/cancellation, command completion, validation changes/failures and observed state changes. Set Validation for compiler findings; repeated identical findings are silent and cleared findings are announced. Use Execute for domain commands so their result reaches the same bridge. Native OS role mappings, screen-reader speech and action transport remain platform integration work; the editor contract is covered by headless adapter and keyboard tests.

RouteLink lets a domain adapter supply an explicit GraphConnector waypoint route for cycles and self-transitions. Its immutable polyline supplies the same drawing, hit testing, bounds and minimap geometry. The callback runs only when both endpoint types are available; it does not alter topology or domain semantics.

Groups are authored GraphGroup frames with core-owned membership and nesting. GroupSelection, RenameGroup, MoveSelectionToGroup, ReparentGroup and Ungroup use the real editor commands and history. Ungroup promotes members and children without deleting nodes. The model rejects nesting cycles. Group headers select and drag every descendant node once as one layout command; Enter on a focused group or its disclosure button toggles SetGroupCollapsed. Group bounds derive from their content and PSS padding/header geometry; empty frames use a default anchor.

Collapsed frames hide descendants and internal links. Crossing links attach to stable boundary ports that retain the original port IDs and model connections, so connecting or disconnecting them still uses actual editor validation. Expanding restores the authored node layout and any nested collapsed state. Group descriptors publish parent relationships, expanded/collapsed descriptions and activation actions. graph-group:selected, graph-group:collapsed and graph-group-header are ordinary PSS selectors; min-width, padding-left, gap and header height control frame geometry.

Copying a selected frame includes its descendant nodes, nested frames, internal links and collapse state. Paste remaps their identities through one reversible command. Unavailable/extended node or group content that cannot be inserted losslessly is rejected; ordinary save/load preserves it. Group and layout edits do not restart the playground's running dataflow/FSM instances.

Native accessibility acceptance is tracked in #226. The desktop hosts still require a native bridge and a recorded screen-reader walkthrough before the integration release tag; headless semantic tests do not satisfy that release gate.