Skip to content

quick-start.md

Latest commit

 

History

History
253 lines (180 loc) · 19.9 KB

quick-start.md

File metadata and controls

253 lines (180 loc) · 19.9 KB

AsterGraph Quick Start

This guide is the shortest path from a blank host to a running AsterGraph integration.

For first-time adopters, start on the default Avalonia path by default. Treat WPF only as adapter-2 portability validation on the same canonical route; it is not a second route or a parity promise. For the frozen support boundary and upgrade guidance toward v1.0.0, see Stabilization Support Matrix. If you are evaluating the public beta end to end, use Beta Evaluation Path as the hosted route ladder from first install to realistic hosted proof. For plugin trust-policy review and local evidence, keep Plugin Manifest and Trust Policy Contract v1 and Beta Support Bundle close to the defended hosted route.

30-Second / 5-Minute / 30-Minute Path

Time Path Stop when
30 seconds Run src/AsterGraph.Demo -- --scenario ai-pipeline or inspect the README scenario image. The SDK story is clear enough to choose a route, and proof mode can emit DEMO_SCENARIO_PRESETS_OK:True.
5 minutes Generate dotnet new astergraph-avalonia, run the starter, and validate ConsumerSample.Avalonia -- --proof --support-bundle <support-bundle-path>. You have FIVE_MINUTE_ONBOARDING_OK:True, ONBOARDING_CONFIGURATION_OK:True, AUTHORING_FLOW_HANDOFF_OK:True, EXPERIENCE_SCOPE_BOUNDARY_OK:True, AUTHORING_DEPTH_HANDOFF_OK:True, AUTHORING_DEPTH_SCOPE_BOUNDARY_OK:True, V058_MILESTONE_PROOF_OK:True, LARGE_GRAPH_UX_POLICY_OK:True, LARGE_GRAPH_UX_SCOPE_BOUNDARY_OK:True, LARGE_GRAPH_UX_PROOF_BASELINE_OK:True, VIEWPORT_LOD_POLICY_OK:True, SELECTED_HOVERED_ADORNER_SCOPE_OK:True, LARGE_GRAPH_BALANCED_UX_OK:True, VIEWPORT_LOD_SCOPE_BOUNDARY_OK:True, EDGE_INTERACTION_CACHE_OK:True, EDGE_DRAG_ROUTE_SIMPLIFICATION_OK:True, SELECTED_EDGE_FEEDBACK_OK:True, EDGE_RENDERING_SCOPE_BOUNDARY_OK:True, MINIMAP_LIGHTWEIGHT_PROJECTION_OK:True, INSPECTOR_NARROW_PROJECTION_OK:True, LARGE_GRAPH_PANEL_SCOPE_OK:True, PROJECTION_PERFORMANCE_EVIDENCE_OK:True, LARGE_GRAPH_UX_HANDOFF_OK:True, and V059_MILESTONE_PROOF_OK:True.
30 minutes Follow the package, route, parameter, plugin, and support-bundle sections below. You know whether your host should copy hosted UI, runtime-only, plugin, or retained migration guidance.

The fastest project-owned start is now the template route:

dotnet new install ./templates
dotnet new astergraph-avalonia -n MyGraphHost
dotnet new astergraph-plugin -n MyGraphPlugin --PluginId my.graph.plugin

1. Pick Your Starting Package

Host goal Start package Why
Hosted starter scaffold AsterGraph.Starter.Avalonia smallest end-to-end Avalonia scaffold; the first hosted hop in the cookbook
Native generated host dotnet new astergraph-avalonia cross-platform Avalonia desktop host owned by your project
Trusted plugin starter dotnet new astergraph-plugin smallest plugin-author project for in-process trusted extensions
Default Avalonia UI host AsterGraph.Avalonia main UI entry with the shipped shell and view factories
Runtime-only or custom UI host AsterGraph.Editor canonical session/runtime surface for custom UI or native shells
Contract-first integration AsterGraph.Abstractions stable identifiers, definitions, and provider contracts

