feat(sdk): KCSDK v1.0.0 — complete SDK implementation (#346) #366

Merged

forbes merged 10 commits from feat/kcsdk-finalize into main 2026-03-02 19:03:17 +00:00

Conversation 0 Commits 10 Files Changed 8 +95 -200

forbes commented 2026-03-01 20:42:30 +00:00

Owner

Copy Link

Summary

Complete implementation of the KCSDK epic (#346), phases 1–8. This PR brings the Kindred SDK from a pure-Python wrapper to a full C++/pybind11 module with stable v1.0.0 API.

Commits (9)

1. #350 — Scaffold KCSDK shared library + kcsdk pybind11 module
2. #351 — Migrate editing context API to kcsdk (7 C++ bindings)
3. #352, #353 — Add panel provider (IPanelProvider) and theme engine (ThemeEngine)
4. fix — Resolve initial editing context on construction
5. docs — KCSDK API reference and addon developer guide
6. #354 — Add IToolbarProvider interface to kcsdk
7. #355 — Add IMenuProvider interface and register_command() wrapper
8. #356 — Add status bar widget wrapper and origin query bindings
9. #357 — Remove fallbacks, add deprecation warnings, bump v1.0.0

Architecture

src/Gui/SDK/
├── CMakeLists.txt          # libKCSDK shared library
├── KCSDKGlobal.h           # Export macros
├── SDKRegistry.h/.cpp      # Central provider registry
├── Types.h                 # Shared type definitions
├── IPanelProvider.h        # Dock panel interface
├── IToolbarProvider.h      # Toolbar interface
├── IMenuProvider.h         # Menu interface
├── ThemeEngine.h/.cpp      # Catppuccin palette queries
├── WidgetBridge.h/.cpp     # Qt widget integration
└── bindings/
    ├── CMakeLists.txt      # kcsdk.so pybind11 module
    ├── kcsdk_py.cpp        # All pybind11 bindings
    └── Py*.h               # Trampoline classes

Python API (kindred_sdk v1.0.0)

All wrappers now require the kcsdk C++ module (fallbacks removed):

• context.py — 7 editing context functions
• dock.py — dock panel registration
• toolbar.py — toolbar provider registration
• menu.py — menu provider registration
• command.py — register_command() convenience wrapper
• statusbar.py — status bar widget registration (pure Python)
• origin.py — origin queries via kcsdk; register/unregister still via FreeCADGui
• theme.py — palette and token queries via ThemeEngine

Deprecation

11 superseded FreeCADGui.* methods now emit Base::Console().warning() but continue working. addOrigin/removeOrigin are excluded (not yet superseded).

Testing

• Build: FreeCADGui + KCSDK + kcsdk_py compile cleanly
• pixi run test-kindred: all 39 Tier 1 tests pass

Closes #346, #350, #351, #352, #353, #354, #355, #356, #357

## Summary Complete implementation of the KCSDK epic (#346), phases 1–8. This PR brings the Kindred SDK from a pure-Python wrapper to a full C++/pybind11 module with stable v1.0.0 API. ## Commits (9) 1. **`#350`** — Scaffold KCSDK shared library + kcsdk pybind11 module 2. **`#351`** — Migrate editing context API to kcsdk (7 C++ bindings) 3. **`#352, #353`** — Add panel provider (`IPanelProvider`) and theme engine (`ThemeEngine`) 4. **fix** — Resolve initial editing context on construction 5. **docs** — KCSDK API reference and addon developer guide 6. **`#354`** — Add `IToolbarProvider` interface to kcsdk 7. **`#355`** — Add `IMenuProvider` interface and `register_command()` wrapper 8. **`#356`** — Add status bar widget wrapper and origin query bindings 9. **`#357`** — Remove fallbacks, add deprecation warnings, bump v1.0.0 ## Architecture ``` src/Gui/SDK/ ├── CMakeLists.txt # libKCSDK shared library ├── KCSDKGlobal.h # Export macros ├── SDKRegistry.h/.cpp # Central provider registry ├── Types.h # Shared type definitions ├── IPanelProvider.h # Dock panel interface ├── IToolbarProvider.h # Toolbar interface ├── IMenuProvider.h # Menu interface ├── ThemeEngine.h/.cpp # Catppuccin palette queries ├── WidgetBridge.h/.cpp # Qt widget integration └── bindings/ ├── CMakeLists.txt # kcsdk.so pybind11 module ├── kcsdk_py.cpp # All pybind11 bindings └── Py*.h # Trampoline classes ``` ## Python API (kindred_sdk v1.0.0) All wrappers now **require** the kcsdk C++ module (fallbacks removed): - `context.py` — 7 editing context functions - `dock.py` — dock panel registration - `toolbar.py` — toolbar provider registration - `menu.py` — menu provider registration - `command.py` — `register_command()` convenience wrapper - `statusbar.py` — status bar widget registration (pure Python) - `origin.py` — origin queries via kcsdk; register/unregister still via FreeCADGui - `theme.py` — palette and token queries via ThemeEngine ## Deprecation 11 superseded `FreeCADGui.*` methods now emit `Base::Console().warning()` but continue working. `addOrigin`/`removeOrigin` are excluded (not yet superseded). ## Testing - Build: FreeCADGui + KCSDK + kcsdk_py compile cleanly - `pixi run test-kindred`: all 39 Tier 1 tests pass Closes #346, #350, #351, #352, #353, #354, #355, #356, #357

forbes added 9 commits 2026-03-01 20:42:31 +00:00

feat(sdk): scaffold KCSDK library + kcsdk pybind11 module (#350) ... 63e591a626

Add the KCSDK C++ shared library and kcsdk pybind11 module, establishing
the build infrastructure for the C++-backed addon SDK.

New files:
- src/Gui/SDK/KCSDKGlobal.h — DLL export macros
- src/Gui/SDK/SDKRegistry.h/.cpp — empty singleton with API_VERSION_MAJOR=1
- src/Gui/SDK/CMakeLists.txt — builds KCSDK shared library
- src/Gui/SDK/bindings/kcsdk_py.cpp — pybind11 module exposing version + available()
- src/Gui/SDK/bindings/CMakeLists.txt — builds kcsdk pybind11 module

Modified:
- src/Gui/CMakeLists.txt — add_subdirectory(SDK)

Verified: import kcsdk; kcsdk.API_VERSION_MAJOR == 1; kcsdk.available() == []

feat(sdk): migrate editing context API to kcsdk (#351) ... 60c0489d73

Add context/overlay registration, injection, query, and refresh to the
KCSDK C++ library and kcsdk pybind11 module.

New files:
- src/Gui/SDK/Types.h — ContextDef, OverlayDef, ContextSnapshot structs
  (plain C++, no Qt in public API)

Modified:
- src/Gui/SDK/SDKRegistry.h/.cpp — register_context/overlay, unregister,
  inject_commands, current_context, refresh (delegates to
  EditingContextResolver with std↔Qt conversion)
- src/Gui/SDK/CMakeLists.txt — add Types.h, link FreeCADGui
- src/Gui/SDK/bindings/kcsdk_py.cpp — bind all context functions with
  GIL-safe match callable wrapping and dict-based snapshot return
- mods/sdk/kindred_sdk/context.py — try kcsdk first, fall back to
  FreeCADGui for backwards compatibility

feat(sdk): add panel provider and theme engine to kcsdk (#352, #353) ... 64644eb623

- IPanelProvider: abstract interface for dock panels with PySide widget bridging
- PyIPanelProvider/PyProviderHolder: pybind11 trampoline + GIL-safe holder
- WidgetBridge: PySide QWidget → C++ QWidget* conversion via Shiboken
- SDKRegistry: panel registration, creation, and lifecycle management
- ThemeEngine: C++ singleton with minimal YAML parser, palette cache,
  getColor/allTokens/formatQss matching Python Palette API
- kcsdk bindings: DockArea, PanelPersistence enums, panel functions,
  theme_color, theme_tokens, format_qss, load_palette
- dock.py: kcsdk delegation with FreeCADGui fallback
- theme.py: kcsdk delegation with Python YAML fallback

fix(editing-context): resolve initial context on construction ... 5f8557fc83

EditingContextResolver constructor did not call refresh(), leaving
d->current as a default empty EditingContext. When BreadcrumbToolBar
queried currentContext() on creation, it received an empty context
with no breadcrumb segments, causing the navbar to appear blank.

Add refresh() at end of constructor so the initial state is resolved
before any View3DInventor queries it.

docs(sdk): add KCSDK API reference and addon developer guide ... ab4054eb9e

- docs/src/reference/kcsdk-python.md: full kcsdk Python API reference
- docs/src/development/writing-an-addon.md: step-by-step addon guide
- docs/INTEGRATION_PLAN.md: add Phase 7 KCSDK section
- docs/ARCHITECTURE.md: add src/Gui/SDK/ to source layout
- docs/src/SUMMARY.md: add new pages to mdBook navigation

feat(sdk): add IToolbarProvider interface to kcsdk (#354) 4eb643a26f

feat(sdk): add IMenuProvider interface and register_command wrapper (#355) ... 747c458e23

IMenuProvider: declarative menu placement with optional context awareness.
C++ interface with pybind11 bindings + GIL-safe holder. SDKMenuManipulator
(shared WorkbenchManipulator) injects menu items on workbench switch,
filtered by editing context when context_ids() is non-empty.

register_command(): thin Python wrapper around FreeCADGui.addCommand()
that standardizes the calling convention within the SDK contract.

Python wrappers (kindred_sdk.register_menu, kindred_sdk.register_command)
use kcsdk-first routing with FreeCADGui fallback.

feat(sdk): add status bar widget wrapper and origin query bindings (#356) ... a6a6cefc16

register_status_widget(): pure Python wrapper that adds a live widget
to the main window status bar with context menu discoverability.

Origin query bindings (kcsdk.list_origins, active_origin, get_origin,
set_active_origin): thin C++ forwarding to OriginManager with Python
wrappers using kcsdk-first routing.

IOriginProvider and IStatusBarProvider C++ interfaces dropped — existing
FileOrigin stack is already complete, and status bar widgets don't need
C++ lifecycle management.

feat(sdk): remove fallbacks, add deprecation warnings, bump v1.0.0 (#357) ... 79f69e2856

- Bump SDK_VERSION to 1.0.0 in version.py and package.xml
- Remove <pure_python> tag from package.xml (kcsdk is C++)
- Remove all FreeCADGui.* fallback paths in context.py, dock.py,
  toolbar.py, menu.py; require kcsdk module
- Remove query fallbacks in origin.py (keep register/unregister
  which still need FreeCADGui.addOrigin/removeOrigin)
- Add deprecation warnings to 11 superseded FreeCADGui methods
  in ApplicationPy.cpp (not addOrigin/removeOrigin)
- All 39 Tier 1 tests pass

forbes added 23 commits 2026-03-02 18:33:01 +00:00

feat(sdk): scaffold KCSDK library + kcsdk pybind11 module (#350) ... 9b28feb8ca

Add the KCSDK C++ shared library and kcsdk pybind11 module, establishing
the build infrastructure for the C++-backed addon SDK.

New files:
- src/Gui/SDK/KCSDKGlobal.h — DLL export macros
- src/Gui/SDK/SDKRegistry.h/.cpp — empty singleton with API_VERSION_MAJOR=1
- src/Gui/SDK/CMakeLists.txt — builds KCSDK shared library
- src/Gui/SDK/bindings/kcsdk_py.cpp — pybind11 module exposing version + available()
- src/Gui/SDK/bindings/CMakeLists.txt — builds kcsdk pybind11 module

Modified:
- src/Gui/CMakeLists.txt — add_subdirectory(SDK)

Verified: import kcsdk; kcsdk.API_VERSION_MAJOR == 1; kcsdk.available() == []

Merge pull request 'feat(sdk): scaffold KCSDK library + kcsdk pybind11 module (#350)' (#358) from feat/kcsdk-scaffold into main ... 169c177b69

Reviewed-on: #358

feat(sdk): migrate editing context API to kcsdk (#351) ... f44aba7388

Add context/overlay registration, injection, query, and refresh to the
KCSDK C++ library and kcsdk pybind11 module.

New files:
- src/Gui/SDK/Types.h — ContextDef, OverlayDef, ContextSnapshot structs
  (plain C++, no Qt in public API)

Modified:
- src/Gui/SDK/SDKRegistry.h/.cpp — register_context/overlay, unregister,
  inject_commands, current_context, refresh (delegates to
  EditingContextResolver with std↔Qt conversion)
- src/Gui/SDK/CMakeLists.txt — add Types.h, link FreeCADGui
- src/Gui/SDK/bindings/kcsdk_py.cpp — bind all context functions with
  GIL-safe match callable wrapping and dict-based snapshot return
- mods/sdk/kindred_sdk/context.py — try kcsdk first, fall back to
  FreeCADGui for backwards compatibility

Merge branch 'main' into feat/kcsdk-scaffold 81a2e75477

Merge pull request 'feat(sdk): migrate editing context API to kcsdk (#351)' (#359) from feat/kcsdk-scaffold into main ... 9fc0d064f8

Reviewed-on: #359

feat(sdk): add panel provider and theme engine to kcsdk (#352, #353) ... 18532e3bd7

- IPanelProvider: abstract interface for dock panels with PySide widget bridging
- PyIPanelProvider/PyProviderHolder: pybind11 trampoline + GIL-safe holder
- WidgetBridge: PySide QWidget → C++ QWidget* conversion via Shiboken
- SDKRegistry: panel registration, creation, and lifecycle management
- ThemeEngine: C++ singleton with minimal YAML parser, palette cache,
  getColor/allTokens/formatQss matching Python Palette API
- kcsdk bindings: DockArea, PanelPersistence enums, panel functions,
  theme_color, theme_tokens, format_qss, load_palette
- dock.py: kcsdk delegation with FreeCADGui fallback
- theme.py: kcsdk delegation with Python YAML fallback

fix(editing-context): resolve initial context on construction ... 1b38d7b24b

EditingContextResolver constructor did not call refresh(), leaving
d->current as a default empty EditingContext. When BreadcrumbToolBar
queried currentContext() on creation, it received an empty context
with no breadcrumb segments, causing the navbar to appear blank.

Add refresh() at end of constructor so the initial state is resolved
before any View3DInventor queries it.

docs(sdk): add KCSDK API reference and addon developer guide ... 5a0be2804d

- docs/src/reference/kcsdk-python.md: full kcsdk Python API reference
- docs/src/development/writing-an-addon.md: step-by-step addon guide
- docs/INTEGRATION_PLAN.md: add Phase 7 KCSDK section
- docs/ARCHITECTURE.md: add src/Gui/SDK/ to source layout
- docs/src/SUMMARY.md: add new pages to mdBook navigation

Merge pull request 'feat(sdk): KCSDK panel provider, theme engine, and breadcrumb fix (#352, #353)' (#360) from feat/kcsdk-scaffold into main ... abfd939d2c

Reviewed-on: #360

feat: add gears workbench as default addon ... 04065e83f3

Add kindred/gears as a submodule under mods/gears. The gears workbench
provides 13 parametric gear commands (involute, cycloid, bevel, worm,
crown, timing, lantern, hypocycloid gears + connectors).

Integration:
- Kindred package.xml with load_priority 40 (sdk -> solver -> gears -> silo)
- Init.py adds repo root to sys.path for pygears + namespace package
- InitGui.py imports upstream GearWorkbench and injects gear commands
  into partdesign.body and partdesign.feature editing contexts
- context.py kcsdk routing already complete from #351

Merge pull request 'feat: add gears workbench as default addon' (#361) from feat/gears-addon into main ... 153f75e6e7

Reviewed-on: #361

chore: set gears submodule default branch to main ecdc9c2067

chore: update silo and solver submodules 51f7635ceb

feat(sdk): add IToolbarProvider interface to kcsdk (#354) 76e448d0d7

Merge pull request 'feat/gears-addon' (#362) from feat/gears-addon into main ... 3759f707cf

Reviewed-on: #362

feat(sdk): add IMenuProvider interface and register_command wrapper (#355) ... 2bf083609d

IMenuProvider: declarative menu placement with optional context awareness.
C++ interface with pybind11 bindings + GIL-safe holder. SDKMenuManipulator
(shared WorkbenchManipulator) injects menu items on workbench switch,
filtered by editing context when context_ids() is non-empty.

register_command(): thin Python wrapper around FreeCADGui.addCommand()
that standardizes the calling convention within the SDK contract.

Python wrappers (kindred_sdk.register_menu, kindred_sdk.register_command)
use kcsdk-first routing with FreeCADGui fallback.

Merge pull request 'feat(sdk): add IMenuProvider interface and register_command wrapper (#355)' (#363) from feat/gears-addon into main ... ec5b3850e9

Reviewed-on: #363

feat(sdk): add status bar widget wrapper and origin query bindings (#356) ... ab8519c272

register_status_widget(): pure Python wrapper that adds a live widget
to the main window status bar with context menu discoverability.

Origin query bindings (kcsdk.list_origins, active_origin, get_origin,
set_active_origin): thin C++ forwarding to OriginManager with Python
wrappers using kcsdk-first routing.

IOriginProvider and IStatusBarProvider C++ interfaces dropped — existing
FileOrigin stack is already complete, and status bar widgets don't need
C++ lifecycle management.

Merge pull request 'feat(sdk): add status bar widget wrapper and origin query bindings (#356)' (#364) from feat/gears-addon into main ... 9778d0dd1b

Reviewed-on: #364

chore: native repository conversion — remove FreeCAD/GitHub artifacts (#367) ... fa9c9ba761

- Delete .github/ directory (60 files, ~4600 lines of unused GitHub
  Actions workflows, FreeCAD-branded issue/PR templates, problem
  matchers, scripts, and images)
- Delete .packit.yaml (Fedora COPR packaging, unused)
- Delete SECURITY.md (FreeCAD-specific security policy)
- Update .pre-commit-config.yaml to remove .github file pattern
- Update .gitignore to remove .github/ whitelist
- Rewrite CODE_OF_CONDUCT.md for Kindred Create community
- Rewrite PRIVACY_POLICY.md covering Silo integration, update
  checker, origin system, and local storage

Gitea equivalents (.gitea/workflows/, .gitea/ISSUE_TEMPLATE/,
.gitea/pull_request_template.md) are already in place.

Closes #367

chore: rebrand XDGData and icon installs to Kindred Create (#367) ... 1b01762a1c

- Replace org.freecad.FreeCAD.desktop with kindred-create.desktop
- Replace org.freecad.FreeCAD.metainfo.xml.in with Kindred Create
  metainfo (new description, Kindred URLs, kindred-create app ID)
- Replace org.freecad.FreeCAD.xml with kindred-create.xml (adds .kc
  MIME type alongside .fcstd)
- Replace FreeCAD.thumbnailer.in with kindred-create.thumbnailer.in
- Update XDGData/CMakeLists.txt for new filenames
- Update src/Gui/CMakeLists.txt icon installs: use kindred-create
  icons from resources/ (all sizes 16-512 + SVG) instead of renaming
  freecad-icon-*.png to org.freecad.FreeCAD.png
- Update freecad-thumbnailer.in default icon to kindred-create.png
- Update AppImage create_bundle.sh to use kindred-create desktop/icon

Remaining org.freecad.FreeCAD references are macOS bundle IDs
(MainWindow.cpp, MacAppBundle/) and packaging fallbacks — separate
rebranding tasks.

Merge pull request 'chore: native repository conversion — remove FreeCAD/GitHub artifacts (#367)' (#368) from chore/repo-cleanup into main ... b0621f9731

Reviewed-on: #368

Merge remote-tracking branch 'origin/main' into feat/kcsdk-finalize ... 470e6f3cf6

# Conflicts:
#	mods/sdk/kindred_sdk/context.py
#	mods/sdk/kindred_sdk/dock.py
#	mods/sdk/kindred_sdk/menu.py
#	mods/sdk/kindred_sdk/origin.py
#	mods/sdk/kindred_sdk/toolbar.py

forbes merged commit e160b07b00 into main 2026-03-02 19:03:17 +00:00

forbes deleted branch feat/kcsdk-finalize 2026-03-02 19:03:18 +00:00

forbes referenced this issue from a commit 2026-03-02 19:03:19 +00:00

Merge pull request 'feat(sdk): KCSDK v1.0.0 — complete SDK implementation (#346)' (#366) from feat/kcsdk-finalize into main

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

UX

branding

bug

ci/cd

CI/CD workflows and deployment

defaults

documentation

Developer documentation

enhancement

high-priority

low-priority

theme

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

forbes

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: kindred/create#366