Arclyra.PluginSdk 1.0.3

Arclyra Plugin Developer Guide

Arclyra plugins extend Arclyra Writing Studio with optional commands, menu items, settings pages, workspace panels, story UI integrations, Smart Builder tools, AI-provider configuration helpers, and host-mediated data workflows. Plugins are distributed as .arcplugin packages, installed into the user's writable app-data area, discovered at runtime, and initialized through Arclyra.PluginSdk.

This repository is the maintained plugin-authoring reference. The SDK package README is intentionally short and links here for the full documentation. For working examples, build and inspect the sample plugins under SamplePlugins/.

First setup steps

1. Install the .NET 8 SDK. Use a Windows development environment when the plugin contributes WPF UI.

2. Create a .NET 8 class library. Use net8.0-windows and enable WPF when the plugin contributes settings pages, panels, custom editors, or other WPF UI.

3. Install Arclyra.PluginSdk from NuGet. Add the SDK package from NuGet using either the .NET CLI or Package Manager Console:

   dotnet add package Arclyra.PluginSdk
   

   Install-Package Arclyra.PluginSdk
   

   Do not copy Arclyra.PluginSdk.dll into the final package; Arclyra supplies the SDK assembly at runtime so host and plugin use the same contract types.

4. Implement IArclyraPlugin. Keep Id stable and make it match plugin.json.

5. Declare a plugin.json manifest. Include entry assembly/type, version, host compatibility, and the least set of capabilities your plugin needs.

6. Build and stage files under a plugin/ folder. Include plugin/plugin.json, your entry DLL, non-host managed dependencies, and required assets.

7. Zip the staging folder and rename it to .arcplugin. The archive root must contain the plugin folder. It may also contain root-level plugin.package.json signature metadata.

8. Install in Arclyra. Open Plugins, choose Install Plugin, select the .arcplugin, and let Arclyra validate, install, and reload plugins.

9. Update by installing a newer package. Keep the same plugin id; use an increasing version value.

Minimal project file for a WPF-capable plugin:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0-windows</TargetFramework>
    <UseWPF>true</UseWPF>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Arclyra.PluginSdk" Version="1.0.0" PrivateAssets="all" ExcludeAssets="runtime" />
  </ItemGroup>
</Project>

Minimal entry point:

using Arclyra.PluginSdk;

namespace Example.WordTools;

public sealed class WordToolsPlugin : IArclyraPlugin
{
    public string Id => "com.example.arclyra.wordtools";

    public string Name => "Example Word Tools";

    public Task InitializeAsync(IPluginContext context, CancellationToken cancellationToken = default)
    {
        context.Logger.LogInformation("Example Word Tools initialized.");

        context.CommandRegistry.RegisterCommand(new PluginCommandRegistration(
            "com.example.arclyra.wordtools.sayHello",
            "Say Hello",
            _ =>
            {
                context.Logger.LogInformation("Hello from Example Word Tools.");
                return Task.CompletedTask;
            },
            "Writes a test message to the plugin log."));

        context.UiRegistry.RegisterMenuItem(new PluginMenuItemRegistration(
            "Tools/Plugins",
            "Example Word Tools",
            "com.example.arclyra.wordtools.sayHello"));

        return Task.CompletedTask;
    }

    public Task ShutdownAsync(CancellationToken cancellationToken = default) => Task.CompletedTask;
}

Minimal manifest:

{
  "id": "com.example.arclyra.wordtools",
  "name": "Example Word Tools",
  "version": "1.0.0",
  "entryAssembly": "Example.WordTools.dll",
  "entryType": "Example.WordTools.WordToolsPlugin",
  "minHostVersion": "1.0.0",
  "description": "Adds example word-count utilities to Arclyra.",
  "author": "Example Studio",
  "website": "https://example.com/arclyra-wordtools",
  "capabilities": []
}

Build a sample plugin from this repository with:

dotnet build SamplePlugins/Arclyra.PluginTemplate/Arclyra.PluginTemplate.csproj

Documentation map

Read these pages for the API details that were split out of this root guide:

• Terminology
• Capabilities
• Story data API
• Prompt context API
• Smart Builder API
• AI generation API
• UI extension API
• Host services API
• Events API
• Lifecycle events
• Packaging
• Plugin signing tool

Runtime and lifecycle model