Add AsterGraph.Core only when the host also needs direct GraphDocument, serialization, or compatibility APIs.

Copy this starter scaffold:

  • AsterGraphEditorFactory.Create(...)
  • AsterGraphAvaloniaViewFactory.Create(...)
  • AsterGraphEditorOptions
  • the document/catalog/editor/view composition flow

Replace in your host:

  • the top-level window and its title/size
  • the sample graph/catalog definitions as the host grows

Use AsterGraph.Starter.Avalonia as the starter recipe. Keep/copy AsterGraphEditorFactory.Create(...), AsterGraphAvaloniaViewFactory.Create(...), AsterGraphEditorOptions, and the document/catalog/editor/view composition flow. Replace the top-level window and its title/size, and replace the sample graph/catalog definitions as the host grows. Copy the host-owned seams, not the sample-owned presentation. The next hosted step is AsterGraph.HelloWorld.Avalonia. When you move to AsterGraph.ConsumerSample.Avalonia, keep action projection, trust workflow, and the selected-node parameter read/write seam host-owned.

Host-Owned Parameter And Metadata Copy Map

Copy from each bounded source for the part it owns:

  • Copy from AsterGraph.Starter.Avalonia: keep AsterGraphEditorFactory.Create(...), AsterGraphAvaloniaViewFactory.Create(...), AsterGraphEditorOptions, and the document/catalog/editor/view composition flow, then replace the top-level window, its title/size, and the sample graph/catalog definitions as the host grows.
  • Copy from AsterGraph.ConsumerSample.Avalonia: keep the action projection, trust workflow, selected-node parameter read/write seam, and snippet catalog insertion seam host-owned, but keep the sample-owned presentation, snippet ids, and proof labels local.
  • Copy from Host Integration: use the route matrix and canonical session/runtime choice to decide which host surface owns the seam.
  • Copy from Authoring Inspector Recipe: use the definition-driven metadata vocabulary (defaultValue, isAdvanced, helpText, placeholderText, constraints.IsReadOnly) for host-owned parameter and metadata work.

Consumer Sample proves the seam split; Authoring Inspector Recipe owns the metadata vocabulary.

2. Install From NuGet

The public beta packages are published to nuget.org, so the default dotnet restore flow plus --prerelease is enough.

# shipped Avalonia UI host
dotnet add package AsterGraph.Avalonia --prerelease

# runtime-only or custom UI host
dotnet add package AsterGraph.Editor --prerelease

# node definitions and provider contracts
dotnet add package AsterGraph.Abstractions --prerelease

AsterGraph.Demo is sample-only and is not part of the supported SDK boundary.

3. Fastest First Run

For the first hosted entry, run:

dotnet run --project tools/AsterGraph.Starter.Avalonia/AsterGraph.Starter.Avalonia.csproj --nologo

For a project-owned native Avalonia scaffold, run:

dotnet new install ./templates
dotnet new astergraph-avalonia -n MyGraphHost
dotnet run --project MyGraphHost/MyGraphHost.csproj

For the smallest possible runtime-only sample, run:

dotnet run --project tools/AsterGraph.HelloWorld/AsterGraph.HelloWorld.csproj --nologo

For the smallest hosted-UI sample, run:

dotnet run --project tools/AsterGraph.HelloWorld.Avalonia/AsterGraph.HelloWorld.Avalonia.csproj --nologo

For one realistic hosted integration with a host-owned action rail, the selected-node parameter read/write seam, and one trusted plugin, run:

dotnet run --project tools/AsterGraph.ConsumerSample.Avalonia/AsterGraph.ConsumerSample.Avalonia.csproj --nologo

Run AsterGraph.ConsumerSample.Avalonia -- --proof first for proof handoff; use HostSample only after that as the post-ladder proof harness.

