Known Limitations
What Beep.Skia does not do, stated plainly, with the workaround where one exists
Every framework has edges. This page lists them so you can plan around them instead of discovering them in production. It is maintained alongside the feature roadmap.
Table of Contents
Platforms and deployment
| Limitation | Detail | Workaround |
|---|---|---|
| Windows hosts require .NET 10 | SkiaSharp's 4.x view packages ship no net8.0 assets, so the WinForms and WPF hosts target net10.0-windows10.0.19041.0. |
Use a net8.0/net9.0 console or service with offscreen rendering if you cannot move to .NET 10 on Windows. |
| The MAUI head is not CI-verified | GitHub-hosted Windows runners cannot build net10.0-ios/maccatalyst; the project is excluded from Beep.Skia.CI.slnf. |
Build the MAUI head locally with the workload installed. Treat it as preview quality until it is in CI. |
| Avalonia renders offscreen | The Avalonia control renders into an Avalonia bitmap rather than through Avalonia.Skia, which keeps SkiaSharp at 4.150.1 across the solution. |
None needed for correctness; expect a copy per frame. If Avalonia adopts SkiaSharp 4.x assets, the surface can be swapped for a leased canvas. |
| No mobile or browser runtime verification | Blazor (WebAssembly) and MAUI compile, but the test suite and consumer validation run on Windows desktop only. | Test your target in your own pipeline; the core libraries are platform-neutral. |
| Private feed required | The core depends on TheTechIdea.Beep.* packages that are not on nuget.org at the required versions. |
Configure the feed (see Troubleshooting). |
Architecture and threading
| Limitation | Detail | Workaround |
|---|---|---|
DrawingManager is not thread-safe |
It owns mutable component and connection lists and is designed for single-threaded UI use. | Mutate only from the UI thread (marshalling input and background results back). The automation service, credential vault and collaboration service are thread-safe. |
| No multi-user live editing | Collaboration covers roles, comments, presence and an audit trail, but not operational-transform/CRDT merging of concurrent edits to the same component. | Use the comment/review workflow; serialized documents are the unit of merge. |
| Undo is per-manager and in-memory | HistoryManager keeps a bounded stack (default depth 100); it is not persisted and does not span documents. |
Persist checkpoints through ToDto() if you need longer history. |
| Text rendering is Latin-centric | Text goes through TypefaceCache and system typefaces; complex script shaping (HarfBuzz-style) is not part of the render path. |
Choose typefaces that cover your script; text is drawn with the host's font stack. |
| Exports are raster/vector snapshots | PNG, SVG and PDF export the drawing, not a semantic model for other tools (except where a family provides one: BPMN, XMI, DDL). | Use the family exporters for interchange; the diagram DTO JSON is the lossless format. |
Feature boundaries
| Limitation | Detail | Workaround |
|---|---|---|
| Automation nodes are the executable surface | The workflow engine executes AutomationNode-derived components; a diagram of plain shape nodes runs as an empty flow. |
Use the automation node types (or wrap your logic in one); see Automation Nodes. |
| Trigger scheduling is in-process | Schedule and file-watch triggers run inside the host process; missed windows while the app is closed are not replayed. | Use the server SKU with an external scheduler for durable scheduling. |
| Credential vault is in-memory plus encrypted export | There is no OS keychain integration or central secret store; the vault encrypts exports with a passphrase. | Load the passphrase from your platform's secret store at startup. |
| Extension packages are trusted code | Installation validates the archive, versions and dependencies, but an extension still runs with your process's privileges. | Install only from sources you trust; see SECURITY.md. |
| Assisted generation is rule-based by default | The bundled assistant parses a small DSL and outlines; it is not an LLM. IDiagramAssistant is the seam for a model-backed implementation. |
Implement IDiagramAssistant to plug in your own provider. |
| No built-in persistence store | The framework serializes to JSON/streams; it does not provide a database, document store or autosave. | Persist ToDto() output wherever your application stores data. |
Tooling and process
| Limitation | Detail | Workaround |
|---|---|---|
| Pre-1.0 API surface | The package version is 1.0.0-alpha; public APIs can still change between releases. |
Pin package versions; watch CHANGELOG.md and the roadmap. |
| XML docs are 97% complete | ~3% of public members have no XML summary; a handful of generated reference entries are name-derived. | The API reference and source are the authority; open an issue for a specific member. |
| Generated docs can drift | The reference pages, images and search index are generated from source; they are only as current as the last regeneration. | Regenerate with the scripts listed in docs/README.md when you change public APIs. |
| No localization | Documentation and built-in component strings are English-only. | Component labels are yours to set; documentation translation would need a fork. |
Deliberately out of scope
- A visual designer for the framework itself — the WinForms sample is the editor; there is no separate IDE.
- A diagram markup language — diagrams are C# objects or JSON; the assisted-generation DSL is an input aid, not a document format.
- Cloud rendering or a hosted service — rendering is in-process; the server SKU executes workflows, it does not render for clients.
- Real-time multiplayer cursors — presence and comments exist; live co-editing does not.
Found something else?
If a limitation is missing from this page, that is itself a documentation bug: report it via Getting Help.