rework plugin and app settings

Author: foxnne

.github/workflows/sdk-tag.yml

@@ -2,27 +2,33 @@ name: SDK tag
 
 # Auto-pins the plugin ABI contract: on every push to main, if src/sdk/sdk_version.zig's
 # `sdk_version` doesn't already have a matching `sdk-v<major>.<minor>.<patch>` tag, create and
-# push one at this commit. This is the pin point third-party plugins' build.zig.zon `fizzy`
-# dependency uses (docs/PLUGINS.md §2.3) instead of an arbitrary commit SHA.
+# push one at this commit. Then pack the plugin-facing `sdk/` package (plus vendored
+# `src/core` + `src/sdk`) into `fizzy-sdk-v*.tar.gz` and publish it as a GitHub release asset
+# on that tag — the URL third-party plugins pin (docs/PLUGINS.md §2.3). The git archive of the
+# monorepo is *not* a valid plugin pin: its root zon owns Velopack.
 #
 # `sdk-v*` is a separate namespace from the app's `v*` release tags (release.yml triggers on
 # `tags: ["v*"]`, a glob on the ref's start — `sdk-v...` doesn't start with `v`, so this can
-# never fire the app build/package pipeline). No build/package step here: just a ref push.
+# never fire the app build/package pipeline).
 
 on:
   push:
     branches: [main]
     paths:
       - "src/sdk/sdk_version.zig"
       - "src/sdk/version.zig"
+      - "sdk/sdk_version.zig"
+      - "sdk/**"
+      - "scripts/pack-sdk.sh"
+      - ".github/workflows/sdk-tag.yml"
   workflow_dispatch:
 
 concurrency:
   group: ${{ github.workflow }}
   cancel-in-progress: false
 
 jobs:
-  tag:
+  tag-and-release:
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -32,7 +38,8 @@ jobs:
           fetch-depth: 0
           fetch-tags: true
 
-      - name: Compute sdk_version and tag if missing
+      - name: Compute sdk_version
+        id: ver
         shell: bash
         run: |
           set -euo pipefail
@@ -48,15 +55,77 @@ jobs:
           fi
 
           tag="sdk-v${major}.${minor}.${patch}"
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+          echo "version=${major}.${minor}.${patch}" >> "$GITHUB_OUTPUT"
           echo "Resolved sdk_version -> $tag"
 
+      - name: Create tag if missing
+        shell: bash
+        run: |
+          set -euo pipefail
+          tag="${{ steps.ver.outputs.tag }}"
+
           if git rev-parse -q --verify "refs/tags/$tag" >/dev/null; then
-            echo "Tag $tag already exists, nothing to do."
+            echo "Tag $tag already exists."
             exit 0
           fi
 
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          git tag -a "$tag" -m "SDK $major.$minor.$patch (ABI fingerprint pin point)"
+          git tag -a "$tag" -m "SDK ${{ steps.ver.outputs.version }} (plugin pin + ABI fingerprint)"
           git push origin "$tag"
           echo "Pushed $tag"
