Cleanup code in advance of initial beta release v0.1.0

[matt-pharr]

No description provided.

[matt-pharr]

@copilot review

[Copilot]

@copilot review

Review complete. Found and fixed the following across commits 004422d and 78cdcca:

Critical fixes:

• Mutex race condition (ipc-register-kernels.ts) — refactored awaitPreviousMutex into acquireMutex which atomically captures the old mutex and replaces startMutex with a new pending promise before the first await. The previous version left a window where two concurrent IPC calls could both observe the resolved mutex and proceed simultaneously.
• Stale onKernelStatus → onKernelCrashed (ARCHITECTURE.md §11.2, §11.5) — three references to the old name/payload shape updated to match the actual implementation.

Non-critical fixes:

• _node_exists None bug (tree_loader.py) — return value is not None, value treated a node holding None as absent; changed to return True, value so conflict_strategy="skip" no longer overwrites valid None nodes.
• Missing typing imports (handlers/project.py) — added from typing import Any, Callable and removed the now-unnecessary forward-reference string quotes.
• useModalKeyboard renamed → makeModalKeyboardHandler (file + all four call sites) — the function calls no React hooks, so the use prefix was misleading. Added a JSDoc note that callers should wrap in useCallback if passing the result as a prop to a memoized child.
• ARCHITECTURE.md §12.2 — added tree_loader.py and handlers/_helpers.py to the Python package layout listing.

[Copilot]

Pull request overview

This PR performs pre–v0.1.0 cleanup and refactoring across both the Python kernel (pdv-python) and the Electron app (electron), focusing on deduplication of loader/handler logic, tightening protocol/type contracts, and simplifying renderer utilities.

Changes:

• Kernel: centralize tree-index mounting logic (tree_loader.py) and handler validation boilerplate (handlers/_helpers.py); add PDVTree.set_quiet for bulk loads without change spam.
• Electron main/renderer: refactor popup-window managers onto a shared BaseWindowManager, rename kernel crash push plumbing, and streamline renderer tree/type utilities (camelCase view-model mapping, reusable error/keyboard helpers).
• Protocol/types: export additional protocol payload types and align UI icon/type handling with canonical NodeKindValue.

Reviewed changes