• Plugins are managed .NET assemblies loaded in-process into collectible plugin load contexts.
• Arclyra creates the plugin type named by entryType, calls InitializeAsync(IPluginContext, CancellationToken), and later calls ShutdownAsync(CancellationToken) before unload, reload, uninstall, or replacement.
• Initialize quickly. Register commands/UI/services, then return. Move long-running work to cancellable plugin-owned tasks.
• Release long-lived resources in ShutdownAsync: event subscriptions, timers, background tasks, cancellation sources, WPF controls, delegates, static references, and unmanaged resources.
• Unload is best-effort. Any remaining strong reference to plugin-defined types can keep the assembly loaded until references are cleared or the process exits.

Install, data, and package locations

Arclyra stores plugins in writable application data rather than under the app install directory.

Each plugin is installed in a safe directory name derived from its manifest id, such as %LocalAppData%\Arclyra\Plugins\com.example.arclyra.wordtools. Plugin data should use a matching folder under PluginData.

Do not write plugins into Program Files, the executable folder, the MSIX package install directory, or AppContext.BaseDirectory. These locations may be read-only, replaced by updates, or unavailable for packaged apps.

.arcplugin package format and validation

A .arcplugin is a ZIP archive. The archive root must contain:

• plugin/plugin.json;
• the plugin entry assembly named by entryAssembly;
• copy-local managed dependencies not supplied by Arclyra;
• assets and content files required at runtime;
• optionally, plugin.package.json at the archive root for package signature metadata.

Arclyra validates packages before installation. Packages are rejected when they:

• exceed 100 MB compressed;
• exceed 250 MB after extraction;
• contain more than 2,000 files;
• contain duplicate, absolute, invalid, traversal, or symbolic-link entries;
• include root entries other than plugin/ and optional plugin.package.json;
• put plugin.json anywhere except plugin/plugin.json;
• declare invalid entry assembly/type paths;
• request reserved capabilities that are not accepted in production manifests.

See Packaging for complete packaging, validation, and distribution details.

Manifest reference

plugin.json is a UTF-8 JSON object.

Legacy aliases may be accepted for older packages (assembly, entryPoint, and minimumArclyraVersion), but new plugins should use entryAssembly, entryType, and minHostVersion.

Capabilities and security

Capabilities are a host-facing declaration and a service gate for Arclyra SDK APIs. They help users and the host understand intended access, but they are not an operating-system sandbox. Follow least privilege, explain why each capability is needed, and avoid surprising background behavior.

The stable capability list, reserved capabilities, and guidance for least-privilege manifests live in Capabilities.

Plugin signatures

Arclyra packages may include root-level plugin.package.json signature metadata for the contents of the plugin/ folder. Signing is intended to let Arclyra associate a package with a known developer identity and detect package tampering.

If you wish to sign your plugins, contact Arclyra at developers@arclyra.app. We will provide the current signing requirements and developer onboarding details. Do not invent your own signature metadata format for public distribution.

For signing-tool usage, see Plugin signing tool.

Native dependencies and Store/MSIX considerations

Managed dependencies can usually live beside the plugin DLL. Native DLLs require extra caution:

• declare nativeDependencies in the manifest;
• match Arclyra's process architecture;
• test classic and MSIX/Store builds early;
• account for Windows packaged-app policy and code-integrity behavior;
• document prerequisites such as VC++ runtime components;
• prefer pure managed dependencies for Store-compatible plugins when possible.

Compatibility and versioning guidance

• Keep plugin ids stable forever. Changing id makes Arclyra treat the package as a different plugin.
• Use semantic-ish System.Version values such as 1.2.3.
• Set minHostVersion when you depend on newer SDK APIs or host behavior.
• Keep plugin-owned configuration ids stable so updates modify existing AI providers instead of adding duplicates.
• Treat host DTOs as snapshots. Re-read data when acting on stale UI or event context.
• Prefer additive changes to your own plugin data files to keep user data upgradeable.

Developer checklist before distribution

• Manifest id, entry assembly, entry type, version, and minimum host version are correct.
• IArclyraPlugin.Id matches plugin.json id.
• The package does not include Arclyra.PluginSdk.dll.
• Capabilities are minimal and documented.
• Startup does not block the UI thread.
• Shutdown disposes subscriptions, background work, timers, and unmanaged resources.
• Package installs cleanly from the Plugins screen.
• Reload/uninstall/reinstall flows work.
• Plugin data is written only to a user-writable plugin-specific location.
• Browser automation scripts, network behavior, and native dependencies are disclosed to users.
• If signing is desired, you have contacted developers@arclyra.app for signing requirements.

Validation command

For documentation-only changes, build the public SDK to catch signature drift that would make examples stale:

dotnet build src/Arclyra.PluginSdk/Arclyra.PluginSdk.csproj