docs: add tsdoc comments and plugin distribution guide

deploy/run.ts

@@ -5,6 +5,7 @@
  * channel via webhook when complete. The script is currently disabled and is
  * intended to be run manually by maintainers.
  *
+ * @packageDocumentation
  * Security note: credentials are read from environment variables and the
  * routine deletes remote files before uploading new ones. Double‑check the
  * target host and paths before executing.

packages/app/studio/README.md

@@ -1,6 +1,8 @@
 # OpenDAW Studio
 
 This package contains the web-based user interface for the OpenDAW project.
+TSDoc comments throughout the codebase power the generated API reference for
+plugin authors.
 It uses a central colour system defined in
 [`src/colors.sass`](src/colors.sass) and exposed through the
 [design tokens](../../docs/docs-dev/style/design-tokens.md).

packages/docs/docs-dev/extending/plugin-distribution.md

@@ -0,0 +1,25 @@
+# Plugin Distribution
+
+Plugins can be shared as npm packages or simple static bundles. This guide outlines common
+approaches for distributing Studio plugins built with the SDK.
+
+## npm packages
+
+1. Compile the plugin and publish it to the npm registry under a unique name.
+2. Consumers install the package and register the plugin with `@opendaw/app-studio`.
+3. Provide type definitions and TSDoc comments so the public API is discoverable.
+
+## Static bundles
+
+For lightweight distribution, host the compiled JavaScript and assets on a web server.
+Load the bundle at runtime using the plugin registration API.
+
+## Versioning and updates
+
+Follow semantic versioning so hosts can safely upgrade. Document any breaking changes in
+your release notes and keep TSDoc comments up to date.
+
+## Further reading
+
+- [Plugin guide](./plugin-guide.md)
+- [Testing plugins](./testing-plugins.md)

packages/docs/docs-user/features/devices-and-plugins.md

@@ -21,7 +21,10 @@ OpenDAW loads plugins built with the project's SDK or other compatible Web Audio
 - Traditional desktop formats like VST or Audio Unit may require additional support and are not guaranteed to work.
 - Different plugins may expose unique parameters; test them in your environment to confirm full compatibility.
 
-Interested in building your own plugins? Check out the [plugin guide](../../docs-dev/extending/plugin-guide.md), the [device boxes guide](../../docs-dev/extending/device-boxes.md), and the [plugin host overview](../../docs-dev/extending/plugin-host.md) in the developer documentation.
+Developer-focused API references are generated from the SDK's TSDoc comments. To learn how plugins are packaged and shared,
+see the [plugin distribution guide](../../docs-dev/extending/plugin-distribution.md).
+
+Interested in building your own plugins? Check out the [plugin guide](../../docs-dev/extending/plugin-guide.md) and the [device boxes guide](../../docs-dev/extending/device-boxes.md) in the developer documentation.
 
 For how device controls are connected to automation, see the [parameter adapter guide](../../docs-dev/extending/parameter-adapters.md).
 

packages/studio/core/src/EffectFactory.ts

@@ -1,5 +1,6 @@
 /**
- * Interface definition for effect factories used to construct effect boxes.
+ * Interface describing factories that construct {@link EffectBox} instances
+ * and their associated metadata for menus and device lists.
  *
  * @packageDocumentation
  */
@@ -9,10 +10,6 @@ import {int} from "@opendaw/lib-std"
 import {Project} from "./Project"
 import {EffectBox} from "./EffectBox"
 
-/**
- * Describes a factory capable of constructing an {@link EffectBox} and its
- * associated metadata used in menus and lists.
- */
 export interface EffectFactory {
     /** Default human readable name. */
     get defaultName(): string
@@ -31,6 +28,7 @@ export interface EffectFactory {
      * @param project - Project context for creating boxes.
      * @param unit - Field referencing the host audio unit.
      * @param index - Insert index within the unit's effect chain.
+     * @returns The newly created effect box.
      */
     create(project: Project, unit: Field<EffectPointerType>, index: int): EffectBox
 }

packages/studio/core/src/InstrumentFactories.ts

@@ -1,9 +1,8 @@
 /**
- * Built-in instrument factory descriptors.
+ * Registry of built-in instrument factory descriptors used by the Studio.
  *
  * @packageDocumentation
  */
-
 import {
   AudioFileBox,
   NanoDeviceBox,

packages/studio/sdk/package.json

@@ -1,4 +1,5 @@
 {
+  "//": "Package manifest for the Studio SDK type definitions documented with TSDoc",
   "name": "@opendaw/studio-sdk",
   "version//": "Version is managed by openDAW versioning policy; see packages/docs/docs-dev/build-and-run/versioning.md",
   "version": "0.0.20",

packages/studio/sdk/src/device-api.ts

@@ -9,28 +9,35 @@
  * Interacts with input and output devices such as audio interfaces or MIDI
  * controllers.
  *
+ * @packageDocumentation
  * @public
  */
 export interface DeviceAPI {
   /**
    * Enumerate available input devices.
+   *
+   * @returns A list of device identifiers suitable for {@link setInput}.
    */
   listInputs(): Promise<string[]>;
 
   /**
    * Enumerate available output devices.
+   *
+   * @returns A list of device identifiers suitable for {@link setOutput}.
    */
   listOutputs(): Promise<string[]>;
 
   /**
    * Select the device that should be used for audio input.
    * @param id - Identifier returned from {@link listInputs}.
+   * @returns A promise that resolves once the device is activated.
    */
   setInput(id: string): Promise<void>;
 
   /**
    * Select the device that should be used for audio output.
    * @param id - Identifier returned from {@link listOutputs}.
+   * @returns A promise that resolves once the device is activated.
    */
   setOutput(id: string): Promise<void>;
 }

packages/studio/sdk/src/index.ts

@@ -7,11 +7,19 @@
  * @packageDocumentation
  */
 
+/** Project management utilities for loading and saving sessions. */
 export type { ProjectAPI } from './project-api';
+/** Interface for enumerating and selecting input/output hardware. */
 export type { DeviceAPI } from './device-api';
+/** Transport controls for playback and position. */
 export type { TransportAPI } from './transport-api';
+/** Offline rendering utilities. */
 export type { RenderAPI } from './render-api';
+/** Project persistence and loading. */
 export type { StorageAPI } from './storage-api';
+/** Low-level audio helpers. */
 export type { AudioAPI } from './audio-api';
+/** MIDI messaging helpers. */
 export type { MidiAPI } from './midi-api';
+/** UI integration helpers for custom panels. */
 export type { UiAPI } from './ui-api';

scripts/clean.sh

@@ -1,5 +1,6 @@
 #!/bin/bash
 
+# @packageDocumentation
 # Remove build artifacts and dependencies across the monorepo.
 #
 # Usage:

scripts/install_dependencies.js

@@ -3,6 +3,8 @@
 /**
  * Install required system dependencies for developing openDAW.
  *
+ * @packageDocumentation
+ *
  * Usage:
  *   npm run install:deps
  *