Copilot reviewed 73 out of 74 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
pdv-python/tests/test_serialization.py	Removes coverage for deleted extract_docstring_preview.
pdv-python/pdv_kernel/tree.py	Adds module-cache reset helper, makes resolve_path always absolute, introduces PDVTree.set_quiet.
pdv-python/pdv_kernel/tree_loader.py	New shared two-pass loader used by project load and module register.
pdv-python/pdv_kernel/serialization.py	Doc clarifications; removes extract_docstring_preview.
pdv-python/pdv_kernel/namespace.py	Uses shared protected-name set for namespace filtering.
pdv-python/pdv_kernel/handlers/tree.py	Simplifies file resolution using updated resolve_path.
pdv-python/pdv_kernel/handlers/script.py	Deduplicates register validation via shared helper.
pdv-python/pdv_kernel/handlers/project.py	Switches to shared load_tree_index loader and progress callback.
pdv-python/pdv_kernel/handlers/note.py	Deduplicates register validation via shared helper.
pdv-python/pdv_kernel/handlers/namelist.py	Centralizes namelist node resolution/validation.
pdv-python/pdv_kernel/handlers/modules.py	Reuses shared loader for module subtree mounting; clarifies setup docs.
pdv-python/pdv_kernel/handlers/gui.py	Deduplicates register validation and GUI-to-module attachment.
pdv-python/pdv_kernel/handlers/_helpers.py	New shared validation/lookup helpers for handlers.
pdv-python/pdv_kernel/errors.py	Removes unused/obsolete exception classes.
pdv-python/pdv_kernel/comms.py	Clarifies version policy reference comments.
pdv-python/pdv_kernel/checksum.py	Updates digest docstring to match XXH3-128 implementation.
electron/renderer/src/utils/errors.ts	New shared promise error-capture helper.
electron/renderer/src/types/pdv.d.ts	Re-exports several wire types from main-process IPC/protocol; adds config field.
electron/renderer/src/types/index.ts	Updates TreeNodeData to camelCase view-model mapped from wire NodeDescriptor.
electron/renderer/src/services/tree.ts	Adds listByPath and centralizes snake_case→camelCase mapping.
electron/renderer/src/services/tree.test.ts	Adjusts tests for updated TreeNodeData shape.
electron/renderer/src/module-window/ModuleWindowRoot.tsx	Uses treeService.listByPath for option population/caching.
electron/renderer/src/hooks/useModalKeyboard.ts	New shared Enter/Escape modal key handler.
electron/renderer/src/gui-viewer/GuiViewerRoot.tsx	Cleans up React import usage.
electron/renderer/src/gui-editor/PropertyEditor.tsx	Removes unused imports.
electron/renderer/src/gui-editor/LivePreview.tsx	Cleans up React import usage.
electron/renderer/src/gui-editor/LayoutCanvas.tsx	Removes unused import; adjusts label fallback behavior.
electron/renderer/src/gui-editor/GuiEditorRoot.tsx	Removes unused context state; refactors resizer ref updates.
electron/renderer/src/components/WriteTab/math-preview.ts	Renames unused parameter to satisfy linting.
electron/renderer/src/components/Tree/TreeNodeRow.tsx	Aligns icon mapping with canonical node kind values.
electron/renderer/src/components/Tree/TreeNodeRow.test.tsx	Updates icon/type tests to new node-kind mapping.
electron/renderer/src/components/Tree/tree-utils.test.ts	Adjusts test fixtures for updated TreeNodeData shape.
electron/renderer/src/components/Tree/index.tsx	Refactors virtual row renderer typing; updates handler field usage.
electron/renderer/src/components/Tree/CreateScriptDialog.tsx	Uses shared useModalKeyboard hook.
electron/renderer/src/components/Tree/CreateNoteDialog.tsx	Uses shared useModalKeyboard hook.
electron/renderer/src/components/Tree/CreateGuiDialog.tsx	Uses shared useModalKeyboard hook.
electron/renderer/src/components/Tree/ContextMenu.tsx	Updates container detection to mapping node type.
electron/renderer/src/components/Tree/ContextMenu.test.tsx	Adjusts test fixture typing.
electron/renderer/src/components/Tree/context-menu-actions.test.ts	Updates expectations for mapping container kind.
electron/renderer/src/components/ScriptDialog/ScriptDialog.test.tsx	Updates test fixtures for updated TreeNodeData shape.
electron/renderer/src/components/ScriptDialog/index.tsx	Cleans up React imports.
electron/renderer/src/components/SaveAsDialog/index.tsx	Uses shared useModalKeyboard; improves name sanitization comment.
electron/renderer/src/components/ModulesPanel/ModuleInputsPanel.tsx	Uses shared captureError utility.
electron/renderer/src/components/ModuleGui/InputControl.tsx	Uses shared captureError utility.
electron/renderer/src/components/ImportModuleDialog/index.tsx	Removes unused kernelReady prop.
electron/renderer/src/components/Icons.tsx	Removes commented-out unused icons.
electron/renderer/src/components/Console/index.tsx	Removes unused export action wiring.
electron/renderer/src/components/Console/Console.test.tsx	Updates test for removed export action.
electron/renderer/src/components/CodeCell/monaco-providers.ts	Uses treeService.listByPath for tree-path completion.
electron/renderer/src/app/useProjectWorkflow.ts	Extends callback deps to include new setter.
electron/renderer/src/app/useKernelSubscriptions.ts	Switches to new onKernelCrashed push channel.
electron/renderer/src/app/useCodeCellsPersistence.ts	Refactors project-ref tracking to an effect.
electron/renderer/src/app/index.tsx	Persists namespace auto-refresh config; updates node field names; renames save handler wiring.
electron/renderer/src/app/HOOKS.md	Removes stale constant reference.
electron/renderer/src/app/constants.ts	Removes unused tree-persist debounce constant.
electron/preload.ts	Renames kernel push subscription to onKernelCrashed.
electron/package.json	Removes unused type packages.
electron/main/pdv-protocol.ts	Exports additional protocol types; clarifies TREE_RESOLVE_FILE usage.
electron/main/module-window-manager.ts	Refactors to BaseWindowManager subclass.
electron/main/module-manager.ts	Replaces dynamic require("fs") with statSync import.
electron/main/menu.ts	Clarifies docs URL versioning comment.
electron/main/kernel-manager.ts	Documents kernelId guard policy.
electron/main/ipc.ts	Adds kernelCrashed push channel; re-exports protocol NodeDescriptor; tightens type exports.
electron/main/ipc-register-kernels.ts	Adds mutex error logging; emits kernelCrashed push; removes dead optional restart/validate branches.
electron/main/index.ts	Adds config default; introduces typed key-mapping helper; renames comm push forwarder; updates window-manager construction.
electron/main/index.test.ts	Updates imports and config expectations; renames push-forwarder usage.
electron/main/gui-viewer-window-manager.ts	Refactors to BaseWindowManager subclass.
electron/main/gui-editor-window-manager.ts	Refactors to BaseWindowManager subclass.
electron/main/config.ts	Adds autoRefreshNamespace with validation/defaults.
electron/main/config.test.ts	Updates config expectations for new field.
electron/main/comm-router.ts	Validates error payload shape; removes deprecated handler shim.
electron/main/base-window-manager.ts	New shared popup-window manager base class.
electron/knip.json	Adds renderer entry points; ignores protocol file for analysis.
ARCHITECTURE.md	Documents new loader/helpers and new base window manager.

[Copilot]

BaseWindowManager.buildConfig requires (key, context), but this override only accepts (alias). TypeScript will flag this as an incompatible override and the file won’t compile. Update the method signature to accept the second parameter (even if unused) or adjust the base-class abstract signature.

[Copilot]

BaseWindowManager.buildConfig is declared as (key, context), but this override only accepts (treePath). This is an incompatible method override and should fail TypeScript compilation. Add the context parameter (or change the base signature if context is not intended to be provided).

Suggested change

	protected buildConfig(treePath: string): ChildWindowConfig {
	return {
	htmlFile: "gui-editor.html",
	windowOptions: {
	width: 1100,
	height: 800,
	title: `GUI Editor: ${treePath}`,
	protected buildConfig(treePath: string, context: GuiEditorContext): ChildWindowConfig {
	return {
	htmlFile: "gui-editor.html",
	windowOptions: {
	width: 1100,
	height: 800,
	title: `GUI Editor: ${context.treePath}`,

[Copilot]

BaseWindowManager.buildConfig requires (key, context), but this override only accepts (treePath). That’s an incompatible override under TypeScript structural typing and should fail compilation. Update the override to accept context as a second argument (even if unused).

[Copilot]

The docstring says the module name is derived from a “stable per-file” hash, but hash(file_path) is salted per interpreter process (and can change across runs). Either reword this to avoid claiming stability, or use a deterministic hash (e.g. hashlib.sha1(file_path.encode()).hexdigest() truncated) if stability across sessions is required.

[Copilot]

on_progress is documented as firing “once per leaf node”, but the implementation calls it for every entry in nodes (including containers and even entries with empty path). Update the docstring to match the actual callback behavior, or adjust the callback invocation to match the documented contract.