For plugin-capable evaluators, the defended hosted trust hop is AsterGraph.ConsumerSample.Avalonia. Read Plugin Manifest and Trust Policy Contract v1 and Plugin And Custom Node Recipe before treating the route as complete.

For plugin authors, generate and validate the starter plugin:

dotnet new astergraph-plugin -n MyGraphPlugin --PluginId my.graph.plugin
dotnet build MyGraphPlugin/MyGraphPlugin.csproj
dotnet run --project tools/AsterGraph.PluginTool -- validate MyGraphPlugin/bin/Debug/net8.0/MyGraphPlugin.dll

Use Starter.Avalonia when you want the first hosted entry and the smallest end-to-end Avalonia scaffold. Use HelloWorld when you want the simplest runtime-only starting point. Use HelloWorld.Avalonia when you want the smallest shipped-shell sample after the starter scaffold. Use ConsumerSample.Avalonia when you want one realistic host before jumping to Demo. Use HostSample only when you want a proof harness for canonical route validation, not as the onboarding step.

The hosted route ladder is Starter.Avalonia -> HelloWorld.Avalonia -> ConsumerSample.Avalonia.

The sample README is tools/AsterGraph.ConsumerSample.Avalonia/README.md.

Five-Minute Hosted Path

Use this path when you want a copyable Avalonia host rather than a full showcase:

  1. Install AsterGraph.Avalonia --prerelease, or run tools/AsterGraph.Starter.Avalonia from source.
  2. Copy the starter composition through AsterGraphHostBuilder.Create().UseDocument(document).UseCatalog(catalog).UseDefaultCompatibility().BuildAvaloniaView() when defaults are enough, or drop down to AsterGraphEditorFactory.Create(...), AsterGraphAvaloniaViewFactory.Create(...), AsterGraphEditorOptions, and the document/catalog/editor/view flow when each service must be explicit.
  3. Add the first custom node definition by replacing the starter sample definition with your own NodeDefinition id, title, ports, and parameter definitions.
  4. Run tools/AsterGraph.ConsumerSample.Avalonia and use the hosted action rail to exercise graph save/load, selected-node parameter editing, and the trusted plugin path.
  5. Run AsterGraph.ConsumerSample.Avalonia -- --proof --support-bundle <support-bundle-path> and expect CONSUMER_SAMPLE_SCENARIO_GRAPH_OK:True, CONSUMER_SAMPLE_HOST_OWNED_ACTIONS_OK:True, CONSUMER_SAMPLE_SUPPORT_BUNDLE_READY_OK:True, GRAPH_SNIPPET_CATALOG_OK:True, GRAPH_SNIPPET_INSERT_OK:True, FRAGMENT_LIBRARY_SEARCH_OK:True, FRAGMENT_LIBRARY_PREVIEW_OK:True, FRAGMENT_LIBRARY_RECENTS_FAVORITES_OK:True, FRAGMENT_LIBRARY_SCOPE_BOUNDARY_OK:True, FIVE_MINUTE_ONBOARDING_OK:True, ONBOARDING_CONFIGURATION_OK:True, AUTHORING_FLOW_PROOF_OK:True, AUTHORING_FLOW_HANDOFF_OK:True, AUTHORING_FLOW_SCOPE_BOUNDARY_OK:True, EXPERIENCE_POLISH_HANDOFF_OK:True, FEATURE_ENHANCEMENT_PROOF_OK:True, EXPERIENCE_SCOPE_BOUNDARY_OK:True, AUTHORING_DEPTH_HANDOFF_OK:True, AUTHORING_DEPTH_SCOPE_BOUNDARY_OK:True, V058_MILESTONE_PROOF_OK:True, LARGE_GRAPH_UX_POLICY_OK:True, LARGE_GRAPH_UX_SCOPE_BOUNDARY_OK:True, LARGE_GRAPH_UX_PROOF_BASELINE_OK:True, VIEWPORT_LOD_POLICY_OK:True, SELECTED_HOVERED_ADORNER_SCOPE_OK:True, LARGE_GRAPH_BALANCED_UX_OK:True, VIEWPORT_LOD_SCOPE_BOUNDARY_OK:True, EDGE_INTERACTION_CACHE_OK:True, EDGE_DRAG_ROUTE_SIMPLIFICATION_OK:True, SELECTED_EDGE_FEEDBACK_OK:True, EDGE_RENDERING_SCOPE_BOUNDARY_OK:True, MINIMAP_LIGHTWEIGHT_PROJECTION_OK:True, INSPECTOR_NARROW_PROJECTION_OK:True, LARGE_GRAPH_PANEL_SCOPE_OK:True, PROJECTION_PERFORMANCE_EVIDENCE_OK:True, LARGE_GRAPH_UX_HANDOFF_OK:True, and V059_MILESTONE_PROOF_OK:True.