+
+      - name: Pack SDK tarball
+        shell: bash
+        run: |
+          set -euo pipefail
+          chmod +x scripts/pack-sdk.sh
+          ./scripts/pack-sdk.sh "$PWD/zig-out/sdk"
+          ls -la zig-out/sdk/
+
+      - name: Publish GitHub release asset
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          tag="${{ steps.ver.outputs.tag }}"
+          version="${{ steps.ver.outputs.version }}"
+          asset="zig-out/sdk/fizzy-sdk-v${version}.tar.gz"
+          test -f "$asset"
+
+          notes_file="$(mktemp)"
+          cat >"$notes_file" <<EOF
+          Plugin-facing SDK package for Fizzy \`${version}\`.
+
+          Pin in your plugin's \`build.zig.zon\`:
+
+          \`\`\`zig
+          .fizzy = .{
+              .url = "https://github.com/fizzyedit/fizzy/releases/download/${tag}/fizzy-sdk-v${version}.tar.gz",
+              .hash = "…", // zig fetch --save=fizzy <url>
+          },
+          \`\`\`
+
+          Do **not** pin the git archive of this tag — that is the full monorepo (app zon / Velopack).
+          This asset is the \`sdk/\` package with \`src/core\` + \`src/sdk\` vendored in.
+          Locally, \`.path = "../fizzy/sdk"\` is fine while developing against an unreleased SDK.
+
+          See [docs/PLUGINS.md](https://github.com/fizzyedit/fizzy/blob/main/docs/PLUGINS.md) §2.3.
+          EOF
+          # Strip the common leading indent from the YAML-embedded heredoc.
+          sed -i 's/^          //' "$notes_file"
+
+          # Idempotent: create the release if missing, else replace the sdk asset.
+          if gh release view "$tag" >/dev/null 2>&1; then
+            echo "Release $tag exists — uploading/replacing asset."
+            gh release upload "$tag" "$asset" --clobber
+          else
+            gh release create "$tag" "$asset" \
+              --title "Fizzy SDK $version" \
+              --notes-file "$notes_file"
+          fi
+
+          echo "Published $asset on $tag"
+          gh release view "$tag" --json assets --jq '.assets[].name'

CLAUDE.md

@@ -9,12 +9,12 @@ Cross-platform, open-source general editor written in Zig, UI via [DVUI](https:/
 Fizzy the app is a near-empty **shell** (window, frame loop, menu/sidebar/panel layout, document model) that owns **no editing features**. Everything the user sees — pixel-art editing, the file explorer/tabs/splits, text editing — is contributed by **plugins** that register against a stable SDK. Plugins never import each other; they meet only at the SDK.
 
 ```
-Shell (Editor)  ←── Host registries + EditorAPI ──→  Plugin (register(host) + vtable)
+Shell (Editor) ←── Host registries + EditorAPI ──→ Plugin (register(host) + vtable)
 ```
 
 - **`src/sdk/`** — the entire contract. `Host` (registries + service locator), `Plugin` (identity + vtable of hooks the shell calls), `DocHandle` (opaque `{ptr, id, owner}` — shell routes every doc op to `owner`, never inspects `ptr`), `EditorAPI` (shell read/util surface plugins reach back through), `regions.zig` (sidebar/bottom/center/menu/settings/command contribution structs), `dylib.zig`/`dvui_context.zig` (runtime-library C-ABI + dvui injection).
 - **`src/editor/`** — the shell itself: `Editor.zig` (frame loop, plugin registration/loading), `PluginLoader.zig` (dlopen), `Menu.zig`, `Sidebar.zig`, `Settings.zig`, etc.
-- **`src/core/`** — shared infra (Atlas/Sprite, math, gfx, fs, paths, platform detection) used by shell *and* plugins. Not plugin-owned; don't move it.
+- **`src/core/`** — shared infra (Atlas/Sprite, math, gfx, fs, paths, platform detection) used by shell *and* plugins. Not plugin-owned; don't move it. `core.fuzzy` is the one matcher behind every filter box in the app (settings tree, file tree, plugin store, LSP completions) — wrap zf through it rather than matching by hand, and remember **lower scores are better**.
 - **`src/plugins/`** — bundled built-in plugins. Each is file-for-file the **same shape a third-party plugin would use**: root `plugin.zig` + identity-only `plugin.zig.zon` + `build.zig` + `build.zig.zon` (optional `src/**`), plus fizzy-internal glue in `static/`. No author `root.zig` or `<name>.zig` hub — the build helper generates the dylib entry; files use named imports (`fizzy_sdk`/`dvui`/…). Builds standalone with `cd src/plugins/<name> && zig build`.
 
 **Two link modes, one source:** built-in plugins compile **static** (linked directly, all targets incl. web) or **dynamic** (`.dylib`/`.so`/`.dll`, desktop-only, `dlopen`'d — this is how third-party plugins ship too). `FIZZY_STATIC_<NAME>=1` env var forces static for a given built-in (useful when debugging dylib loading).
@@ -36,7 +36,7 @@ Shell (Editor)  ←── Host registries + EditorAPI ──→  Plugin (registe
 3. Plugin prefs: `sdk.settings.Schema(struct { … })` then `.register(host, &plugin, …)` — shell draws them only while the plugin is loaded (no SettingsSection). User config on disk is ZON (`settings.zon` / `recents.zon`).
 4. Editor plugins implement the document vtable cluster; shell plugins (workbench-style) register a center provider + sidebar views instead.
 5. User-invoked actions are **`Command`s** — `"<active_owner_id>.<action>"`.
-6. `zig build install` drops `{id}.dylib` into the fizzy plugins dir (no sidecar `.zon`).
+6. `zig build install` drops `{id}/{id}.dylib` (its own directory) into the fizzy plugins dir (no sidecar `.zon`).
 7. Memory: `host.allocator` vs `host.arena()`; never touch `dvui.currentWindow().gpa` directly.
 8. ABI: structural fingerprint at `dlopen` (`fizzy_plugin_abi_fingerprint`); bumps are rare/deliberate.
 
@@ -60,25 +60,25 @@ Don't trust older narrative docs that call this forward-looking/not-yet-built.
 ## Build
 
 ```sh
-zig build            # native exe
-zig build check-web  # wasm
-zig build test       # unit/integration tests
-zig build test-sdk-version   # CI lock: ABI fingerprint bump must bump sdk_version too
+zig build              # native exe
+zig build check-web    # wasm
+zig build test         # unit/integration tests
+zig build test-sdk-version  # CI lock: ABI fingerprint bump must bump sdk_version too
 ```
 
 Run all of these after touching the SDK boundary (`src/sdk/**`) or a plugin's vtable usage.
 
 ### Keep the plugin build free of app-only dependencies
 
-Every plugin build (including third-party ones like pixi) compiles this repo's root `build.zig` via `b.dependency("fizzy", .{ .plugin_sdk = true })`. Because `@import` is **comptime + transitive**, anything the root `build()` can reach at comptime is pulled into *every* plugin build — even code guarded by a runtime `if (plugin_sdk) return;`. So an app-only dependency reached through a plain top-level `@import("<dep>")` (like Velopack, the host's self-installer/updater) leaks its whole graph — wrapper + prebuilt archives — into plugin builds that never use it.
+Plugins depend on the **`sdk/` package** (its own `build.zig` + `build.zig.zon`), not the repo root. The root zon owns the editor build and may list app-only deps (Velopack, nightwatch, …). A root-zon `.lazy = true` URL dep is **not** enough by itself: Zig eagerly unpacks lazy URL deps that already sit in the global cache into every consumer's `zig-pkg`, so after any app build a plugin depending on the root package would grow a Velopack tree even though `lazyDependency` never runs on the plugin path.
 
-Rule: **app-only deps must never be reachable via comptime `@import` from the root build graph.** The pattern (see Velopack):
+Pattern:
 
-- Mark the dep `.lazy = true` in `build.zig.zon`.
-- Never `@import("velopack_zig")` anywhere in the build graph. The helper surface is **vendored** in `build/velopack.zig` (pure `std.Build` glue) and takes the dependency as a handle.
-- Resolve it lazily *inside the app build only*: `const vz = b.lazyDependency("velopack_zig", .{}) orelse return;` in `build/app.zig`, then thread `vz` through `build/exe.zig` / `build/package.zig`.
+- **Plugins** (built-in + third-party): `.fizzy = .{ .path = ".../sdk" }` locally, or the `fizzy-sdk-v*` **release asset** URL from the matching `sdk-v*` tag (not the git archive — that is the monorepo root zon with Velopack). Call `fizzy.plugin.create` / `.install` as before; `b.dependency("fizzy", .{ .plugin_sdk = true })` still works (the option is accepted and ignored — `sdk/` always exports modules). Packing: `scripts/pack-sdk.sh` / `.github/workflows/sdk-tag.yml`.
+- **App**: repo-root `zig build` as usual. Velopack stays `.lazy = true` in the root zon; never `@import("velopack_zig")` — the helper surface is vendored in `build/velopack.zig` and resolved only in `build/app.zig` via `lazyDependency`.
+- Shared `core` import wiring lives in `sdk/core_module.zig` and is called from the app build *and* `sdk/plugin_sdk.zig`'s `exportModules` so the import set can't drift. Note the `with_tui = false` on the zf dependency: without it, zf's standalone terminal binary drags `libvaxis` into every plugin build.
 
-Acceptance test after any build-graph change: cross-build the image plugin and confirm no leak —
+Acceptance test after any build-graph change:
 
 ```sh
 cd src/plugins/image && rm -rf .zig-cache zig-out zig-pkg && zig build -Doptimize=ReleaseFast

build.zig

@@ -1,6 +1,8 @@
 const std = @import("std");
 
-pub const plugin = @import("plugin_sdk.zig");
+/// App-side re-export of the plugin build API (lives in `sdk/`). Plugins should depend on
+/// the `sdk/` package directly — see CLAUDE.md — not this root package.
+pub const plugin = @import("sdk/plugin_sdk.zig");
 
 pub fn build(b: *std.Build) !void {
     const windows_msvc_libc_opt = b.option([]const u8, "windows-msvc-libc", "zig libc manifest for *-windows-msvc when cross-compiling; forwarded by packageall for Windows children") orelse null;
@@ -16,21 +18,11 @@ pub fn build(b: *std.Build) !void {
     const target = b.standardTargetOptions(.{});
     const optimize = b.standardOptimizeOption(.{});
 
-    const plugin_sdk = b.option(
-        bool,
-        "plugin_sdk",
-        "Export core/sdk modules for third-party plugin builds; skips the fizzy app",
-    ) orelse false;
-    if (plugin_sdk) {
-        try plugin.exportModules(b, target, optimize);
-        return;
-    }
-
     try @import("build/app.zig").build(b, target, optimize, .{
         .windows_msvc_libc_opt = windows_msvc_libc_opt,
         .fetch_msvc_opt = fetch_msvc_opt,
         .macos_sign_app_identity = macos_sign_app_identity,
         .macos_sign_install_identity = macos_sign_install_identity,
         .macos_notary_profile = macos_notary_profile,
     });
-} 
+}

build.zig.zon

@@ -5,8 +5,7 @@
         "build.zig",
         "build.zig.zon",
         "update.zig",
-        "build",
-        "plugin_sdk.zig",
+        "sdk",
         "assets",
         "libs",
     },
@@ -39,6 +38,8 @@
             .url = "https://github.com/foxnne/assetpack/archive/ac7592f3f5988857840d0df4610e1e1fad690e2e.tar.gz",
             .hash = "assetpack-0.2.0-5DA2d1ZkAADJanNVdWrUBOGMhOzUENhrUiqXcHADxY2x",
         },
+        // App-only. Plugins depend on `sdk/` (not this root package) so they never see
+        // Velopack — see CLAUDE.md.
         .velopack_zig = .{
             .url = "https://github.com/graphl-tech/velopack-zig/archive/0c2f20635a97fde38cc8000e9fb1a75f891cf37d.tar.gz",
             .hash = "velopack_zig-0.0.1-LzeGcengAACU1f33uDAuLKlWXtek0KCC6i_b3XWeJMjd",
@@ -52,5 +53,14 @@
             .hash = "cmark_gfm-0.1.0-uQgTKymaFwDK0jVZszXfDtQtW6BnS44Bp0GS55TVBD4p",
             .lazy = true,
         },
+        .nightwatch = .{
+            .url = "git+https://github.com/neurocyte/nightwatch#cac3b9edb3a59f5b3a290cf3b76044ad9b09ef28",
+            .hash = "nightwatch-1.0.0-uXzeHyOgAgCvaBhschfx3LA48n01bLYOVBQUXYjvrREM",
+            .lazy = true,
+        },
+        .zf = .{
+            .url = "git+https://github.com/natecraddock/zf#c35c421f84895193246db06c40683c1a30e616ef",
+            .hash = "zf-0.11.0-OIRy8X-RAAAwaRXHMYpj2uvBnuGTZWEE_3V7acqHQNtW",
+        },
     },
 }

build/app.zig

@@ -1,9 +1,18 @@
 const std = @import("std");
 
-const plugin = @import("../plugin_sdk.zig");
+const plugin = @import("../sdk/plugin_sdk.zig");
+const core_mod = @import("../sdk/core_module.zig");
 const dvui = @import("dvui");
 const velopack = @import("velopack.zig");
 
+// `sdk/sdk_version.zig` mirrors `src/sdk/sdk_version.zig` for the plugin package boundary.
+comptime {
+    const pack = @import("../sdk/sdk_version.zig").sdk_version;
+    const runtime = @import("../src/sdk/sdk_version.zig").sdk_version;
+    if (pack.major != runtime.major or pack.minor != runtime.minor or pack.patch != runtime.patch)
+        @compileError("sdk/sdk_version.zig drifted from src/sdk/sdk_version.zig — bump both");
+}
+
 pub const Options = struct {
     windows_msvc_libc_opt: ?[]const u8 = null,
     fetch_msvc_opt: ?bool = null,
@@ -19,10 +28,9 @@ pub fn build(b: *std.Build, target: std.Build.ResolvedTarget, optimize: std.buil
     const macos_sign_install_identity = opts.macos_sign_install_identity;
     const macos_notary_profile = opts.macos_notary_profile;
 
-    // Resolve Velopack lazily. This runs only on app builds (never on the plugin-SDK path,
-    // which returns from the root build before reaching here), so plugin builds never fetch
-    // it. On the first configure pass this returns null → Zig fetches velopack_zig and
-    // re-runs build(); the second pass proceeds with a valid handle.
+    // Resolve Velopack lazily (app-only; plugins depend on `sdk/` which has no Velopack).
+    // First configure pass returns null → Zig fetches velopack_zig and re-runs build();
+    // the second pass proceeds with a valid handle.
     const vz = b.lazyDependency("velopack_zig", .{}) orelse return;
 
     const common = @import("common.zig");
@@ -425,28 +433,26 @@ pub fn build(b: *std.Build, target: std.Build.ResolvedTarget, optimize: std.buil
     fizzy_test_module.addImport("backend", dvui_testing_dep.module("testing"));
     fizzy_test_module.addImport("assets", assets_module);
     fizzy_test_module.addOptions("build_opts", build_opts);
-    if (b.lazyDependency("icons", .{ .target = target, .optimize = optimize })) |dep| {
-        fizzy_test_module.addImport("icons", dep.module("icons"));
-    }
 
     // Shared `core` module for the test build (dvui testing backend variant).
     const core_module_test = b.createModule(.{
         .target = target,
         .optimize = optimize,
         .root_source_file = b.path("src/core/core.zig"),
     });
-    core_module_test.addImport("dvui", dvui_testing_dep.module("dvui_testing"));
-    if (b.lazyDependency("icons", .{ .target = target, .optimize = optimize })) |dep| {
-        core_module_test.addImport("icons", dep.module("icons"));
-    }
+    const icons_test = core_mod.addImports(b, core_module_test, dvui_testing_dep.module("dvui_testing"), target, optimize);
     fizzy_test_module.addImport("core", core_module_test);
+    if (icons_test) |icons| fizzy_test_module.addImport("icons", icons);
+    if (b.lazyDependency("nightwatch", .{ .target = target, .optimize = optimize })) |dep| {
+        fizzy_test_module.addImport("nightwatch", dep.module("nightwatch"));
+    }
 
     const sdk_module_test = sdk.wireSdkModule(b, target, optimize, dvui_testing_dep.module("dvui_testing"), dvui_test_proxy_bridge, core_module_test, fizzy_test_module);
     _ = workbench_plugin.addStaticModule(b, target, optimize, .{
         .dvui = dvui_testing_dep.module("dvui_testing"),
         .core = core_module_test,
         .sdk = sdk_module_test,
-        .icons = if (b.lazyDependency("icons", .{ .target = target, .optimize = optimize })) |dep| dep.module("icons") else null,
+        .icons = icons_test,
         .backend = dvui_testing_dep.module("testing"),
     }, workbench_opts, fizzy_test_module);
     _ = text_plugin.addStaticModule(b, target, optimize, .{

build/common.zig

@@ -1,6 +1,6 @@
 const std = @import("std");
 
-const plugin = @import("../plugin_sdk.zig");
+const plugin = @import("../sdk/plugin_sdk.zig");
 const update = @import("../update.zig");
 const GitDependency = update.GitDependency;