AsterGraph is a modular node-graph editor toolkit for .NET. It gives hosts a reusable editor runtime, a canonical session/runtime route for custom UI or native shells, a shipped Avalonia hosted-UI path, and explicit seams for plugins, automation, localization, diagnostics, and presentation overrides.
- current installable package version:
0.11.0-beta - matching public prerelease tag for this package line:
v0.11.0-beta - historical legacy repository milestone tag series:
v1.x-style pre-launch checkpoints (historical pre-launch checkpoints, not the NuGet version) - published packages target
net8.0andnet9.0 - packed
HostSamplealso proves downstream.NET 10consumption during the release gate - public prerelease tags must match the package version exactly for this package line, for example
v0.11.0-beta - package version versus historical repository-tag guidance: Versioning
- frozen support boundary and
v1.0.0upgrade guidance: Stabilization Support Matrix - evaluator ladder from first install to realistic hosted proof: Beta Evaluation Path
- current scope, non-goals, and known limitations: Alpha Status
| I want to... | Start here | Why |
|---|---|---|
| get the first hosted entry | tools/AsterGraph.Starter.Avalonia |
smallest end-to-end Avalonia scaffold; the first hosted hop in the cookbook |
| get the fastest runtime-only first run | tools/AsterGraph.HelloWorld |
smallest runtime-only sample; one canonical route for custom UI or native shells |
| embed the shipped Avalonia UI | tools/AsterGraph.HelloWorld.Avalonia |
smallest stock hosted-UI sample after the starter scaffold |
| try a realistic hosted integration | Consumer Sample | medium sample on the same canonical route, with host-owned actions, parameter editing, and one trusted plugin |
| integrate into an existing host | Host Integration | route matrix, package boundary, migration guidance |
| inspect the full surface visually | Demo Guide | showcase host for plugins, automation, localization, and standalone surfaces |
| validate packed consumption or maintain releases | Contributing and Public Launch Checklist | proof lanes, CI, and release flow |
The hosted route ladder is Starter.Avalonia -> HelloWorld.Avalonia -> ConsumerSample.Avalonia.
Most new hosts start with one of these commands:
# shipped Avalonia UI host
dotnet add package AsterGraph.Avalonia --prerelease
# runtime-only or custom UI host
dotnet add package AsterGraph.Editor --prerelease
# node definitions, identifiers, and provider contracts
dotnet add package AsterGraph.Abstractions --prereleaseAdd AsterGraph.Core only when the host also needs direct GraphDocument, serialization, or compatibility APIs.
| Route | Use when | First API | First sample |
|---|---|---|---|
| Hosted starter scaffold | the host wants the smallest end-to-end Avalonia entry before a fuller app | AsterGraphEditorFactory.Create(...) + AsterGraphAvaloniaViewFactory.Create(...) |
AsterGraph.Starter.Avalonia |
| Runtime-only or custom UI | the host owns its own UI and wants the canonical runtime boundary | AsterGraphEditorFactory.CreateSession(...) + IGraphEditorSession |
AsterGraph.HelloWorld |
| Shipped Avalonia UI | the host wants the stock editor shell or stock standalone Avalonia surfaces | AsterGraphEditorFactory.Create(...) + AsterGraphAvaloniaViewFactory.Create(...) |
AsterGraph.HelloWorld.Avalonia |
| Retained migration | the host is moving off older MVVM-shaped entry points in planned batches | new GraphEditorViewModel(...) + new GraphEditorView { Editor = editor } |
Host Integration |
For new runtime-facing work, anchor on the first route. The Avalonia route is the supported hosted adapter path today, while the retained route stays migration-only. The current public beta keeps WPF as adapter 2 and publishes Avalonia/WPF gaps through the Adapter Capability Matrix instead of adding adapter-specific runtime APIs or claiming parity.
tools/AsterGraph.Starter.Avalonia= first hosted scaffold; the smallest end-to-end Avalonia entrytools/AsterGraph.HelloWorld= first-run sample for the runtime-only pathtools/AsterGraph.HelloWorld.Avalonia= smallest stock hosted-UI sample after the starter scaffoldtools/AsterGraph.ConsumerSample.Avalonia= realistic hosted-UI consumer sample betweenHelloWorld.AvaloniaandDemotools/AsterGraph.HostSample= proof harness for runtime-only and hosted-UI validation, not the onboarding steptools/AsterGraph.PackageSmoke= packed-package prooftools/AsterGraph.ScaleSmoke= public larger-graph baseline plus history/state proofsrc/AsterGraph.Demo= showcase host; menu labels follow the current UI language
These are the current public capability modules. They sit on top of the canonical session/runtime route; hosted Avalonia composition reuses the same seams instead of defining a second capability model.
| Module | Canonical seam | First proof/sample anchor |
|---|---|---|
Selection |
IGraphEditorSession.Commands.SetSelection(...) + Queries.GetSelectionSnapshot() |
tools/AsterGraph.ScaleSmoke, tools/AsterGraph.HelloWorld |
History |
IGraphEditorSession.Commands.Undo() / Redo() plus the save/dirty contract |
tools/AsterGraph.ScaleSmoke, State Contracts |
Clipboard |
TryCopySelectionAsync() / TryPasteSelectionAsync() through host clipboard services |
tools/AsterGraph.HostSample |
Shortcut Policy |
AsterGraphCommandShortcutPolicy on the hosted Avalonia route |
tools/AsterGraph.PackageSmoke, tools/AsterGraph.HelloWorld.Avalonia |
Layout |
session-backed align/distribute commands | src/AsterGraph.Demo |
MiniMap |
session snapshots projected into AsterGraphMiniMapViewFactory.Create(...) |
src/AsterGraph.Demo |
Stencil |
session stencil queries plus the shipped Avalonia insertion surface | src/AsterGraph.Demo |
Fragment Library |
session fragment/template commands backed by fragment workspace/library services | src/AsterGraph.Demo |
Export |
IGraphSceneSvgExportService + TryExportSceneAsSvg() |
tools/AsterGraph.HostSample |
Baseline Edge Authoring |
StartConnection(...), CompleteConnection(...), reconnect/disconnect commands, and the pending-connection snapshot |
tools/AsterGraph.HostSample, tools/AsterGraph.ScaleSmoke |
Node Surface Authoring |
GetNodeSurfaceSnapshots(), TrySetNodeSize(...), and parameter edits through the shared session command path |
src/AsterGraph.Demo, Advanced Editing Guide |
Hierarchy Semantics |
GetHierarchyStateSnapshot(), GetNodeGroups(), GetNodeGroupSnapshots(), and group collapse/move/resize/membership commands |
src/AsterGraph.Demo, Advanced Editing Guide |
Composite Scope Authoring |
wrap/promote/expose/unexpose/scope-navigation commands plus scope/composite queries | src/AsterGraph.Demo, Advanced Editing Guide |
Edge Semantics |
connection note, reconnect, and disconnect commands on the canonical session route | src/AsterGraph.Demo, Advanced Editing Guide |
Edge Geometry Tooling |
GetConnectionGeometrySnapshots() plus route-vertex insert/move/remove commands |
src/AsterGraph.Demo, Advanced Editing Guide |
Only these four libraries are published as the supported SDK surface:
| Package | Reference when | Notes |
|---|---|---|
AsterGraph.Abstractions |
defining nodes, identifiers, catalogs, style tokens, or provider contracts | stable contract layer with no UI dependency |
AsterGraph.Core |
working directly with GraphDocument, serialization, or compatibility services |
model and persistence layer |
AsterGraph.Editor |
building or extending an editor runtime or runtime session | canonical host-facing runtime package |
AsterGraph.Avalonia |
embedding the shipped Avalonia UI | default UI entry package for hosts |
AsterGraph.Demo is sample-only and is not part of the supported package boundary.
Current capabilities:
- draggable, selectable graph nodes with marquee selection and multi-selection
- zoom, pan, mini map, and pending-connection preview
- save/load, undo/redo, copy/paste, fragment import/export, and SVG scene export
- batch alignment, distribution, and shared-parameter editing for compatible selections
- definition-driven inspector metadata with grouped parameters, shipped list/text/number/bool/enum editors, and validation feedback
- tiered node surfaces, fixed group frames, hierarchy snapshots, scoped composites, connection notes, and routed edge geometry editing
- compile-time node-definition registration and runtime plugin registration
- host-governed plugin trust policy, local candidate discovery, and load-state inspection
- descriptor-first automation through
IGraphEditorSession.Automation - runtime diagnostics, inspection snapshots, and replaceable host services
Current non-goals:
- algorithm execution engine
- arbitrary host-agnostic property editor framework beyond the shipped definition-driven inspector
- plugin marketplace or remote install/update workflows
- plugin unload lifecycle
- process sandboxing or untrusted-code isolation guarantees
- dedicated scripting language or workflow-designer UI for automation authoring
Plugin loading is in-process. AsterGraph currently gives hosts:
- allow/block trust policy through
PluginTrustPolicy - local candidate discovery before activation
- runtime inspection of trusted, loaded, and blocked outcomes
It does not provide sandboxing or untrusted-code isolation. For public prerelease hosts, prefer fixed plugin directories, explicit allowlists, and your own signature or hash validation policy.
Consumer-facing guides:
- Versioning
- Quick Start
- Stabilization Support Matrix
- Consumer Sample
- Host Integration
- Adapter Capability Matrix
- Advanced Editing Guide
- ScaleSmoke Baseline
- Authoring Inspector Recipe
- Adoption Feedback Loop
- Plugin And Custom Node Recipe
- Retained-To-Session Migration Recipe
- State Contracts
- Extension Contracts
- Alpha Status
- Project Status
- Demo Guide
Chinese equivalents live under docs/zh-CN/.
- contributor workflow: CONTRIBUTING.md
- code of conduct: CODE_OF_CONDUCT.md
- security reporting: SECURITY.md
- public launch and release sign-off: Public Launch Checklist