Runtime feedback proof remains host-owned: ConsumerSample should also keep RUNTIME_DEBUG_PANEL_INTERACTION_OK:True, RUNTIME_LOG_LOCATE_OK:True, and RUNTIME_LOG_EXPORT_OK:True, while Demo keeps AI_PIPELINE_MOCK_RUNNER_POLISH_OK:True, AI_PIPELINE_PAYLOAD_PREVIEW_OK:True, and AI_PIPELINE_ERROR_DEBUG_EVIDENCE_OK:True. These are not execution-engine, workflow scripting UI, marketplace, sandbox, WPF parity, or GA claims.

Graph search proof also stays hosted and snapshot-driven: expect GRAPH_SEARCH_LOCATE_OK:True, GRAPH_SEARCH_SCOPE_FILTER_OK:True, and GRAPH_SEARCH_VIEWPORT_FOCUS_OK:True without a background graph index service or command macro engine. Command palette proof stays on the same shared command/session route: expect COMMAND_PALETTE_GROUPING_OK:True, COMMAND_PALETTE_DISABLED_REASON_OK:True, COMMAND_PALETTE_RECENT_ACTIONS_OK:True, COMMAND_PROJECTION_UNIFIED_OK:True, COMMAND_PALETTE_OK:True, TOOLBAR_DESCRIPTOR_OK:True, CONTEXT_MENU_DESCRIPTOR_OK:True, and COMMAND_DISABLED_REASON_OK:True without adding macros or scripting. Workbench discoverability proof closes v0.63 on hosted layout/discovery/recents-favorites evidence: expect WORKBENCH_DISCOVERABILITY_HANDOFF_OK:True, WORKBENCH_DISCOVERABILITY_SCOPE_BOUNDARY_OK:True, and V063_MILESTONE_PROOF_OK:True without adding a runtime route, macro/query system, remote sync, marketplace state, WPF parity, or GA claim. Navigation proof stays host-owned on top of existing selection, scope, and viewport commands: expect NAVIGATION_HISTORY_OK:True, SCOPE_BREADCRUMB_NAVIGATION_OK:True, FOCUS_RESTORE_OK:True, NAVIGATION_PRODUCTIVITY_PROOF_OK:True, NAVIGATION_PRODUCTIVITY_HANDOFF_OK:True, and NAVIGATION_SCOPE_BOUNDARY_OK:True without a new runtime navigation API.

Template smoke in the release lane validates that astergraph-avalonia and astergraph-plugin generate buildable net8.0 projects and that the generated plugin passes AsterGraph.PluginTool validate.

Cross-platform packaging proof stays in CI rather than in a copied host: Windows validates net8.0, net9.0, and net10.0; Linux and macOS run the all-framework lane; release validation packs the public packages, runs template smoke, and checks the packed HostSample route including HOST_SAMPLE_NET10_OK:True.

Copy from Starter.Avalonia for composition, HelloWorld for runtime-only shape, HelloWorld.Avalonia for the smallest hosted UI, ConsumerSample.Avalonia for realistic host-owned actions/parameters/plugins/support proof, and Demo only when you need the full capability showcase.

4. Canonical Adoption Routes

If your host needs Start here First sample
Hosted starter scaffold AsterGraphEditorFactory.Create(...) + AsterGraphAvaloniaViewFactory.Create(...) tools/AsterGraph.Starter.Avalonia
Runtime-only or custom UI AsterGraphEditorFactory.CreateSession(...) tools/AsterGraph.HelloWorld
Shipped Avalonia UI AsterGraphEditorFactory.Create(...) + AsterGraphAvaloniaViewFactory.Create(...) tools/AsterGraph.HelloWorld.Avalonia
Plugin trust/discovery AsterGraphEditorFactory.DiscoverPluginCandidates(...) + AsterGraphEditorOptions.PluginTrustPolicy tools/AsterGraph.ConsumerSample.Avalonia
Automation IGraphEditorSession.Automation.Execute(...) Host Integration
Retained compatibility bridge new GraphEditorViewModel(...) + new GraphEditorView { Editor = editor } Host Integration

For new work, start with the runtime/session route or the shipped Avalonia route. Treat the retained route as migration-only. Choose retained only when you are migrating an existing host in batches. Use the retained recipe only as a copyable migration aid for an existing host. If you need that bridge, use Retained Migration Recipe; otherwise start with CreateSession(...) or Create(...) + AsterGraphAvaloniaViewFactory.Create(...). If you are choosing retained, stop at that recipe instead of stitching together multiple docs; it is the single bounded retained recipe set for existing GraphEditorViewModel / GraphEditorView hosts. New adopters should start with AsterGraph.Starter.Avalonia unless they are intentionally building a custom UI host from day one. If the host owns its UI, the runtime/session route is the canonical native path; Editor.Session still owns host actions, diagnostics, automation, and proof logic. Quick Start remains Avalonia-first today. The current public beta line validates WPF as adapter 2 on the same canonical route; see Adapter Capability Matrix for that contract instead of treating it as a second beginner route or a parity promise.

5. Hosted Builder Cookbook

Use the thin builder for the common hosted route:

using AsterGraph.Avalonia.Hosting;

var view = AsterGraphHostBuilder
    .Create()
    .UseDocument(document)
    .UseCatalog(catalog)
    .UseDefaultCompatibility()
    .BuildAvaloniaView();

Drop down to the canonical factories when you need explicit service wiring:

using AsterGraph.Abstractions.Catalog;
using AsterGraph.Avalonia.Hosting;
using AsterGraph.Core.Compatibility;
using AsterGraph.Core.Models;
using AsterGraph.Editor.Hosting;

INodeCatalog catalog = CreateCatalog();
var document = CreateDocument();

var editor = AsterGraphEditorFactory.Create(new AsterGraphEditorOptions
{
    Document = document,
    NodeCatalog = catalog,
    CompatibilityService = new DefaultPortCompatibilityService(),
});

var view = AsterGraphAvaloniaViewFactory.Create(new AsterGraphAvaloniaViewOptions
{
    Editor = editor,
});

AsterGraphHostBuilder is a thin hosted helper over the same editor/session and Avalonia view factories. It is not a second runtime model.

Use builder pass-throughs such as UseBehaviorOptions(...), UseContextMenuAugmentor(...), UseNodePresentationProvider(...), UseToolProvider(...), UseRuntimeOverlayProvider(...), and UseLayoutProvider(...) when the common hosted route is still enough. UseNodePresentationProvider(...) forwards AsterGraphEditorOptions.NodePresentationProvider for editor-runtime node presentation state; Avalonia visual replacement stays on AsterGraphPresentationOptions.

6. Plugin Trust Boundary

Plugin loading is currently in-process. Hosts can discover candidates, apply an allow/block trust policy, and inspect load results. AsterGraph does not provide sandboxing or untrusted-code isolation.

7. Need More Than The First Run?

8. Maintainer And Source-Validation Paths

If you are validating the repository itself instead of consuming the published packages: